Cerbi.Governance.Core 2.2.29

Cerbi.Governance.Core

v2.2.0 — The canonical governance engine for the CerbiShield logger ecosystem.

Cerbi.Governance.Core provides compile-time and runtime governance enforcement for structured logging across .NET applications. It is used by all CerbiShield logger plugins (CerbiStream, Serilog, MEL, NLog) and the CerbiShield Dashboard to define, validate, and score governance profiles.

Why Canonical Profile

Prior to v2.2.0, the codebase maintained two incompatible profile models:

This dual-model problem meant:

• Dashboard rule templates produced Profile JSON that loggers couldn't read
• Runtime loggers used LogProfile JSON that the Dashboard couldn't render
• Two serialization formats, two validation paths, two sets of bugs

v2.2.0 eliminates the legacy model. The entire stack — Dashboard → GovernanceApi → GovernanceRuntime → Governance.Core → Logger plugins — now uses a single canonical Profile object. One JSON format. One validation path. One source of truth.

Key Features

• Profile — Single canonical governance profile model with strongly-typed enums
  • SeverityLevel enum: Info, Warn, Error, Forbidden
  • FieldType enum: String, Int, Decimal, Guid, DateTime, Bool, Object, Array
  • ProfileStatus enum: Draft, Published
  • EncryptionMode enum: None, Base64, AES
• GovernanceConfigLoader — Static loader that reads canonical Profile JSON from file, with FileSystemWatcher hot-reload
• GovernanceHelper — Runtime validation of log entries against loaded Profile (required fields, disallowed fields, field types, enum constraints, encryption, scoring)
• GovernanceValidator — Structural validation of Profile definitions (name, appName, version, required properties)
• ScoringSettings — Configurable scoring weights by severity, plugin weights, scoring version
• Roslyn Helpers — ExtractLoggedFields for compile-time field analysis from Dictionary<string, object> expressions

Quickstart: Using GovernanceConfigLoader

using Cerbi.Governance;
using Cerbi.Governance.Core.Models;

// Load a canonical governance profile from a JSON file
GovernanceConfigLoader.SetGovernanceFilePath("cerbi_governance.json");

// Access the currently loaded profile
Profile? profile = GovernanceConfigLoader.CurrentProfile;
if (profile != null)
{
    Console.WriteLine($"Profile: {profile.Name} (app: {profile.AppName})");
    Console.WriteLine($"Version: {profile.Version}, Status: {profile.Status}");
    Console.WriteLine($"Required fields: {profile.RequiredFields?.Count ?? 0}");
    Console.WriteLine($"Disallowed fields: {profile.DisallowedFields?.Count ?? 0}");
    Console.WriteLine($"Scoring enabled: {profile.Scoring?.Enabled ?? false}");
}

Validating a Log Entry

var logData = new Dictionary<string, object>
{
    { "requestId", Guid.NewGuid() },
    { "userId", "u-12345" },
    { "timestamp", DateTime.UtcNow }
};

bool isValid = GovernanceHelper.TryValidate("my-profile", logData, out var errors, out var score);

if (!isValid)
{
    foreach (var error in errors)
        Console.WriteLine($"  Violation: {error}");
    Console.WriteLine($"  Score penalty: {score}");
}

Canonical Profile JSON

All governance profiles use this flat JSON schema — the same format produced by the CerbiShield Dashboard rule editor and consumed by all runtime loggers:

