Cerbi.Governance.Runtime 1.1.6

Cerbi.Governance.Runtime

🛡️ Real-time governance enforcement & scoring for structured logging in .NET

Cerbi.Governance.Runtime validates structured log records against Cerbi governance profiles at runtime, annotates them, computes optional governance score impact, and (optionally) ships compact score events asynchronously to CerbiShield.

Added Capabilities (Scoring & Shipping)

Runtime Scoring

When profile Scoring.Enabled = true:

• Violations converted to impact via severity weights (defaults: Info=0.5, Warn=2.0, Error=5.0).
• Overrides via WeightsBySeverity.
• Plugin impacts multiplied by PluginWeights[ruleId] when present (default multiplier 1.0).
• Relaxed events (GovernanceRelaxed = true + profile AllowRelax) force impact to 0 but remain tagged.

Annotated keys:

• GovernanceScoreImpact (double)
• GovernanceScoringVersion (optional)
• Existing: GovernanceViolations, GovernanceProfileUsed, GovernanceMode, GovernanceEnforced, GovernanceRelaxed.

Score Shipping (Non-Blocking)

Configure ScoreShippingOptions + initialize:

var shipOpts = new ScoreShippingOptions {
    Enabled = true,
    LicenseAllowsScoring = true,
    Endpoint = "https://tenant/api/governance/scores",
    BatchSize = 50,
    FlushInterval = TimeSpan.FromSeconds(5)
};
var shipper = new ScoreShipper(shipOpts);
LoggerGovernanceExtensions.InitializeScoreShipping(shipOpts, shipper);

Channel-based batching ensures logging hot path is not blocked.

Score event model (GovernanceScoreEvent) includes: AppName, Environment, Timestamp, ScoreImpact, GovernanceRelaxed, Violations[].

Governance JSON Example with Scoring

A simplified example profile for an Orders domain:

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "Orders": {
      "FieldSeverities": { "userId": "Required", "password": "Forbidden" },
      "Scoring": {
        "Enabled": true,
        "WeightsBySeverity": { "Error": 5, "Warn": 2 },
        "PluginWeights": { "plugin.teamid.required": 2.0 },
        "Version": "1.0"
      },
      "AllowRelax": true
    }
  }
}

Profiles are usually authored and versioned via Cerbi.Governance.Core schema and surfaced in CerbiShield.

Usage

Manual Validation (In-Place)

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

var validator = new RuntimeGovernanceValidator(
    isEnabled: () => true,
    profileName: "Orders",
    source: new FileGovernanceSource("cerbi_governance.json"));

var record = new Dictionary<string, object?>
{
    ["userId"] = "abc123",
    ["Status"] = "Failed"
};

validator.ValidateInPlace(record);

// record now includes:
// - GovernanceProfileUsed
// - GovernanceEnforced
// - GovernanceMode
// - GovernanceViolations (if any)

The record stays fully usable as a standard structured log object — just with extra governance metadata attached.

ILogger Extension Usage

You can wire the validator into your existing ILogger pipeline:

// Example signature; actual extensions live in LoggerGovernanceExtensions
logger.LogInformation(validator, "Processing order {OrderId}", Guid.NewGuid().ToString());

The extension will:

• Apply runtime governance using the configured profile.
• Enrich the log with governance metadata and environment context.
• Forward the resulting structured log to whatever sinks you already use (Serilog, NLog, OTEL exporters, Seq, Loki, ELK/OpenSearch, Fluentd, etc.).

Environment Metadata

LoggerGovernanceExtensions can automatically enrich logs with environment metadata, including:

• ApplicationId

  • From CERBI_APP_ID
  • Default: "MyApp"

• InstanceId

  • From machine name (host identifier)

• Region

  • From CLOUD_REGION
  • Default: "unknown-region"

• CloudProvider

  • Inferred as one of: AWS, GCP, Azure, or OnPrem (best-effort heuristic)

This enrichment is designed for downstream correlation in systems like Loki, Seq, Elastic/OpenSearch, Graylog, VictoriaLogs, or OTEL-backed pipelines.

Relaxation Mode

Sometimes you want to temporarily bypass strict governance (e.g., debugging or emergencies) but still record that this happened.

Profiles with AllowRelax: true let producers set GovernanceRelaxed = true. In that case:

• Strict enforcement can be skipped.
• The record is still tagged with governance metadata, such as:

{
  "GovernanceRelaxed": true,
  "GovernanceEnforced": false,
  "GovernanceProfileUsed": "Orders"
}

This allows CerbIQ / CerbiSense and your auditors to see where and when governance was relaxed.

Performance Notes

Cerbi.Governance.Runtime is built with high-throughput services in mind:

• Uses stackalloc for required-field tracking where appropriate.
• Caches compiled profile rules for faster evaluation.
• Avoids reflection unless topic inference requires it.
• Performs in-place mutation to minimize extra allocations.

The intent is to keep governance overhead low enough to use on every log event in high-volume systems.

Extensibility

The runtime engine is source-agnostic. Implement IRuntimeGovernanceSource to load governance profiles from wherever you like (files, blob storage, feature-flag system, HTTP API, etc.):

public interface IRuntimeGovernanceSource
{
    CerbiGovernance? Load();
    DateTime GetLastUpdatedUtc();
}

Provided implementation:

• FileGovernanceSource – loads from a local JSON file and uses timestamp polling for hot reload.

Implement IRuntimeGovernancePlugin to contribute PluginImpactResult items for inline scoring.

License

MIT

Part of CerbiSuite – Unified Logging Governance.