CerbiStream.GovernanceAnalyzer 1.2.1

Cerbi.NLog.GovernanceAnalyzer

Cerbi Governance Analyzer for NLog — compile-time log validation using Roslyn analyzers and JSON-based governance profiles + realtime runtime governance validation with high-throughput async score shipping.

This package lets you enforce logging governance rules for NLog at build time and runtime, so bad log patterns never make it to production, and governance violations are automatically scored and shipped to centralized observability platforms.

Part of the Cerbi Suite for governed logging, observability, and compliance.

📆 What It Does

Cerbi.NLog.GovernanceAnalyzer provides dual-layer governance:

Compile-Time (Roslyn Analyzer)

• ✅ Enforce required fields (e.g., userId, operationId)
• ❌ Block or warn on forbidden fields (e.g., ssn, creditCardNumber)
• 🧠 Validate field types, enums, and encryption settings
• 🔍 Violations surfaced as compiler diagnostics in Visual Studio, Rider, CI/CD

Runtime (GovernanceScore Target)

• 🔄 Realtime validation: automatically validates every log against governance profiles
• 📊 Impact scoring: computes violation severity (MissingField=5pts, Forbidden=10pts, etc.)
• 📡 Async shipping: batched HTTP POST with retry, backoff, and license gating
• ⚡ High throughput: 100k+ events/sec, non-blocking enqueue, Channel-based queue
• 🎯 Auto-enrichment: opt-in feature attaches scores automatically

🔧 Example – NLog Usage & Diagnostics

_logger.Info("userId={0}, ssn={1}", "abc-123", "123-45-6789");

If your cerbi_governance.json declares:

• userId as Required
• ssn as Forbidden

Compile-Time

[CERBI001] Missing Required Field: 'userId'
[CERBI002] Forbidden Field: 'ssn'

Runtime

{
  "App": "MyApp",
  "Environment": "Production",
  "Impact": 15.0,
  "Violations": ["MissingField:userId", "ForbiddenField:ssn"],
  "Relaxed": false
}

📄 Governance Configuration

Governance rules are defined in a JSON profile shared with the rest of the Cerbi ecosystem (via Cerbi.Governance.Core).

Example cerbi_governance.json:

{
  "EnforcementMode": "Strict",
  "LoggingProfiles": {
    "PIILog": {
      "AllowedLevels": [ "Info", "Warn", "Error" ],
      "FieldSeverities": {
        "userId": "Required",
        "ssn": "Forbidden",
        "sessionId": "Warning"
      },
      "FieldTypes": {
        "userId": "Guid"
      },
      "FieldEnums": {
        "Region": ["US", "EU", "APAC"]
      }
    }
  }
}

In your .csproj, make sure the config is copied alongside your build output:

<ItemGroup>
  <None Include="cerbi_governance.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Tip: You can keep multiple profiles (e.g. default, PIILog, AuditLog) and select them via Cerbi configuration. The NLog analyzer consumes whatever profile you point it at.

🚀 Runtime Governance Score Shipping (Optional)

Enable automatic validation and scoring by adding the custom NLog target GovernanceScore. It inspects LogEventInfo.Properties for these keys:

• GovernanceScoreImpact (numeric) – REQUIRED to emit an event
• GovernanceViolations (list/string) – optional list of violation messages
• GovernanceRelaxed (bool) – optional flag indicating relaxed enforcement mode

If present, and shipping is enabled & licensed, a GovernanceScoreEvent is queued and batch-shipped asynchronously.

NLog Config Example

<nlog>
  <extensions>
    <add assembly="CerbiStream.GovernanceAnalyzer" />
  </extensions>
  <targets>
    <target xsi:type="GovernanceScore"
            name="governanceScore"
            appName="MyApp"
            environment="Production"
            enableAutoEnrichment="true"
            governanceProfile="PIILog"
            scoreShippingEnabled="true"
            licenseAllowsScoring="true"
            scoreEndpoint="https://score.cerbi.systems/ingest"
            scoreMaxBatchSize="50"
            scoreMaxQueueSize="1000"
            scoreFlushIntervalSeconds="5" />
  </targets>
  <rules>
    <logger name="*" minlevel="Info" writeTo="governanceScore" />
  </rules>
</nlog>

How it works:

1. Every log passes through RuntimeGovernanceEnricher
2. Validates against PIILog profile
3. If violations exist, computes impact score
4. Attaches GovernanceScoreImpact, GovernanceViolations, GovernanceRelaxed
5. Ships to endpoint via async batch

Manual Mode

Attach properties manually:

var logEvent = new LogEventInfo(LogLevel.Info, "", "Example governance event");
logEvent.Properties["GovernanceScoreImpact"] = 12.5;
logEvent.Properties["GovernanceViolations"] = new[]{"MissingField:userId"};
logEvent.Properties["GovernanceRelaxed"] = false;
Logger.Log(logEvent);

Gating Rules

Event shipped only if:

1. scoreShippingEnabled = true
2. licenseAllowsScoring = true
3. GovernanceScoreImpact exists & parses as numeric

Non-blocking: dropped if queue full; no hot-path locks.

⚙️ Configuration Reference (Target Attributes)

You can also programmatically configure the target after LogManager.Configuration loads if needed.

📑 GovernanceScoreEvent Schema (JSON Batch Payload)

A flush sends a JSON array of events:

