guardrail-audit-log

Guardrail Audit Log

Core Rule

Every guardrail violation, warning, block, and override must be logged to a centralized, immutable audit trail. If you cannot prove a guardrail fired, you cannot prove the system is protected.

Why Centralized Audit Logging

Guardrail Event Schema

Every guardrail event — whether from a hook, skill, or runtime check — must conform to this schema:

interface GuardrailEvent {
  // Identity
  eventId: string;           // UUID — unique per event
  timestamp: string;         // ISO 8601 — when the guardrail fired

  // Classification
  guardrailLayer: 'input_output' | 'contextual' | 'security' | 'adaptive' | 'ethical_compliance';
  guardrailName: string;     // e.g., 'secrets-detection', 'bias-check', 'scope-creep'
  severity: 'info' | 'warning' | 'block' | 'override';

  // Context
  source: string;            // which hook, skill, or check generated this event
  trigger: string;           // what triggered the guardrail (file path, command, code pattern)
  description: string;       // human-readable explanation

  // Resolution
  action: 'allowed' | 'warned' | 'blocked' | 'overridden';
  resolution?: string;       // how it was resolved (if overridden, why)
  resolvedBy?: string;       // who resolved it (user, system, auto)

  // Metadata
  sessionId?: string;        // session that generated this event
  projectId?: string;        // project identifier
  tier?: string;             // user tier at time of event
  tags?: string[];           // additional classification tags
}