feat(audit): M5.3 response-capture increments — request headers, ceiling-hits counter, per-method body opt-out (T7)

1. Request headers in Extra JSON (AuditWriteMiddleware): adds a `requestHeaders` object to the existing Extra JSON alongside remoteIp/userAgent; headers whose names appear in AuditLogOptions.HeaderRedactList (Authorization, X-Api-Key, Cookie, Set-Cookie by default) are replaced with "<redacted>" using OrdinalIgnoreCase matching — same policy as ScadaBridgeAuditRedactor. 2. AuditInboundCeilingHits counter: new IAuditInboundCeilingHitsCounter interface + NoOpAuditInboundCeilingHitsCounter default; AuditCentralHealthSnapshot implements the interface (Interlocked field, thread-safe) and exposes AuditInboundCeilingHits on IAuditCentralHealthSnapshot; AddAuditLog registers the NoOp default, AddAuditLogCentralMaintenance forwards to the snapshot; AuditWriteMiddleware accepts the counter as an optional ctor arg and increments it once per request where either the request or response body hit the cap. 3. Per-method SkipBodyCapture opt-out: adds SkipBodyCapture bool to PerTargetRedactionOverride; AuditWriteMiddleware consults the per-target override map at the start of InvokeAsync (before EnableBuffering) and, when set, skips body read + capture entirely — the audit row still emits with headers/metadata but null RequestSummary/ResponseSummary; truncation flags are also cleared so the ceiling-hits counter is not bumped for opted-out methods.
2026-06-16 21:23:07 -04:00
parent 0569c5ff23
commit a07ff28f10
9 changed files with 643 additions and 8 deletions
@@ -6,6 +6,7 @@ using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.AuditLog.Central;
 using ZB.MOM.WW.ScadaBridge.AuditLog.Configuration;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
@@ -95,6 +96,7 @@ public sealed class AuditWriteMiddleware
    private readonly ILogger<AuditWriteMiddleware> _logger;
    private readonly IOptionsMonitor<AuditLogOptions> _options;
    private readonly IAuditActorAccessor? _actorAccessor;
+    private readonly IAuditInboundCeilingHitsCounter _ceilingHitsCounter;

    /// <summary>
    /// Initializes the middleware with its required dependencies.
@@ -110,18 +112,26 @@ public sealed class AuditWriteMiddleware
    /// construct the middleware; when absent, actor resolution falls back to the
    /// stashed API-key name only.
    /// </param>
+    /// <param name="ceilingHitsCounter">
+    /// M5.3 (T7, optional): incremented whenever an inbound request or response
+    /// body is truncated at <see cref="AuditLogOptions.InboundMaxBytes"/>. Optional
+    /// so existing tests and composition roots without the central health snapshot
+    /// wired still construct without the counter; a NoOp is used when absent.
+    /// </param>
    public AuditWriteMiddleware(
        RequestDelegate next,
        ICentralAuditWriter auditWriter,
        ILogger<AuditWriteMiddleware> logger,
        IOptionsMonitor<AuditLogOptions> options,
-        IAuditActorAccessor? actorAccessor = null)
+        IAuditActorAccessor? actorAccessor = null,
+        IAuditInboundCeilingHitsCounter? ceilingHitsCounter = null)
    {
        _next = next ?? throw new ArgumentNullException(nameof(next));
        _auditWriter = auditWriter ?? throw new ArgumentNullException(nameof(auditWriter));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        _options = options ?? throw new ArgumentNullException(nameof(options));
        _actorAccessor = actorAccessor;
+        _ceilingHitsCounter = ceilingHitsCounter ?? new NoOpAuditInboundCeilingHitsCounter();
    }

    /// <summary>
