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/policy/gate-bypass-audit-logging.md

2.7 KiB
Raw Blame History

Gate Bypass Audit Logging

Module

Policy

Status

IMPLEMENTED

Description

Dedicated gate bypass audit system that records who/when/why for any gate override, persisting actor identity, justification text, IP address, and CI context to an audit repository. Includes rate limiting support for bypass abuse prevention.

Implementation Details

  • PolicyGateEvaluator override support: src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs
    • Override mechanism integrated into multi-gate evaluation pipeline
    • Override requires justification string (non-empty)
    • Gate result types include PassWithNote for approved bypasses with audit trail
    • Each gate decision is logged with full context (gate name, decision, justification)
  • PolicyGateOptions: src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs -- gate configuration including override policies
  • ExceptionEffectRegistry: src/Policy/StellaOps.Policy.Engine/Adapters/ExceptionEffectRegistry.cs -- maps exception types to effects with audit trail
  • ExceptionApplication audit: src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionApplication.cs
    • Records every exception application with ExceptionId, FindingId, OriginalStatus, AppliedStatus, EffectName, EffectType, EvaluationRunId, PolicyBundleDigest, AppliedAt, Metadata
    • Metadata dictionary supports arbitrary context (IP address, CI pipeline ID, actor identity)
  • IExceptionApplicationRepository: src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/IExceptionApplicationRepository.cs
    • Query by ExceptionId, FindingId, EvaluationRunId, time range for audit review
    • Statistics: total applications, unique exceptions/findings/vulnerabilities, breakdowns by effect type and status
  • VerdictAttestationService: src/Policy/StellaOps.Policy.Engine/Attestation/VerdictAttestationService.cs -- DSSE-signed attestations for all verdict decisions including bypasses

E2E Test Plan

  • Apply gate override with justification; verify ExceptionApplication record includes justification in Metadata
  • Apply gate override; verify Metadata contains actor identity, IP address, and timestamp
  • Query GetByExceptionIdAsync for override exception; verify full audit trail returned
  • Apply 3 overrides in same evaluation run; query GetByEvaluationRunIdAsync; verify all 3 returned
  • Apply override with empty justification; verify override is rejected (justification required)
  • Query GetStatisticsAsync after multiple overrides; verify ByEffectType counts include override effects
  • Verify VerdictAttestationService creates DSSE-signed attestation for override decisions
  • Verify override decisions are included in GetByTimeRangeAsync query results for compliance export