CerbiStream.GovernanceAnalyzer 1.1.4

CerbiStream Governance Analyzer

🛡️ CerbiStream Governance Analyzer

CerbiStream-GovernanceAnalyzer is a high-performance, plugin-extensible governance engine for structured logging in .NET. It enables both runtime enforcement and compile-time analysis (via Roslyn Analyzer) to ensure logging consistency, security, and observability compliance.

✅ What’s New?

• 🔄 Live Reloading of JSON governance configs
• 🧠 Plugin Architecture — inject dynamic validation rules (per environment, compliance, etc.)
• 🧩 Per-field Type & Enum Enforcement
• 🚫 DisallowedFields Support — prevent sensitive or restricted data from being logged
• 🔐 Governance Modes: Permissive, WarnOnly, Strict
• 📊 Impact Scoring for governance violations (coming soon)
• 🔍 Roslyn Analyzer to catch issues at build-time

📦 Installation

dotnet add package CerbiStream.GovernanceAnalyzer

---CerbiStream-GovernanceAnalyzer is a Roslyn-based static analysis tool designed to enforce structured logging standards within applications using CerbiStream. It ensures that log messages adhere to governance rules defined in JSON configurations, reducing runtime validation overhead and improving developer experience.

🔥 Why Use CerbiStream-GovernanceAnalyzer?

• Compile-Time Log Validation – Prevents misformatted logs before deployment.
• Structured Logging Enforcement – Ensures consistent log structures across teams.
• Customizable Rules via JSON – Allows organizations to define mandatory fields for logs.
• Seamless Integration with CerbiStream – Works alongside CerbiStream for log governance.
• Lightweight & Fast – Runs at build time, avoiding runtime performance impact.

🚀 Installation

To add CerbiStream-GovernanceAnalyzer to your project, install it via NuGet:

 dotnet add package CerbiStream.GovernanceAnalyzer

Or update your .csproj:

<ItemGroup>
    <PackageReference Include="CerbiStream.GovernanceAnalyzer" Version="1.0.0" />
</ItemGroup>

📌 How It Works

1. Governance Rules via JSON

   • Define required and optional logging fields in a cerbi_governance.json file.
   • Example:

   {
      "LoggingProfiles": {
          "Default": {
              "RequiredFields": ["Timestamp", "LogLevel", "Message", "ApplicationId"],
              "OptionalFields": ["UserId", "TransactionId"]
          }
      }
   }
   

2. Static Analysis at Build-Time

   • The analyzer verifies that logs match the governance profile during compilation.
   • Example of a valid log:

   logger.LogInformation("User login successful | UserId: {UserId}, Timestamp: {Timestamp}", userId, DateTime.UtcNow);
   

   • Example of an invalid log (missing required fields):

   logger.LogInformation("User login successful"); // ❌ Missing required metadata
   

   • The build will fail with a warning/error indicating missing required fields.

3. Enforce or Warn Mode

   • Choose whether governance rules should fail the build (Error Mode) or just warn developers (Warning Mode).
   • This can be controlled via the cerbi_governance.json file.

🛠️ Configuration Options

📖 Example Usage

1️⃣ Enabling Governance in CerbiStream

In your Program.cs:

var serviceProvider = new ServiceCollection()
    .AddLogging(builder =>
    {
        builder.AddCerbiStream(options =>
        {
            options.EnableGovernance();
        });
    })
    .BuildServiceProvider();

2️⃣ Running the Governance Analyzer

The analyzer automatically runs during the build process. If any logs do not meet governance standards, you’ll see build errors or warnings.

🎯 Future Enhancements

• Integration with CI/CD Pipelines – Enforce logging rules in GitHub Actions/Azure DevOps.
• Dashboard for Governance Management – UI to configure log governance dynamically.
• Multi-Project Support – Apply governance rules across microservices.

📜 License

CerbiStream-GovernanceAnalyzer is open-source under the MIT License.

📬 Contact & Contributions

We welcome contributions! Submit an issue or a pull request on GitHub.

🧰 Runtime Usage

🔧 1. Governance Config Example

{
{
  "Version": "1.0",
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "API": {
      "RequiredFields": ["Timestamp", "LogLevel", "Message", "ApplicationId"],
      "OptionalFields": ["UserId", "TransactionId"],
      "DisallowedFields": ["ssn", "creditCardNumber", "socialSecurityNumber"],
      "AllowedLevels": ["Information", "Warning", "Error"],
      "Encryption": "None",
      "FieldTypes": {
        "ApplicationId": "Guid"
      },
      "FieldEnums": {
        "Environment": ["Development", "Staging", "Production"]
      }
    }
  }
}