@@ -133,9 +143,11 @@ public sealed class AuditWriteMiddleware
    {
        var sw = Stopwatch.StartNew();

-        // Per-request hot read of the inbound cap so a live config change
+        // Per-request hot read of the options snapshot so a live config change
        // picks up on the next request without re-resolving the singleton.
-        var cap = _options.CurrentValue.InboundMaxBytes;
+        // InboundMaxBytes is read once here and passed to the capture helpers.
+        var opts = _options.CurrentValue;
+        var cap = opts.InboundMaxBytes;

        // Audit Log #23 (ParentExecutionId): mint the inbound request's per-request
        // ExecutionId ONCE, here at the start of the request, and stash it on
@@ -163,9 +175,20 @@ public sealed class AuditWriteMiddleware
        // ReadBufferedRequestBodyAsync's own ContentLength is 0 short-circuit
        // returns (null, false) for the bodyless case anyway, so the audit row
        // is unchanged.
+        //
+        // M5.3 (T7): check if the matched method/target has SkipBodyCapture set.
+        // The route value is resolved BEFORE the pipeline runs (route matching
+        // has already bound {methodName} at this point), so we can skip the
+        // EnableBuffering allocation and body read up front.
+        var methodNameForOverride = ctx.Request.RouteValues.TryGetValue("methodName", out var rv)
+            && rv is string mn && !string.IsNullOrWhiteSpace(mn) ? mn : null;
+        var skipBody = methodNameForOverride != null
+            && opts.PerTargetOverrides.TryGetValue(methodNameForOverride, out var perTarget)
+            && perTarget.SkipBodyCapture;
+
        var requestBody = (string?)null;
        var requestTruncated = false;
-        if (RequestHasBody(ctx.Request))
+        if (!skipBody && RequestHasBody(ctx.Request))
        {
            ctx.Request.EnableBuffering();
            (requestBody, requestTruncated) =
@@ -200,7 +223,14 @@ public sealed class AuditWriteMiddleware
            // The forwarding wrapper has already written every byte to the
            // original sink; this just pulls back the bounded UTF-8 string.
            ctx.Response.Body = originalResponseBody;
-            var (responseBody, responseTruncated) = captureStream.GetCapturedBody();
+            var (capturedResponseBody, capturedResponseTruncated) = captureStream.GetCapturedBody();
+            // M5.3 (T7): if SkipBodyCapture is set, discard the captured response
+            // body (the request body was never captured above). The row + headers
+            // still emit with null RequestSummary / ResponseSummary.
+            // Truncation flags are also cleared so ceiling-hit counter is not
+            // bumped for methods that deliberately opt out of body capture.
+            var responseBody = skipBody ? null : capturedResponseBody;
+            var responseTruncated = skipBody ? false : capturedResponseTruncated;

            EmitInboundAudit(
                ctx,
@@ -208,7 +238,9 @@ public sealed class AuditWriteMiddleware
                thrown,
                requestBody,
                responseBody,
-                requestTruncated || responseTruncated);
+                requestTruncated || responseTruncated,
+                requestTruncated,
+                responseTruncated);
        }
    }

@@ -223,7 +255,9 @@ public sealed class AuditWriteMiddleware
        Exception? thrown,
        string? requestBody,
        string? responseBody,
-        bool payloadTruncated)
+        bool payloadTruncated,
+        bool requestTruncated = false,
+        bool responseTruncated = false)
    {
        try
        {
@@ -243,10 +277,40 @@ public sealed class AuditWriteMiddleware
            var actor = isAuthFailure ? null : ResolveActor(ctx);
            var methodName = ResolveMethodName(ctx);

+            // M5.3 (T7): increment the ceiling-hits counter once per request
+            // that hit the cap on EITHER the request or response body.
+            if (requestTruncated || responseTruncated)
+            {
+                try { _ceilingHitsCounter.Increment(); } catch { /* swallow per §7 */ }
+            }
+
+            // M5.3 (T7): capture request headers into Extra JSON alongside the
+            // existing remoteIp / userAgent provenance fields. The header
+            // collection is run through the SAME header-redaction list
+            // (AuditLogOptions.HeaderRedactList) that the ScadaBridgeAuditRedactor
+            // applies to RequestSummary / ResponseSummary — auth/sensitive
+            // headers are redacted before they land in the row.
+            var currentOpts = _options.CurrentValue;
+            var redactSet = new HashSet<string>(
+                currentOpts.HeaderRedactList,
+                StringComparer.OrdinalIgnoreCase);
+
+            var headerDict = new Dictionary<string, string>(StringComparer.Ordinal);
+            foreach (var header in ctx.Request.Headers)
+            {
+                // Redact headers whose name appears in the HeaderRedactList —
+                // the same "<redacted>" marker used by ScadaBridgeAuditRedactor.
+                var value = redactSet.Contains(header.Key)
+                    ? "<redacted>"
+                    : header.Value.ToString();
+                headerDict[header.Key] = value;
+            }
+
            var extra = JsonSerializer.Serialize(new
            {
                remoteIp = ctx.Connection.RemoteIpAddress?.ToString(),
                userAgent = ctx.Request.Headers.UserAgent.ToString(),
+                requestHeaders = headerDict,
            });

            var evt = ScadaBridgeAuditEventFactory.Create(