CerbiStream.GovernanceAnalyzer 1.1.30

CerbiStream Governance Analyzer

🛡️ What is CerbiStream Governance Analyzer?

A high‑performance Roslyn analyzer that enforces your organisation’s structured‑logging governance rules at build‑time – before code reaches production. It ships with a tiny runtime helper (optional) plus hot‑reloading JSON configs so you can evolve policy without redeploying.

• Prevents PII leakage and missing telemetry fields.
• Guarantees encryption settings for sensitive profiles.
• Emits actionable build errors (CERBI‑IDs) your CI pipeline can fail on.

One package. Zero code changes. Add the NuGet, drop a cerbi_governance.json, hit build.

🧠 For Stakeholders

Cerbi helps your developers log securely, consistently, and in compliance with privacy laws — automatically.

If a developer accidentally logs something they shouldn’t (like an email, password, or ID), Cerbi catches it before the code is deployed. It’s like spellcheck for logs, preventing mistakes before they go live.

Cerbi is a seatbelt for your logs: invisible until something goes wrong — and essential when it does.

🚀 Quick‑start

Why build‑time? Catch errors before they ship. Compilation fails fast, blocking merges and eliminating "fix‑it‑in‑prod" hot‑patches.

# inside your project
$ dotnet add package CerbiStream.GovernanceAnalyzer

Place cerbi_governance.json in your repo root (or anywhere – set the path via MSBuild/Env). Example profile:

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "default": {
      "RequireTopic": true,
      "AllowedTopics": ["Auth","Payments"],
      "FieldSeverities": {
        "userId": "Required",
        "password": "Forbidden"
      },
      "EncryptionSettings": {
        "Mode": "AES",
        "FieldSeverity": "Required"
      }
    }
  }
}

Write logs the usual way. The analyzer handles the rest.

logger.LogInformation(new {
    Topic   = "Auth",        // ✅ whitelisted
    userId  = userId,
});

Missing required field? CERBI001. Wrong topic? CERBI020/021. CI fails – issue caught before merge.

Want even faster logging?

logger.LogInformation("User login ok");

This works too — as long as your governance rules don’t require specific structured fields. We support both!

Note: Logs passed via new {} become structured log fields. Cerbi uses this structure to validate governance rules, like required fields, forbidden fields, and allowed topics. If you use plain text ("string only"), governance validation is skipped — use only when you don’t need governance enforcement.

✅ Real-world Usage Examples

1. Implicit (no attributes)

logger.LogInformation(new {
    Topic = "Payments",
    userId = userId,
    email = "demo@domain.com"
});

Works out-of-the-box. The analyzer validates against the default profile.

2. Using [CerbiTopic("...")] to set topic for class

using CerbiStream.Governance;

[CerbiTopic("Auth")]
public class LoginService
{
    private readonly ILogger<LoginService> _logger;

    public void Login(Guid userId)
    {
        _logger.LogInformation(new { userId }); // Topic inferred = "Auth"
    }
}

3. Relax() for incident/triage bypass

logger.Relax().LogWarning(new {
    Topic = "Auth",
    rawPayload = "{ data }"
});

Triggers CERBI000. Allowed only if AllowRelax: true.

4. Override topic at log-site

[CerbiTopic("Users")]
public class AccountController
{
    public void Reset()
    {
        _logger.LogInformation(new {
            Topic = "Users:Reset",
            userId,
            reason
        });
    }
}

5. Optional runtime validation (for tests / API gateways)

var result = GovernanceHelper.TryValidate("Payments", logDict, out var errors);

6. Incorrect usage (will fail build)

logger.LogInformation("hello world");           // CERBI021 – missing Topic
logger.LogInformation(new { Topic = "XYZ" });   // CERBI020 – invalid topic

✨ Feature Matrix

*Runtime checks live in GovernanceHelper.TryValidate() – optional for API‑level validation/tests.

🖇️ Topic Governance

Cerbi lets you declare a default topic once per class (or file) so individual calls stay clean.

using CerbiStream.Governance;

[CerbiTopic("Auth")]
public class LoginController
{
    private readonly ILogger<LoginController> _log;

    public void SignIn(Guid userId)
    {
        _log.LogInformation(new { userId }); // Topic inferred = "Auth"
    }
}

Need to override inside a specific method? just add the property:

_log.LogInformation(new { Topic = "Auth:Reset", userId, reason });

📄 Diagnostics Cheat‑sheet

All IDs use the CERBI‑prefix so you can filter easily in IDEs & pipelines.

🔌 Extensibility

• Plugin interface (ICustomGovernancePlugin) – add bespoke rules (e.g., team‑id in prod, audit score).
• Live reload – JSON file watcher reloads policy without restarting.

🏆 Scoring (Phase 2 sneak‑peek)

Every violation will soon emit an impact score (0‑10). CI can fail on cumulative risk, not just presence of errors. Build output will include a summary table:

CERBI tally   :  4 errors   1 warning   26 score
Gate threshold: <=30  ✅ pass

Scoring is runtime‑friendly too—serialised as GovernanceScore for SIEM dashboards.

📚 Further reading

• Detailed schema – cerbi_governance.schema.json
• Blog post – "Shift‑Left Logging Governance with Roslyn" (coming soon)
• Governance FAQ – https://cerbi.systems/governance-faq

📦 Packaging & CI

📢 License & Contact

• License: MIT
• NuGet Packages:
  • CerbiStream.GovernanceAnalyzer
  • CerbiStream
• Website: https://cerbi.systems
• Email: mailto:hello@cerbi.io
• Discord: https://discord.gg/cerbi

Secure • Structured • Compliant

CerbiStream Governance Analyzer — © Cerbi LLC 2025