Cerbi.Governance.Core 2.0.20

Cerbi.Governance.Core

Lightweight shared governance contracts for runtime validation, analyzer enforcement, redaction rules, scoring metadata, and structured logging governance across the CerbiSuite ecosystem.

Cerbi.Governance.Core provides the canonical models, JSON schema, profile versioning, scoring weights, and plugin contracts used by:

• CerbiStream (logging + runtime enforcement)
• Cerbi.GovernanceAnalyzer (compile-time enforcement via Roslyn)
• Cerbi.Governance.Runtime (real-time validator)
• CerbiShield Dashboard (governance creation, deploy, and reporting)
• CerbIQ & CerbiSense (downstream scoring, routing, ML)

It is intentionally small, dependency-light, cross-compatible, and safe to reference from analyzers, runtime services, plugins, and distributed .NET apps.

Why This Exists

Traditional .NET loggers — Serilog, NLog, Log4Net, MEL, OpenTelemetry Logging, Seq, Loki, etc. — provide excellent observability, but none enforce governance:

• They cannot block or tag forbidden fields (SSN, CreditCardNumber, Email).
• They cannot prove compliance for GDPR/HIPAA/SOC2.
• They cannot redline violations at compile-time.
• They cannot guarantee profile consistency across teams and microservices.
• They cannot apply weighted scoring for violation impact.

Cerbi.Governance.Core solves this by defining a shared governance contract for redaction, required fields, forbidden fields, tagging, encryption rules, rule severity, and optional scoring weights — used everywhere from analyzers to runtime services.

Think of it as the “governance schema & rule engine spine” of the Cerbi ecosystem.

Key Features

• Canonical governance model

  • CerbiGovernance, LogProfile, FieldRules, EncryptionSettings, ScoringSettings, and typed enums.

• Governance JSON Schema Versioned, strict schema for rule sets, under Schema/.

• Optional scoring metadata

  • scoring.enabled
  • scoring.weightsBySeverity (Info/Warn/Error → number)
  • scoring.pluginWeights (ruleId → number)
  • scoring.version (semver for scoring model)

• Sample profiles Ready-to-use examples under Samples/.

• Runtime validator contracts

  • IGovernanceValidator
  • GovernanceValidator (lightweight real-time validator)

• Plugin support Extend governance using ICustomGovernancePlugin (e.g., TeamIdPlugin).

• GovernanceConfigLoader Safe config loader with:

  • case-insensitive parsing
  • minimal allocations
  • injectable logging (GovernanceConfigLoader.Log)
  • graceful error handling

• Analyzer-safe Library is safe to load inside Roslyn analyzers (no heavyweight dependencies).

• Versioned profile support Enables future schema evolution without breaking deployed apps.

• Zero external dependencies Dependency-light and analyzer-friendly.

Where This Fits in CerbiSuite

CerbiShield Dashboard (rule creation, versioning, deploy)
               │
               ▼
Cerbi.Governance.Core  <— shared models, schema, plugin contracts
               │
 ┌─────────────┼─────────────────────────────┐
 │             │                             │
 ▼             ▼                             ▼
Cerbi.GovernanceAnalyzer   Cerbi.Governance.Runtime   CerbiStream (logging)
(compile-time rules)       (runtime validation)        (logging + tagging)

Downstream:

• CerbIQ → routing, metadata aggregation, violation scoring
• CerbiSense → ML analysis, anomaly detection, trend forecasting

How It Compares (SEO-friendly)

This library does not replace existing loggers or collectors.

Instead, it adds governance where they cannot:

Cerbi adds governance on top of whichever logger or collector you already use.

Installation

dotnet add package Cerbi.Governance.Core

Assembly Attribute (Strongly Recommended)

Point your project to its governance JSON file:

using Cerbi.Governance;

[assembly: CerbiGovernanceConfig("cerbi_governance.json")]

This supports analyzers, runtime validators, and profile discovery.

Quickstart: Runtime Validation

using Cerbi.Governance.Core.Validation;
using System.Text.Json;

// 1. Load your governance profile (you control this)
var profile = /* parse using GovernanceConfigLoader or your own logic */;

// 2. Sample log payload
string payload = @"{ ""Email"": ""john.doe@example.com"", ""Amount"": 250 }";
var json = JsonDocument.Parse(payload);

// 3. Validate
var validator = new GovernanceValidator();
var result = validator.Validate(profile, json.RootElement);

if (result.Violations.Any())
{
    Console.WriteLine("Governance violations detected:");
    foreach (var v in result.Violations)
        Console.WriteLine($" - {v.Message}");
}

Quickstart: Using GovernanceConfigLoader

GovernanceConfigLoader.Log = s => logger.LogInformation(s);

var loader = new GovernanceConfigLoader("cerbi_governance.json");
var config = loader.Load();

Console.WriteLine($"Loaded {config.Profiles.Count} profiles.");

Safe-by-default:

• Gracefully handles missing files
• Gracefully handles parse failures
• Converts JSON case-insensitively
• Does not throw by default

Example Governance Profile (with scoring)

{
  "name": "payments-default",
  "appName": "PaymentsService",
  "version": "1.2.0",
  "status": "Published",
  "metadata": {
    "description": "Default governance for payment logs",
    "owner": "payments-team",
    "createdAt": "2024-11-01T10:00:00Z"
  },
  "requiredFields": [ "operation", "appName" ],
  "disallowedFields": [ "ssn", "creditCardNumber" ],
  "fieldSeverities": {
    "customerId": "Error",
    "region": "Warn"
  },
  "scoring": {
    "enabled": true,
    "weightsBySeverity": {
      "Info": 0.5,
      "Warn": 1.0,
      "Error": 5.0
    },
    "pluginWeights": {
      "CERBI_TEAM_ID": 2.0
    },
    "version": "1.0.0"
  }
}

Re-Baseline: Build, Test, Validate

1. Verify SDK

dotnet --info

2. Build and Test

dotnet restore
dotnet build -c Release
dotnet test -c Release

3. Optional Benchmarks

scripts/bench.sh   # Linux/macOS
scripts/bench.ps1  # Windows

Contributing

• dotnet test to run tests
• All warnings treated as errors in CI
• Roslyn-analyzer safe — keep dependencies minimal
• PRs welcome

Roadmap

• Additional unit test coverage (helpers, plugins)
• More sample governance profiles
• Fully unify System.Text.Json usage
• Optional structured logger for config loader
• Future versioned schema evolution
• Expanded scoring strategies (per-field impact, decay models)

License

MIT — see LICENSE.