🛠 How to Use

GovernanceConfigLoader.SetGovernanceFilePath("config/cerbi_governance.json");
var isValid = GovernanceHelper.TryValidate("PIILog", logData, out var errors);

📄 Requires a governance config file. See config/cerbi_governance.json for format.

✅ Summary

🧪 2. Validate a Log Entry at Runtime

var logData = new Dictionary<string, object>
{
    { "Timestamp", DateTime.UtcNow },
    { "LogLevel", "Error" },
    { "Message", "Order failed" },
    { "ApplicationId", Guid.NewGuid() }
};

var valid = GovernanceHelper.TryValidate("API", logData, out var errors);

if (!valid)
{
    Console.WriteLine("Governance violations:");
    errors.ForEach(Console.WriteLine);
}

❌ Disallowed Fields

You can now explicitly block fields that must not appear in any log entry. This helps enforce compliance with security, privacy, or internal data handling policies (e.g., GDPR, HIPAA).

📄 Governance Config Example

{
  "LoggingProfiles": {
    "PIILog": {
      "RequiredFields": ["Timestamp", "Message", "UserId"],
      "DisallowedFields": ["SSN", "CreditCardNumber", "MedicalRecordId"],
      "AllowedLevels": ["Information", "Error"]
    }
  }
}

🧩 Flat JSON-Only Governance Mode

CerbiStream.GovernanceAnalyzer uses a single, flat JSON file for rule configuration.

📘 See cerbi_governance.schema.json for full validation schema used by the dashboard and Monaco Editor.

No tenants. No runtime switching. No external lookups.
Just fast, lightweight governance.

⚙️ Runtime Enforcement

• 🔄 Live JSON reload (no restart)
• 🧩 Plugins (validate based on environment, team, user, etc.)
• 🔐 Field-level encryption enforcement
• 🧠 Impact scoring (optional)

🧪 Compile-Time Enforcement (Roslyn)

• 🔍 Catch missing fields at build time
• ❌ Warn on disallowed log levels
• ✅ Extensible for IDE feedback

✅ Example Governance Config (cerbi_governance.json)

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "PIILog": {
      "RequiredFields": ["userId", "ssn"],
      "AllowedLevels": ["Information", "Error"],
      "Encryption": "AES"
    },
    "SecurityLog": {
      "RequiredFields": ["userId", "IPAddress"],
      "AllowedLevels": ["Error", "Critical"],
      "Encryption": "AES"
    }
  }
}

🔌 Governance Plugins (Extend Enforcement)

📄 Interface

public interface ICustomGovernancePlugin
{
    string Id { get; }
    string Description { get; }
    PluginCategory Category { get; }
    string[] AppliesToProfiles { get; }

    bool Validate(string profileName, Dictionary<string, object> logData, out List<string> failures, out int impactScore);
}

⚙️ Example Plugin

public class TeamIdPlugin : ICustomGovernancePlugin
{
    public string Id => "plugin.teamid.required";
    public string Description => "Requires TeamId when Environment = Production";
    public PluginCategory Category => PluginCategory.Security;
    public string[] AppliesToProfiles => new[] { "*" };

    public bool Validate(string profile, Dictionary<string, object> logData, out List<string> failures, out int impactScore)
    {
        failures = new();
        impactScore = 0;

        if (logData.TryGetValue("Environment", out var env) &&
            env?.ToString()?.Equals("Production", StringComparison.OrdinalIgnoreCase) == true)
        {
            if (!logData.ContainsKey("TeamId"))
            {
                failures.Add("MissingField: TeamId is required in Production");
                impactScore = 5;
                return false;
            }
        }

        return true;
    }
}

💡 Register your plugin once on startup:

GovernancePluginManager.Plugin = new TeamIdPlugin();

🧪 Developer Features

💡 Example Governance Violation

MissingField: ApplicationId
InvalidEnum: Environment must be one of [Development, Staging, Production]
InvalidType: ApplicationId expected guid

🤝 CerbiStream + Governance Analyzer

Use both for complete log compliance, structure, and real-time observability

dotnet add package CerbiStream
dotnet add package CerbiStream.GovernanceAnalyzer

• CerbiStream handles routing, structure, and metadata
• GovernanceAnalyzer ensures enforcement and correctness

📍 Roadmap

📬 Contact & Community

• 🌐 Website: Cerbi-CerbiStream
• 📦 NuGet: GovernanceAnalyzer on NuGet
• 📫 Email: thomasvnelson@live.com

🔖 MIT Licensed · 💬 Built for real developers.
🧠 Structured. Secure. Governed. Fast.