CerbiStream Governance Analyzer (Library View)

This README focuses on how this library works technically and how to use it inside your own solutions. For a mixed business/technical overview and a CerbiSuite/Cerbi.io pitch, see the root README.md in this repo.

---

1. Package Role in the Cerbi Ecosystem

CerbiStream.GovernanceAnalyzer is the Roslyn analyzer and governance helper library that:

• loads and normalizes Cerbi governance profiles from JSON;
• exposes helpers for runtime components (GovernanceConfigLoader, GovernanceHelper);
• provides analyzers that validate structured log usage at build time.

It is designed to be:

• consumed by application projects that log via Serilog/NLog/MEL;
• referenced by Cerbi runtime packages (Cerbi.Governance.Runtime, Cerbi.MEL.Governance, CerbiStream);
• aligned with CerbiSuite and CerbiShield governance models as described on https://cerbi.io.

---

2. Core Concepts

2.1 Governance Profiles

Profiles live in JSON files (typically cerbi_governance.json) and define:

• LoggingProfiles – keyed by profile name (PIILog, AuditLog, etc.).
• FieldSeverities – Required, Forbidden, Warning, Info.
• FieldTypes – expected types like Guid, string, int, etc.
• FieldEnums – whitelists for enum‑like string fields.
• EncryptionSettings – required/forbidden encryption modes.
• AllowRelax – whether relaxation is allowed (GovernanceRelaxed = true).

These are Cerbi.Governance.Core models. The analyzer and helpers never invent their own types; they reuse the shared governance contracts.

2.2 Config Loader

GovernanceConfigLoader is the single entry point for profile loading inside the analyzer/runtime combo:

• Discovers the governance JSON file.
• Deserializes into CerbiGovernance.
• Applies convenience semantics (e.g., Encryption → EncryptionSettings).
• Populates an internal dictionary of LogProfile objects.
• Exposes:
  • TryGetProfile(string profileName, out LogProfile profile)
  • GetAllowedLevels(string profileName)
  • CurrentMode (Permissive, WarnOnly, Strict).

2.3 Analyzer Behavior

LogGovernanceAnalyzer (and related analyzers) inspect log invocations such as:

logger.LogInformation("User {userId} logged in", userId);

The analyzer will:

1. Extract {userId} from the message template.
2. Decide which profile is in effect (e.g., PIILog).
3. Look up FieldSeverities["userId"] and type rules.
4. Emit diagnostics when:
   • a required field is missing,
   • a forbidden field is present (password),
   • an enum is invalid (Region not in ["US","EU"]),
   • the type is wrong (userId string vs Guid),
   • relaxation is used where not allowed.

The diagnostics plug into standard Roslyn infrastructure and are consumable by IDEs and CI.

---

3. Installation & Basic Use

3.1 Install From NuGet

dotnet add package CerbiStream.GovernanceAnalyzer

3.2 Add a Governance Config

{ "EnforcementMode": "Strict", "LoggingProfiles": { "PIILog": { "AllowRelax": false, "AllowedLevels": ["Information", "Error"], "FieldSeverities": { "userId": "Required", "password": "Forbidden" }, "FieldTypes": { "userId": "Guid" }, "FieldEnums": { "Region": ["US", "EU"] }, "EncryptionSettings": { "Mode": "AES", "FieldSeverity": "Required" } } } }

Place this file in your app (default: ./cerbi_governance.json or config/cerbi_governance.json).

3.3 Optional: Override File Path

using Cerbi.Governance; [assembly: CerbiGovernanceConfig("config/cerbi_governance.json")]

3.4 IDE & CI Experience

When a developer writes something that violates the profile, such as:

logger.LogInformation("Login {userId} with password {password}", userId, password);

you’ll see analyzer diagnostics like:

• Forbidden field (password),
• Required field missing, if a profile demands a field that is absent,
• Invalid type/enum, if the value does not match governance rules.

These diagnostics behave like any other Roslyn analyzer warning/error.

---

4. Runtime Hooks for CerbiStream / MEL

Although this library is analyzer‑centric, the repo also includes runtime helpers that support CerbiStream and Cerbi.MEL.Governance:

• Runtime/CerbiGovernanceLogger.cs – wraps MEL loggers and applies governance.
• Runtime/GovernanceScoreShipper.cs – channel‑based, high‑throughput shipper for PII‑safe scoring metadata.
• Extensions/CerbiGovernanceBuilder.cs – fluent API for configuring governance + score shipping via ILoggingBuilder.

Example (conceptual):

builder.Logging.AddCerbiGovernance(cerbi => cerbi .WithConfigFile("cerbi_governance.json") .UseProfile("PIILog") .WithBalancedScoreShipping("https://api.cerbi.io/scores", licenseKey));

This path is mostly exercised by the runtime NuGet packages, but the implementation lives here so analyzers and runtime share a codebase.

---

5. Relationship to Cerbi.io / CerbiSuite

This library is part of the CerbiSuite governance story described on https://cerbi.io:

• CerbiStream – runtime logging + governance metadata.
• CerbiStream.GovernanceAnalyzer – build‑time guardrails and config loader.
• Cerbi.Governance.Runtime – shared evaluator + scoring.
• CerbiShield – dashboards, scoring, RBAC, audit history.

For a sales/exec oriented explanation (log spend reduction, redaction posture, dashboard stability, etc.) see the site and the root repo README.md. This file is intentionally focused on how to integrate and extend the analyzer and helpers in code.

---

6. Contributing / Extending

If you want to extend the analyzers:

• look at LogGovernanceAnalyzer.cs and test files under CerbiStream.GovernanceAnalyzer-Tests;
• use Cerbi.Governance.Core models wherever possible;
• add tests for new diagnostics in the test project.

If you want to modify runtime pieces (shipper, builder, logger providers), ensure:

• you keep the governance contracts consistent with Cerbi.Governance.Core;
• you do not introduce hard dependencies on non‑MIT components in the runtime paths;
• you keep performance characteristics aligned with expectations documented in PRODUCTION_READY_SUMMARY.md and THROUGHPUT_ANALYSIS.md.