stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/findings/admin-audit-trails.md

3.2 KiB
Raw Blame History

Admin audit trails (comprehensive logging of changes)

Module

Findings

Status

IMPLEMENTED

Description

Policy evaluation trace snapshots, evidence graph builder, and exception event auditing provide admin-level audit trails for governance.

Implementation Details

  • Ledger Event Write Service: src/Findings/StellaOps.Findings.Ledger/Services/LedgerEventWriteService.cs -- writes append-only ledger events; every finding state change, VEX decision, and policy evaluation is recorded as an immutable event with timestamp, actor, and payload.
  • Evidence Graph Builder: src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs -- constructs evidence subgraphs from ledger events and attestation pointers for audit visualization.
  • Attestation Pointer Service: src/Findings/StellaOps.Findings.Ledger/Services/AttestationPointerService.cs -- links findings to their attestation evidence for audit chain tracking.
  • Attestation Status Calculator: src/Findings/StellaOps.Findings.Ledger/Infrastructure/Attestation/AttestationStatusCalculator.cs -- computes attestation coverage status for audit dashboards.
  • Decision Service: src/Findings/StellaOps.Findings.Ledger/Services/DecisionService.cs (implements IDecisionService) -- records policy decisions with full trace context.
  • Decision Hook Interface: src/Findings/StellaOps.Findings.Ledger/Services/IDecisionHook.cs -- extension point for hooking into decision events for custom audit processing.
  • Ledger Incident Coordinator: src/Findings/StellaOps.Findings.Ledger/Services/Incident/LedgerIncidentCoordinator.cs -- coordinates incident response workflows with audit trail recording.
  • Ledger Telemetry: src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTelemetry.cs -- OpenTelemetry instrumentation for ledger operations providing trace-level audit visibility.
  • Ledger Timeline: src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTimeline.cs -- timeline view of ledger events for audit review.
  • Tests: src/Findings/StellaOps.Findings.Ledger.Tests/FindingsLedgerIntegrationTests.cs, src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerEventWriteServiceTests.cs, src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/LedgerEventWriteServiceIncidentTests.cs, src/Findings/StellaOps.Findings.Ledger.Tests/Observability/LedgerTelemetryTests.cs, LedgerTimelineTests.cs

E2E Test Plan

  • Submit a finding state change via LedgerEventWriteService and verify the event is recorded with correct timestamp, actor, and payload in the append-only ledger
  • Query the evidence graph for a finding that has multiple audit events and verify the graph shows the chronological chain of state changes
  • Trigger a policy decision and verify DecisionService records the full trace context (rule name, inputs, outcome) as an auditable event
  • Verify incident coordination audit: create an incident via LedgerIncidentCoordinator and confirm the incident creation, status changes, and resolution are all recorded in the ledger
  • Verify telemetry integration: perform a ledger operation and confirm OpenTelemetry spans are emitted with the correct operation name and attributes