using System.Globalization; using System.Text; using System.Text.Json; using System.Text.Json.Serialization; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; using ZB.MOM.WW.Audit; using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories; using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management; using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit; using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums; using ZB.MOM.WW.Auth.Abstractions.Ldap; using ZB.MOM.WW.ScadaBridge.Security; namespace ZB.MOM.WW.ScadaBridge.ManagementService; /// /// Minimal-API endpoints exposing the central Audit Log over HTTP for the /// ScadaBridge CLI. Three routes: /// /// GET /api/audit/query — keyset-paged JSON page, gated on the /// permission. /// GET /api/audit/export — streamed bulk export (csv / jsonl / /// parquet), gated on the /// permission. /// GET /api/audit/tree — execution-chain tree rooted at the /// topmost ancestor of a given executionId, returned as a JSON array /// of ; gated on /// . /// /// /// /// Auth mechanism. ManagementService ships NO ASP.NET authorization-policy /// pipeline — the existing /management endpoint /// () authenticates each request by hand: /// decode HTTP Basic Auth, bind against LDAP via , /// then map LDAP groups to roles via . These audit /// endpoints follow that exact mechanism rather than .RequireAuthorization() /// so the CLI authenticates the same way it does for every other management /// call (HTTP Basic). Permission gating is then a role-set membership check /// against / /// — the very role sets the /// CentralUI's enforces, so the two surfaces /// stay in lockstep. /// /// /// /// Parquet. format=parquet (ScadaBridge#42) streams the same 24 columns as /// csv / jsonl as one Parquet file (), a row group at a time. /// /// public static class AuditEndpoints { /// Default rows per page for /api/audit/query. public const int DefaultPageSize = 100; /// Hard ceiling on a single query page — keeps one page bounded in memory. public const int MaxPageSize = 1000; /// Repository round-trip size used while streaming an export. public const int ExportPageSize = 1000; /// Content type of a format=parquet export (ScadaBridge#42). public const string ParquetContentType = "application/vnd.apache.parquet"; /// /// Serializer for individual rows (query results + /// jsonl export lines). Drops null columns so a sparse audit row stays /// compact on the wire. /// private static readonly JsonSerializerOptions JsonOptions = new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, Converters = { new JsonStringEnumConverter() }, }; /// /// Serializer for the /api/audit/query response envelope. Unlike /// it does NOT ignore nulls — the contract /// requires nextCursor to be present as an explicit null when /// there is no further page, so the CLI can rely on the key always existing. /// private static readonly JsonSerializerOptions EnvelopeJsonOptions = new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, Converters = { new JsonStringEnumConverter() }, }; /// Default sentinel written by the backfill endpoint when the caller omits sentinel. public const string DefaultBackfillSentinel = "unknown"; /// Default batch size for the backfill endpoint when the caller omits batchSize. public const int DefaultBackfillBatchSize = 5000; /// /// Registers the /api/audit/query, /api/audit/export, /// /api/audit/tree, and POST /api/audit/backfill-source-node /// minimal-API endpoints. /// /// The endpoint route builder to register routes on. /// The same builder, for chaining. public static IEndpointRouteBuilder MapAuditAPI(this IEndpointRouteBuilder endpoints) { endpoints.MapGet("/api/audit/query", (Delegate)HandleQuery); endpoints.MapGet("/api/audit/export", (Delegate)HandleExport); endpoints.MapGet("/api/audit/tree", (Delegate)HandleTree); endpoints.MapPost("/api/audit/backfill-source-node", (Delegate)HandleBackfillSourceNode); return endpoints; } // ───────────────────────────────────────────────────────────────────── // GET /api/audit/query // ───────────────────────────────────────────────────────────────────── /// /// Handles GET /api/audit/query: authenticates, checks the OperationalAudit permission, and returns a keyset-paged JSON result. /// /// The HTTP context for the current request. /// A task that resolves to the HTTP result (200 JSON page, 401, or 403). internal static async Task HandleQuery(HttpContext context) { var auth = await AuthenticateAsync(context); if (auth.Failure is not null) { return auth.Failure; } if (!HasAnyRole(auth.User!, AuthorizationPolicies.OperationalAuditRoles)) { return Forbidden("OperationalAudit"); } AuditLogQueryFilter filter; try { filter = ParseFilter(context.Request.Query); } catch (AuditFilterParseException ex) { return BadFilter(ex); } var restricted = ApplySiteScope(filter, auth.User!); if (restricted is null) { return Forbidden("OperationalAudit"); } filter = restricted; var paging = ParsePaging(context.Request.Query); var repo = context.RequestServices.GetRequiredService(); var canonical = await repo.QueryAsync(filter, paging, context.RequestAborted); // The cursor for the next page is the last row of this page — but only // when the page came back FULL. A short page means there is no next // page, so nextCursor is null and the CLI stops paging. object? nextCursor = null; if (canonical.Count == paging.PageSize && canonical.Count > 0) { var last = canonical[^1]; nextCursor = new { // Canonical OccurredAtUtc is a DateTimeOffset; the cursor key is UTC. afterOccurredAtUtc = last.OccurredAtUtc.UtcDateTime, afterEventId = last.EventId, }; } // Decompose canonical rows into the flat AuditExportRow so the // CLI's JSON shape (24-field) is unchanged. var events = canonical.Select(AuditExportRow.From).ToList(); var payload = new { events, nextCursor }; // EnvelopeJsonOptions keeps an explicit null nextCursor on the wire so // the CLI can always read the key. AuditEvent rows render with their // full (null-inclusive) shape — a stable schema for the consumer. return Results.Text( JsonSerializer.Serialize(payload, EnvelopeJsonOptions), "application/json", statusCode: 200); } // ───────────────────────────────────────────────────────────────────── // GET /api/audit/export // ───────────────────────────────────────────────────────────────────── /// /// Handles GET /api/audit/export: authenticates, checks the AuditExport permission, and streams the matching rows as CSV, JSONL or Parquet. /// /// The HTTP context for the current request. /// A task that resolves to the HTTP result (streaming CSV/JSONL/Parquet, 400, 401, or 403). internal static async Task HandleExport(HttpContext context) { var auth = await AuthenticateAsync(context); if (auth.Failure is not null) { return auth.Failure; } if (!HasAnyRole(auth.User!, AuthorizationPolicies.AuditExportRoles)) { return Forbidden("AuditExport"); } var format = (context.Request.Query["format"].ToString() ?? string.Empty).Trim().ToLowerInvariant(); if (string.IsNullOrEmpty(format)) { format = "csv"; } if (format != "csv" && format != "jsonl" && format != "parquet") { return Results.Json( new { error = $"Unsupported export format '{format}'. Use csv, jsonl, or parquet.", code = "BAD_REQUEST" }, statusCode: 400); } AuditLogQueryFilter filter; try { filter = ParseFilter(context.Request.Query); } catch (AuditFilterParseException ex) { return BadFilter(ex); } var restricted = ApplySiteScope(filter, auth.User!); if (restricted is null) { return Forbidden("AuditExport"); } filter = restricted; var repo = context.RequestServices.GetRequiredService(); var (contentType, extension) = format switch { "csv" => ("text/csv; charset=utf-8", "csv"), "parquet" => (ParquetContentType, "parquet"), _ => ("application/x-ndjson", "jsonl"), }; var fileName = $"audit-log-{DateTime.UtcNow:yyyyMMdd-HHmmss}.{extension}"; context.Response.ContentType = contentType; context.Response.Headers["Content-Disposition"] = $"attachment; filename=\"{fileName}\""; // Defeat intermediate proxy buffering so rows stream as each page flushes. context.Response.Headers["Cache-Control"] = "no-store"; if (format == "csv") { await StreamCsvAsync(repo, filter, context.Response.Body, context.RequestAborted); } else if (format == "parquet") { // ScadaBridge#42: same 24 columns as csv/jsonl, one row group per 10k rows. await AuditExportParquet.WriteAsync( ExportRowPagesAsync(repo, filter, context.RequestAborted), context.Response.Body, context.RequestAborted); } else { await StreamJsonlAsync(repo, filter, context.Response.Body, context.RequestAborted); } return Results.Empty; } // ───────────────────────────────────────────────────────────────────── // GET /api/audit/tree // ───────────────────────────────────────────────────────────────────── /// /// Handles GET /api/audit/tree?executionId=...: authenticates, checks the /// OperationalAudit permission, and returns the full execution-chain tree rooted at /// the topmost ancestor of the supplied executionId. The response is a JSON /// array of objects (empty array when the id is /// not found). Returns HTTP 400 when executionId is absent or not a valid /// GUID. /// /// The HTTP context for the current request. /// A task that resolves to the HTTP result (200 JSON array, 400, 401, or 403). internal static async Task HandleTree(HttpContext context) { var auth = await AuthenticateAsync(context); if (auth.Failure is not null) { return auth.Failure; } if (!HasAnyRole(auth.User!, AuthorizationPolicies.OperationalAuditRoles)) { return Forbidden("OperationalAudit"); } var raw = context.Request.Query["executionId"].ToString(); if (string.IsNullOrWhiteSpace(raw) || !Guid.TryParse(raw, out var executionId)) { return Results.Json( new { error = "Missing or invalid 'executionId' query parameter (expected a GUID).", code = "BAD_REQUEST" }, statusCode: 400); } var repo = context.RequestServices.GetRequiredService(); var permitted = auth.User!.Roles.Contains("Administrator", StringComparer.OrdinalIgnoreCase) || auth.User.PermittedSiteIds.Length == 0 ? null : auth.User.PermittedSiteIds; var nodes = await repo.GetExecutionTreeAsync(executionId, context.RequestAborted, permitted); return Results.Json(nodes, JsonOptions); } // ───────────────────────────────────────────────────────────────────── // POST /api/audit/backfill-source-node // ───────────────────────────────────────────────────────────────────── /// /// Handles POST /api/audit/backfill-source-node: authenticates (Admin role /// required), reads the JSON body for sentinel / before / /// batchSize, and calls /// on the maintenance /// path. /// /// /// Auth. Admin-only — backfilling the SourceNode column is a one-time ops /// procedure that mutates the AuditLog table via the maintenance path (NOT the /// append-only writer role). Restricted to /// (Administrator) so it is never accessible to Viewer-role users. /// /// /// /// Request body. /// /// { /// "sentinel": "unknown", // optional; default "unknown" /// "before": "2026-01-01T00:00:00Z", // required ISO-8601 UTC /// "batchSize": 5000 // optional; default 5000 /// } /// /// /// /// /// Response (200). /// { "rowsUpdated": 12345, "sentinel": "unknown", "before": "2026-01-01T00:00:00Z" } /// /// /// The HTTP context for the current request. /// A task that resolves to the HTTP result (200 JSON, 400, 401, or 403). internal static async Task HandleBackfillSourceNode(HttpContext context) { var auth = await AuthenticateAsync(context); if (auth.Failure is not null) { return auth.Failure; } // Admin-only: backfilling is a one-time ops procedure on the maintenance path. if (!HasAnyRole(auth.User!, AuthorizationPolicies.AuditExportRoles)) { return Forbidden("Administrator"); } string bodyText; try { using var reader = new System.IO.StreamReader(context.Request.Body); bodyText = await reader.ReadToEndAsync(context.RequestAborted); } catch (OperationCanceledException) { return Results.Json(new { error = "Request cancelled.", code = "CANCELLED" }, statusCode: 499); } string sentinel = DefaultBackfillSentinel; DateTime? beforeUtc = null; int batchSize = DefaultBackfillBatchSize; if (!string.IsNullOrWhiteSpace(bodyText)) { try { using var doc = System.Text.Json.JsonDocument.Parse(bodyText); var root = doc.RootElement; if (root.TryGetProperty("sentinel", out var sentinelEl)) { var s = sentinelEl.GetString(); if (!string.IsNullOrWhiteSpace(s)) { sentinel = s.Trim(); } } if (root.TryGetProperty("before", out var beforeEl)) { if (DateTime.TryParse( beforeEl.GetString(), System.Globalization.CultureInfo.InvariantCulture, System.Globalization.DateTimeStyles.AssumeUniversal | System.Globalization.DateTimeStyles.AdjustToUniversal, out var parsed)) { beforeUtc = DateTime.SpecifyKind(parsed, DateTimeKind.Utc); } else { return Results.Json( new { error = "Invalid 'before' value; expected ISO-8601 UTC datetime.", code = "BAD_REQUEST" }, statusCode: 400); } } if (root.TryGetProperty("batchSize", out var batchEl) && batchEl.TryGetInt32(out var b) && b > 0) { batchSize = b; } } catch (System.Text.Json.JsonException) { return Results.Json( new { error = "Request body must be valid JSON.", code = "BAD_REQUEST" }, statusCode: 400); } } if (beforeUtc is null) { return Results.Json( new { error = "Required field 'before' (ISO-8601 UTC datetime) is missing.", code = "BAD_REQUEST" }, statusCode: 400); } var repo = context.RequestServices.GetRequiredService(); var rowsUpdated = await repo.BackfillSourceNodeAsync(sentinel, beforeUtc.Value, batchSize, context.RequestAborted); return Results.Json(new { rowsUpdated, sentinel, before = beforeUtc.Value.ToString("O", System.Globalization.CultureInfo.InvariantCulture), }, JsonOptions); } /// /// Streams every matching row as RFC 4180 CSV, paging the repository with its /// keyset cursor and flushing after each page so a large export starts /// arriving immediately. Column order matches . /// private static async Task StreamCsvAsync( IAuditLogRepository repo, AuditLogQueryFilter filter, Stream output, CancellationToken ct) { await using var writer = new StreamWriter( output, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false), bufferSize: 4096, leaveOpen: true) { NewLine = "\r\n", }; await writer.WriteLineAsync(CsvHeader); await foreach (var page in PageAsync(repo, filter, ct)) { foreach (var evt in page) { await writer.WriteLineAsync(FormatCsvRow(AuditExportRow.From(evt))); } await writer.FlushAsync(ct); await output.FlushAsync(ct); } } /// /// Streams every matching row as newline-delimited JSON (one compact object /// per line), flushing after each page. /// private static async Task StreamJsonlAsync( IAuditLogRepository repo, AuditLogQueryFilter filter, Stream output, CancellationToken ct) { await using var writer = new StreamWriter( output, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false), bufferSize: 4096, leaveOpen: true) { NewLine = "\n", }; await foreach (var page in PageAsync(repo, filter, ct)) { foreach (var evt in page) { await writer.WriteLineAsync(JsonSerializer.Serialize(AuditExportRow.From(evt), JsonOptions)); } await writer.FlushAsync(ct); await output.FlushAsync(ct); } } /// Projects pages onto the flat export row shape. private static async IAsyncEnumerable> ExportRowPagesAsync( IAuditLogRepository repo, AuditLogQueryFilter filter, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct) { await foreach (var page in PageAsync(repo, filter, ct)) { yield return page.Select(AuditExportRow.From).ToList(); } } /// /// Lazily yields full repository pages, advancing the keyset cursor until a /// short page signals the end. Shared by the csv + jsonl streamers. /// private static async IAsyncEnumerable> PageAsync( IAuditLogRepository repo, AuditLogQueryFilter filter, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct) { var cursor = new AuditLogPaging(ExportPageSize); while (true) { ct.ThrowIfCancellationRequested(); var page = await repo.QueryAsync(filter, cursor, ct); if (page.Count == 0) { yield break; } yield return page; if (page.Count < cursor.PageSize) { yield break; } var last = page[^1]; // Canonical OccurredAtUtc is a DateTimeOffset; the keyset cursor column is UTC. cursor = new AuditLogPaging(ExportPageSize, last.OccurredAtUtc.UtcDateTime, last.EventId); } } // ───────────────────────────────────────────────────────────────────── // Authentication — Basic Auth → LDAP → roles (mirrors ManagementEndpoints) // ───────────────────────────────────────────────────────────────────── /// Outcome of : exactly one of the two fields is set. private readonly record struct AuthOutcome(AuthenticatedUser? User, IResult? Failure); /// /// Authenticates the audit-REST request via the shared /// — the dev/test /// DisableLogin bypass first, otherwise HTTP Basic → LDAP → roles, the same flow /// uses. Returns a populated /// on success, or an carrying the 401 response on any failure. /// private static async Task AuthenticateAsync(HttpContext context) { var outcome = await ManagementAuthenticator.AuthenticateAsync(context); return new AuthOutcome(outcome.User, outcome.Failure); } private static bool HasAnyRole(AuthenticatedUser user, string[] allowed) => user.Roles.Any(r => allowed.Contains(r, StringComparer.OrdinalIgnoreCase)); private static IResult Forbidden(string permission) => Results.Json( new { error = $"Permission '{permission}' required.", code = "UNAUTHORIZED" }, statusCode: 403); /// /// Maps an to the endpoint's existing /// 400 BAD_REQUEST shape — the same envelope the unsupported-export-format /// branch already returns, so the CLI needs no new error handling. /// /// /// The exception message is surfaced VERBATIM. It is composed by the parser to be /// caller-safe (offending value + the full valid set) and naming the valid set is /// the entire point of the check (register row 99). /// /// The parse failure to surface. /// A 400 result carrying the caller-safe message. private static IResult BadFilter(AuditFilterParseException ex) => Results.Json( new { error = ex.Message, code = "BAD_REQUEST" }, statusCode: 400); /// /// Applies the caller's to the /// audit-log filter. System-wide callers (empty PermittedSiteIds — /// Admin or a Deployment-style role with no scope rules attached to its mapping) /// see the filter unchanged. A scoped caller has any caller-supplied /// sourceSiteId intersected with their permitted set: an empty caller filter /// is replaced by the permitted set; an explicit out-of-scope filter (no overlap /// with the permitted set) returns null so the caller gets a 403 rather /// than silently empty results. /// /// The caller-supplied audit-log query filter to scope. /// The authenticated user whose permitted site IDs constrain the filter. /// /// The restricted filter, or null if the caller explicitly asked for /// sites entirely outside their permitted set. /// public static AuditLogQueryFilter? ApplySiteScope(AuditLogQueryFilter filter, AuthenticatedUser user) { // Empty PermittedSiteIds is the system-wide signal (Administrator, // system-wide Deployer). System-wide audit roles also fall here — the // design treats Administrator/Viewer (the audit roles) as // non-site-scoped unless an operator attaches scope rules to the LDAP // mapping; if they do, this helper enforces them. if (user.PermittedSiteIds.Length == 0) { return filter; } var permitted = new HashSet(user.PermittedSiteIds, StringComparer.Ordinal); if (filter.SourceSiteIds is null || filter.SourceSiteIds.Count == 0) { // No explicit filter — restrict to permitted set. return filter with { SourceSiteIds = permitted.ToArray() }; } // Explicit filter — intersect. var intersection = filter.SourceSiteIds.Where(permitted.Contains).ToArray(); if (intersection.Length == 0) { return null; } return filter with { SourceSiteIds = intersection }; } // ───────────────────────────────────────────────────────────────────── // Query-string parsing // ───────────────────────────────────────────────────────────────────── /// /// Parses the query-string into an . The /// channel/kind/status/sourceSiteId dimensions are /// multi-value: a repeated query param (channel=A&channel=B) yields /// a multi-element filter list, while a single param yields a one-element /// list. /// /// /// /// The enum filters parse STRICTLY (register row 99); the Guid/date filters /// stay lax. An unrecognised channel/kind/status throws /// , which the two handlers turn into a /// 400 BAD_REQUEST naming the valid set. Silently dropping a filter here /// used to hand the CLI a plausible, complete-looking page that did not answer /// the question asked — the same failure row 88 fixed for deploy status. /// The CLI reaches this endpoint with case-insensitive values now that its own /// case-SENSITIVE AcceptOnlyFromAmong guard is gone, so this is the /// authoritative check for those three dimensions. /// /// /// The CentralUI AuditLogPage drill-in parser and the CentralUI export /// endpoint it feeds deliberately keep the LAX /// — they read a query /// string a human may have bookmarked or hand-edited, where a stale fragment /// must still render the page. Do not "reconcile" the two. /// /// /// This endpoint reads the source-site filter from the sourceSiteId /// query key, whereas the CentralUI export endpoint reads it as site. /// The divergence is deliberate — each endpoint matches its own CLI / UI URL /// builder — so do NOT "fix" the two to a single key name. /// /// /// The HTTP query string collection to parse filter parameters from. /// An built from the supplied query parameters. /// A channel/kind/status value is not a recognised member name. public static AuditLogQueryFilter ParseFilter(IQueryCollection query) { var channels = AuditQueryParamParsers.ParseEnumListStrict(query["channel"], "channel"); var kinds = AuditQueryParamParsers.ParseEnumListStrict(query["kind"], "kind"); var statuses = AuditQueryParamParsers.ParseEnumListStrict(query["status"], "status"); var sourceSiteIds = AuditQueryParamParsers.ParseStringList(query["sourceSiteId"]); Guid? correlationId = null; if (query.TryGetValue("correlationId", out var corrValues) && Guid.TryParse(corrValues.ToString(), out var parsedCorr)) { correlationId = parsedCorr; } Guid? executionId = null; if (query.TryGetValue("executionId", out var execValues) && Guid.TryParse(execValues.ToString(), out var parsedExec)) { executionId = parsedExec; } Guid? parentExecutionId = null; if (query.TryGetValue("parentExecutionId", out var parentExecValues) && Guid.TryParse(parentExecValues.ToString(), out var parsedParentExec)) { parentExecutionId = parsedParentExec; } return new AuditLogQueryFilter( Channels: channels, Kinds: kinds, Statuses: statuses, SourceSiteIds: sourceSiteIds, Target: TrimToNullable(query, "target"), Actor: TrimToNullable(query, "actor"), CorrelationId: correlationId, ExecutionId: executionId, ParentExecutionId: parentExecutionId, FromUtc: ParseUtcDate(query, "fromUtc"), ToUtc: ParseUtcDate(query, "toUtc")); } /// /// Parses the keyset-paging query parameters into an /// . pageSize is clamped to /// [1, ]; a missing / junk value falls back /// to . afterOccurredAtUtc + /// afterEventId are honoured only when BOTH parse (the repository's /// keyset cursor requires the pair together). /// /// The HTTP query string collection to parse paging parameters from. /// An built from the supplied query parameters. public static AuditLogPaging ParsePaging(IQueryCollection query) { int pageSize = DefaultPageSize; if (query.TryGetValue("pageSize", out var pageSizeRaw) && int.TryParse(pageSizeRaw.ToString(), NumberStyles.Integer, CultureInfo.InvariantCulture, out var parsedSize) && parsedSize > 0) { pageSize = Math.Min(parsedSize, MaxPageSize); } DateTime? afterOccurredAt = ParseUtcDate(query, "afterOccurredAtUtc"); Guid? afterEventId = null; if (query.TryGetValue("afterEventId", out var eventIdRaw) && Guid.TryParse(eventIdRaw.ToString(), out var parsedEventId)) { afterEventId = parsedEventId; } // The cursor pair must be all-or-nothing — a half-supplied cursor would // produce an invalid keyset predicate. Drop both unless both are present. if (afterOccurredAt is null || afterEventId is null) { return new AuditLogPaging(pageSize); } return new AuditLogPaging(pageSize, afterOccurredAt, afterEventId); } private static string? TrimToNullable(IQueryCollection query, string key) { if (!query.TryGetValue(key, out var values)) { return null; } var v = values.ToString(); return string.IsNullOrWhiteSpace(v) ? null : v.Trim(); } private static DateTime? ParseUtcDate(IQueryCollection query, string key) { if (!query.TryGetValue(key, out var values)) { return null; } if (DateTime.TryParse( values.ToString(), CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out var parsed)) { return DateTime.SpecifyKind(parsed, DateTimeKind.Utc); } return null; } // ───────────────────────────────────────────────────────────────────── // CSV helpers — 24 columns, same order/naming as the JSONL export // (AuditExportRow property declaration order) // ───────────────────────────────────────────────────────────────────── public const string CsvHeader = "EventId,OccurredAtUtc,IngestedAtUtc,Channel,Kind,CorrelationId,ExecutionId,ParentExecutionId," + "SourceSiteId,SourceNode,SourceInstanceId,SourceScript,Actor,Target,Status," + "HttpStatus,DurationMs,ErrorMessage,ErrorDetail,RequestSummary," + "ResponseSummary,PayloadTruncated,Extra,ForwardState"; /// /// Formats a single as an RFC 4180 CSV row matching . /// Free-text columns (anything that can carry inbound-API-caller-controlled or /// site-script-controlled text — , /// , , /// , , /// , , /// , , /// , ) are run /// through before RFC 4180 quoting so a leading /// =/+/-/@/TAB/CR can't be interpreted as a formula or DDE /// trigger by a spreadsheet application (CSV formula injection). GUID/enum/numeric/date/bool columns the /// exporter formats itself are never neutralized — none of them can start with a trigger /// character, and neutralizing a signed numeric column would corrupt it. /// /// The audit event to format. /// An RFC 4180 CSV row string (no trailing newline) for the supplied event. public static string FormatCsvRow(AuditExportRow evt) { var sb = new StringBuilder(256); AppendField(sb, evt.EventId.ToString(), first: true); AppendField(sb, FormatDate(evt.OccurredAtUtc)); AppendField(sb, FormatDate(evt.IngestedAtUtc)); AppendField(sb, evt.Channel.ToString()); AppendField(sb, evt.Kind.ToString()); AppendField(sb, evt.CorrelationId?.ToString()); AppendField(sb, evt.ExecutionId?.ToString()); AppendField(sb, evt.ParentExecutionId?.ToString()); AppendField(sb, evt.SourceSiteId, freeText: true); AppendField(sb, evt.SourceNode, freeText: true); AppendField(sb, evt.SourceInstanceId, freeText: true); AppendField(sb, evt.SourceScript, freeText: true); AppendField(sb, evt.Actor, freeText: true); AppendField(sb, evt.Target, freeText: true); AppendField(sb, evt.Status.ToString()); AppendField(sb, evt.HttpStatus?.ToString(CultureInfo.InvariantCulture)); AppendField(sb, evt.DurationMs?.ToString(CultureInfo.InvariantCulture)); AppendField(sb, evt.ErrorMessage, freeText: true); AppendField(sb, evt.ErrorDetail, freeText: true); AppendField(sb, evt.RequestSummary, freeText: true); AppendField(sb, evt.ResponseSummary, freeText: true); AppendField(sb, evt.PayloadTruncated.ToString()); AppendField(sb, evt.Extra, freeText: true); AppendField(sb, evt.ForwardState?.ToString()); return sb.ToString(); } private static string? FormatDate(DateTime? value) => value?.ToString("O", CultureInfo.InvariantCulture); private static string FormatDate(DateTime value) => value.ToString("O", CultureInfo.InvariantCulture); private static void AppendField(StringBuilder sb, string? value, bool first = false, bool freeText = false) { if (!first) sb.Append(','); if (string.IsNullOrEmpty(value)) { return; } // OWASP CSV-injection neutralization (CSV formula injection): a free-text cell whose // first character would be interpreted by a spreadsheet application as a // formula/DDE trigger is prefixed with a literal single quote. Applied // BEFORE RFC 4180 quoting, and only to free-text columns — never to the // GUID/enum/numeric/date/bool columns this formatter generates itself. if (freeText && NeedsFormulaNeutralization(value)) { value = "'" + value; } // RFC 4180: quote on comma / quote / CR / LF; double-up embedded quotes. if (value.IndexOfAny(s_quoteTriggers) < 0) { sb.Append(value); return; } sb.Append('"'); foreach (var ch in value) { if (ch == '"') { sb.Append('"').Append('"'); } else { sb.Append(ch); } } sb.Append('"'); } /// /// True when starts with a character a spreadsheet /// application would treat as a formula/DDE-launch trigger — the OWASP CSV /// Injection standard set: =, +, -, @, TAB, CR. /// private static bool NeedsFormulaNeutralization(string value) { var c = value[0]; return c == '=' || c == '+' || c == '-' || c == '@' || c == '\t' || c == '\r'; } private static readonly char[] s_quoteTriggers = { ',', '"', '\r', '\n' }; }