Cerbi.Governance.Runtime 1.1.5

Cerbi.Governance.Runtime

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

Cerbi.Governance.Runtime validates structured log records against Cerbi governance profiles at runtime and annotates them with enforcement metadata (profile used, mode, violations) for downstream analytics, compliance, and ML pipelines.

It’s optimized for high-throughput, in-place mutation, and low allocations, and is safe to embed directly into production services.

Overview

Modern .NET logging stacks — Serilog, NLog, Log4Net, Microsoft.Extensions.Logging, OpenTelemetry Logging / OTLP, Loki / Promtail / Alloy, Fluentd / FluentBit, Seq, ELK / OpenSearch, Graylog, VictoriaLogs, or even plain Journald / syslog — are excellent at collecting and shipping logs, but they don’t enforce governance:

• They don’t know which fields are Required or Forbidden.
• They don’t enforce types or enum values.
• They don’t tag logs that violate policy for downstream scoring or audit.

Cerbi.Governance.Runtime sits inside your app, in front of whichever logging stack you use, and:

• Validates each structured log record against a Cerbi governance profile.
• Annotates the record with structured governance metadata.
• Optionally supports relaxation (bypass enforcement but still tag the event).
• Supports hot-reloaded profiles from files or custom sources.

It is the runtime enforcement engine built on top of Cerbi.Governance.Core.

Key Features

• Field severities

  • Required, Forbidden, Info
  • Drive how each field is evaluated in a profile.

• Type validation Validate field types (e.g. string, int, bool, Guid, DateTime, float) against governance expectations.

• Enum constraints Enforce allowed values per field (e.g. Status: ["Pending", "Approved", "Rejected"]).

• Topic enforcement via [CerbiTopic] Profiles can require topics and limit allowed topics; runtime can infer topics from [CerbiTopic] at call sites.

• Per-profile relaxation Profiles can opt into AllowRelax, allowing producers to mark a log as GovernanceRelaxed = true while still tagging enforcement metadata.

• In-place validation Validate / ValidateInPlace mutate the structured record in place, avoiding extra allocations.

• Hot reload File timestamp polling for governance profiles (via FileGovernanceSource).

• ILogger extensions Extensions for governed logging that automatically add environment metadata such as application id, instance id, region, and cloud provider.

• Extensible sources Plug in your own IRuntimeGovernanceSource implementation (blob, remote API, config store, etc.).

Where It Fits in CerbiSuite

Cerbi.Governance.Runtime is the runtime enforcement layer in the Cerbi ecosystem:

• Cerbi.Governance.Core – shared models, JSON schema, plugin contracts
• Cerbi.GovernanceAnalyzer – compile-time validation (Roslyn analyzers)
• Cerbi.Governance.Runtime – real-time runtime validation & tagging ← this repo
• CerbiStream – logging library that uses runtime enforcement
• CerbiShield Dashboard – create, manage, and deploy governance profiles
• CerbIQ / CerbiSense – downstream routing, scoring, and ML analytics on violations and governance metadata

It does not replace Serilog, NLog, OpenTelemetry, Loki, etc. It governs the logs before they hit those systems.

Installation

dotnet add package Cerbi.Governance.Runtime

Governance JSON Example

A simplified example profile for an Orders domain:

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "Orders": {
      "RequireTopic": true,
      "AllowedTopics": [ "Orders", "Users" ],
      "FieldSeverities": {
        "userId": "Required",
        "email": "Required",
        "password": "Forbidden"
      },
      "FieldTypes": {
        "userId": "string",
        "email": "string"
      },
      "FieldEnums": {
        "Status": [ "Pending", "Approved", "Rejected" ]
      },
      "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.

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.

Hot Reload & Testing

Runtime reload behavior is validated in tests (for example RuntimeGovernanceValidatorReloadTests):

• When the underlying governance file content and timestamp change,
• The next validation cycle detects the change and rebuilds the internal config from the updated profile.

This ensures you can ship governance profile changes without redeploying the app.

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.

How It Plays with Other Logging Stacks

Cerbi.Governance.Runtime is designed to run ahead of your existing logging and observability stack:

• Serilog / NLog / Log4Net / MEL

  • Use runtime validation before writing to sinks.
  • Treat the enriched record as your log payload.

• OpenTelemetry Logging + Collector / OTLP

  • Validate and tag logs before they are exported via OTLP to the collector.
  • Helps you avoid leaking sensitive data into your telemetry backends.

• Loki / Promtail / Grafana Alloy

  • Enforce governance in-app, then ship to Loki.
  • Promtail / Alloy just ship what’s already governed.

• Fluentd / FluentBit / Graylog / Seq / ELK / OpenSearch / VictoriaLogs / Journald / syslog

  • Same pattern: Cerbi governs the log content before your collector/indexer ever sees it.

You don’t have to abandon your existing stack; Cerbi gives you a governance layer on top of what you already use.

FAQ

Does this replace Serilog, NLog, or OpenTelemetry? No. It complements them by enforcing governance rules and tagging violations at runtime.

Does it drop logs that violate policy? The runtime focuses on tagging and annotating structured logs with governance metadata; application-level behavior (e.g., rejection, redaction) can be handled by CerbiStream or your own pipeline using this metadata.

Where do the governance profiles come from? From JSON files conforming to Cerbi.Governance.Core schema — usually created and deployed via CerbiShield.

Can I disable governance entirely? Yes. You can pass isEnabled: () => false into the validator, or omit integration in specific environments.

What about performance? The library is tuned for low allocations and in-place mutation. You should still benchmark in your own environment, but it’s built specifically for high-volume API and worker workloads.

Is this free to use? Yes. Cerbi libraries (including Cerbi.Governance.Runtime and Cerbi.Governance.Core) ship under MIT. CerbiShield and enterprise dashboards are licensed separately.

License

MIT – see LICENSE.

Part of the CerbiSuite – Unified Logging Governance.