40 lines
3.9 KiB
Markdown
40 lines
3.9 KiB
Markdown
# Admin audit trails (comprehensive logging of changes)
|
|
|
|
## Module
|
|
Findings
|
|
|
|
## Status
|
|
PARTIALLY_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
|
|
|
|
## Verification
|
|
- Run: `docs/qa/feature-checks/runs/findings/admin-audit-trails/run-001/`
|
|
- Date (UTC): 2026-02-11
|
|
- Verdict: `not_implemented`
|
|
|
|
## Missing / Mismatched Behavior
|
|
- `DecisionService.RecordAsync` creates drafts with `SequenceNumber = 0`, but `LedgerEventWriteService` requires strict expected sequence values, so decision append behavior is not fully wired for production audit trails.
|
|
- `DecisionService.GetHistoryAsync` currently returns an empty list stub, so audit timeline retrieval is not fully implemented.
|
|
- Active WebService runtime wiring uses `NullEvidenceRepository` and `InMemoryFindingRepository`, so evidence graph and related admin audit views are scaffolded but not backed by persisted runtime data.
|