{
  "App": "MyApp",
  "Environment": "Production",
  "UtcTimestamp": "2025-01-15T12:34:56Z",
  "Impact": 15.0,
  "Relaxed": false,
  "Violations": [
    "MissingField: userId (User identifier)",
    "ForbiddenField: ssn (Social Security Number)"
  ],
  "Properties": {
    "CorrelationId": "abc-123",
    "RequestPath": "/api/users"
  }
}

Reserved property keys are not duplicated inside Properties: GovernanceScoreImpact, GovernanceViolations, GovernanceRelaxed.

⚡ Performance & Reliability

High-Throughput Design

• Channel-based queue: System.Threading.Channels with BoundedChannelFullMode.DropWrite
• Non-blocking enqueue: O(1) lock-free write; drops when full (no hot-path contention)
• Async HTTP: HttpClient.PostAsync with fire-and-forget batching
• Background flushing: continuous Task.Run loop eliminates timer overhead
• Profile caching: loaded once on InitializeTarget(), reused per event
• Inline validation: avoids external helper call overhead
• Fast impact scoring: char prefix matching (err[0] == 'M') instead of Contains()
• Zero-allocation enqueue: no intermediate buffers, direct channel write

Benchmark

Failure Modes

• HTTP failure: retries with exponential backoff; drops batch after MaxRetries
• Malformed impact: suppresses event emission (no exception)
• Queue overflow: silently drops new events (non-blocking)
• Shutdown: drains remaining events on Dispose() (5s timeout)

🔐 License Gating

Two independent gates:

1. Feature flag: scoreShippingEnabled (on/off switch)
2. Entitlement check: licenseAllowsScoring (license validation)

Use licenseAllowsScoring=false to disable dynamically (e.g., expired contract, regional restriction, missing entitlement).

🧪 Testing Guidance

Unit Tests

// Test auto-enrichment
var target = CreateTarget(fakeShipper, t => {
    t.EnableAutoEnrichment = true;
    t.GovernanceProfile = "PIILog";
});

var logEvent = new LogEventInfo(LogLevel.Info, "", "test");
logEvent.Properties["password"] = "secret"; // forbidden field
target.Emit(logEvent);

Assert.Equal(1, fakeShipper.EnqueueCount);
Assert.True(fakeShipper.LastEvent.Impact > 0);
Assert.Contains("ForbiddenField: password", fakeShipper.LastEvent.Violations);

High-Throughput Test

[Fact]
public async Task HighThroughput_ThousandsOfEvents_NoBlocking()
{
    var shipper = new ScoreShipper(httpClient, options);
    var start = DateTime.UtcNow;
    
    for (int i = 0; i < 1000; i++)
        shipper.Enqueue(new GovernanceScoreEvent { Impact = i });
    
    var elapsed = DateTime.UtcNow - start;
    Assert.True(elapsed.TotalMilliseconds < 100); // <100ms for 1000 events
}

🔌 Extensibility

Custom Shipper

Replace internal ScoreShipper with custom implementation:

public class MyCustomTarget : GovernanceScoreTarget
{
    protected override void InitializeTarget()
    {
        // Inject custom shipper with metrics, circuit breaker, etc.
        _scoreShipper = new MyCustomShipper(_httpClient, ScoreShipping);
    }
}

Custom Validation

Wrap additional metadata:

logEvent.Properties["TeamId"] = "team-42";
logEvent.Properties["ServiceVersion"] = "1.2.3";
// Automatically copied to GovernanceScoreEvent.Properties

📦 Installation

dotnet add package Cerbi.NLog.GovernanceAnalyzer

• Analyzer: runs automatically at build
• Target: activates via <extensions> in NLog config

🔐 Encryption & NLog

This package does not implement log payload encryption. NLog lacks first-class encryption support for structured data.

For end-to-end encrypted logging with governance-aware encryption modes (AES/Base64/None):

• CerbiStream – governed logging library
• Cerbi.Governance.Runtime – runtime validation engine

🧠 IDE & CI Integration

Local Development

• Underlines / squiggles in Visual Studio and Rider
• Diagnostics in Error List
• Treat as warnings for dev productivity

CI/CD

dotnet build /warnaserror:CERBI001,CERBI002

• Escalate to errors for critical profiles (PII/PHI)
• Block deployment on governance violations

🧹 Plugin Architecture

Layer custom rules via ICustomGovernancePlugin:

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

        var isProd = logData.TryGetValue("Environment", out var env) &&
                     env?.ToString() == "Production";

        if (isProd && !logData.ContainsKey("TeamId"))
        {
            failures.Add("MissingField: TeamId is required in Production.");
            impactScore = 5;
            return false;
        }
        return true;
    }
}

Use plugins for:

• Environment-specific rules (stricter in Production)
• Team/domain-specific checks
• Custom impact scoring for dashboards (CerbiShield / CerbIQ)

🌍 How It Fits with Other Loggers & Stacks

This package targets NLog specifically, but it’s part of a bigger story:

• Serilog / MEL / NLog / Log4Net
  • Other Cerbi analyzers and runtime components cover these stacks.
• OpenTelemetry Logging / OTLP / Collector
  • Cerbi ensures logs are governed before they’re exported and shipped downstream.
• Seq, Grafana Loki / Promtail / Alloy, Fluentd / FluentBit, ELK / OpenSearch, Graylog, VictoriaLogs / VictoriaMetrics, Journald / syslog
  • Keep using your existing sinks; this analyzer + target just keeps the input sane and compliant.

Cerbi.NLog.GovernanceAnalyzer doesn’t replace NLog or your observability platform. It makes sure your NLog usage is safe, structured, and policy-compliant.

📜 License

MIT © Cerbi LLC — https://cerbi.io

See LICENSE.txt for details.