{
  "name": "PII Protection",
  "appName": "my-service",
  "version": "1.0.0",
  "status": "Published",
  "metadata": {
    "description": "Prevents PII leakage in application logs",
    "owner": "security-team",
    "createdAt": "2025-01-15T00:00:00Z"
  },
  "tags": ["pii", "compliance", "hipaa"],
  "allowRelax": false,
  "requiredFields": ["requestId", "timestamp", "correlationId"],
  "disallowedFields": ["ssn", "creditCardNumber", "password"],
  "fieldSeverities": {
    "requestId": "Error",
    "userId": "Warn",
    "ssn": "Forbidden",
    "debugInfo": "Info"
  },
  "fieldTypes": {
    "requestId": "Guid",
    "userId": "String",
    "timestamp": "DateTime",
    "retryCount": "Int",
    "amount": "Decimal",
    "isAdmin": "Bool"
  },
  "enums": {
    "environment": ["dev", "staging", "production"],
    "logLevel": ["Debug", "Info", "Warning", "Error", "Critical"]
  },
  "encryption": {
    "mode": "AES",
    "encryptedFields": ["ssn", "email"]
  },
  "scoring": {
    "enabled": true,
    "weightsBySeverity": {
      "Error": 5.0,
      "Warn": 1.0,
      "Info": 0.1
    },
    "pluginWeights": {},
    "version": "1.0.0"
  }
}

Architecture

┌─────────────────────────────────────────────────────────┐
│  CerbiShield Dashboard (Next.js)                        │
│  → Creates/edits Profile JSON via rule editor            │
│  → Reads Profile from GovernanceStore API                │
└────────────────────────┬────────────────────────────────┘
                         │ canonical Profile JSON
┌────────────────────────▼────────────────────────────────┐
│  Cerbi.GovernanceRuntime (v2.0.0)                        │
│  → Loads Profile via FileGovernanceSource                │
│  → Validates at runtime via CompiledProfile.Build        │
└────────────────────────┬────────────────────────────────┘
                         │ uses
┌────────────────────────▼────────────────────────────────┐
│  Cerbi.Governance.Core (v2.2.0)     ← YOU ARE HERE       │
│  → GovernanceConfigLoader: loads Profile from JSON file  │
│  → GovernanceHelper: validates log data against Profile   │
│  → GovernanceValidator: validates Profile structure       │
│  → Models: Profile, SeverityLevel, FieldType, etc.       │
└────────────────────────┬────────────────────────────────┘
                         │ consumed by
┌────────────────────────▼────────────────────────────────┐
│  Logger Plugins                                          │
│  → CerbiStream, Serilog, MEL, NLog                       │
│  → Load Profile → validate logs → ship scoring events    │
└─────────────────────────────────────────────────────────┘

Comparison: Core vs Runtime vs Validator

Profile Model Reference

public class Profile
{
    public string? Name { get; set; }
    public string? AppName { get; set; }
    public string? Version { get; set; }
    public ProfileStatus Status { get; set; }           // Draft | Published
    public ProfileMetadata? Metadata { get; set; }
    public List<string>? Tags { get; set; }
    public bool AllowRelax { get; set; }
    public List<string>? AllowedTopics { get; set; }
    public List<string>? RequiredFields { get; set; }
    public List<string>? DisallowedFields { get; set; }
    public Dictionary<string, SeverityLevel>? FieldSeverities { get; set; }  // Info|Warn|Error|Forbidden
    public Dictionary<string, FieldType>? FieldTypes { get; set; }           // String|Int|Decimal|Guid|DateTime|Bool|Object|Array
    public Dictionary<string, List<string>>? Enums { get; set; }
    public Encryption? Encryption { get; set; }
    public ScoringSettings? Scoring { get; set; }
}

Breaking Changes in v2.2.0

• GovernanceConfigLoader.CurrentProfile is now Profile? (was accessed via TryGetProfile with LogProfile)
• GovernanceConfigLoader.SetCurrentProfileForTest(Profile) — parameter changed from LogProfile to Profile
• GovernanceHelper.TryValidate uses Profile.FieldSeverities as Dict<string, SeverityLevel> (was Dict<string, string>)
• GovernanceHelper.TryValidate uses Profile.FieldTypes as Dict<string, FieldType> (was Dict<string, string>)
• GovernanceHelper.TryValidate uses Profile.Enums (was FieldEnums in legacy)
• Removed: TryGetProfile, GetAllowedLevels, GovernanceMode from GovernanceConfigLoader
• Legacy models LogProfile and CerbiGovernance still exist in the codebase but are no longer used by ConfigLoader, Helper, or Validator

Installation

dotnet add package Cerbi.Governance.Core --version 2.2.0

License

MIT