Guardian Audit

Tamper-evident audit logger that pairs with Guardian safety skill. Captures every destructive operation decision, agent reasoning, backup verification result, and human escalation response in an append-only, hash-chained log. Use when Guardian or any safety gatekeeper halts or approves an operation. Use when compliance requires proof of what AI agents did and why. Use when you need replay, forensics, or regulatory audit trails for agent actions. Triggers on any safety decision, destructive operation execution, escalation event, or when the user says "log this", "audit trail", "compliance", or "what did the agent do".

Guardian Audit — Tamper-Evident Audit Logger

"Trust, but log."

A companion skill to Guardian (or any safety gatekeeper) that captures every decision, action, and escalation in an append-only, hash-chained audit trail.

Why this exists: Guardian stops bad things. Guardian Audit proves it stopped them — or proves the agent did them anyway.

What It Logs

Every entry includes:

Field	Purpose
timestamp	ISO-8601 with millisecond precision
sequence	Monotonic integer, no gaps allowed
previous_hash	SHA-256 of previous entry (chain integrity)
event_type	GUARDIAN_CHECK, GUARDIAN_HALT, GUARDIAN_APPROVE, EXECUTED, ESCALATION_RESOLVED
agent_id	Anonymous identifier (no platform specifics)
operation	What the agent tried to do
target	File / path / database / endpoint
category	CRITICAL / HIGH / MEDIUM / NON-DESTRUCTIVE
backup_verdict	VERIFIED / UNVERIFIED / STALE / PARTIAL
backup_checks	JSON array of which indicators matched
decision	PROCEED / HALT / AWAITING_HUMAN / DENIED
approver	guardian-auto / human:anonymous / agent:rejected
agent_reasoning	The agent's stated justification (quoted)
guardian_notes	Why Guardian made this decision
outcome	SUCCESS / FAILURE / TIMEOUT / CANCELLED
entry_hash	SHA-256 of this entry's content

The Hash Chain

Entry[N].previous_hash = SHA256(Entry[N-1].content)
Entry[N].entry_hash = SHA256(Entry[N].content)

If any entry is modified, every subsequent entry's previous_hash fails verification. The chain is self-validating.

Log Format

Append-only line-delimited JSON (NDJSON), one entry per line:

{"timestamp":"2026-05-18T14:02:31.847Z","sequence":42,"previous_hash":"a3f7...","event_type":"GUARDIAN_HALT","agent_id":"agent-7f3a","operation":"rm -rf /tmp/old-builds","target":"/tmp/old-builds","category":"HIGH","backup_verdict":"UNVERIFIED","backup_checks":[],"decision":"HALT","approver":"guardian-auto","agent_reasoning":"Cleaning up old build artifacts","guardian_notes":"Mass delete operation with no backup coverage","outcome":"AWAITING_HUMAN","entry_hash":"9e2b..."}

Where Logs Live

Platform	Default Path
Windows	%LOCALAPPDATA%\guardian-audit\audit.log
macOS	~/.local/share/guardian-audit/audit.log
Linux	~/.local/share/guardian-audit/audit.log

Immutable by convention: The log file has append-only permissions. The executing agent cannot delete or modify entries. Only a human with elevated privileges can rotate logs.

Verification Script

# Verify chain integrity
./scripts/verify-chain.py audit.log
# Output: "Chain valid: 1,247 entries, 0 breaks"
# Or: "CHAIN BROKEN at entry 843: hash mismatch"

Integration with Guardian

Guardian calls Guardian Audit automatically after every decision:

Guardian Decision → Guardian Audit LOG → Continue / Halt

No additional agent action required. Guardian Audit is a passive listener that records what happened.

Standalone Use

Guardian Audit also works independently. Any safety tool, human approval, or agent action can emit an entry:

# From any agent or tool
from guardian_audit import log_event

log_event(
    event_type="MANUAL_APPROVE",
    operation="deploy-production",
    target="api.production.internal",
    decision="PROCEED",
    approver="human:anonymous",
    agent_reasoning="Emergency fix for auth bug"
)

Why This Matters

Compliance frameworks requiring audit trails:

• EU AI Act (Article 52): High-risk AI systems must maintain logs
• SOC 2 Type II: Change management and access control evidence
• HIPAA §164.312(b): Mechanisms to record and examine activity
• GDPR Article 5(1)(d): Accuracy and accountability

Forensics: When something goes wrong, you need to know:

• What did the agent try to do?
• Did Guardian stop it?
• Did a human approve it anyway?
• What was the agent's reasoning at the time?

Mandatory Rules

1. Append-Only: Entries are never deleted. Log rotation creates new files, never modifies existing ones.
2. Hash Chain: Every entry references the previous. Tampering is detectable.
3. No Agent Modification: The executing agent cannot modify its own audit trail. Ever.
4. Minimal Overhead: Logging adds <5ms per decision. No perceptible latency.
5. Human Readable: NDJSON format means tail -f audit.log is meaningful without tooling.

Scope

Vanilla: Not specific to Guardian. Works with any safety gatekeeper, human approval workflow, or agent runtime.

Passive: Does not block or delay operations. Logs after the fact.

Mandatory: Once enabled, all safety decisions are logged. No opt-out per-session.

References

• references/LOG-SCHEMA.md — Complete field definitions and validation rules
• references/COMPLIANCE-MAPPING.md — Framework requirements (EU AI Act, SOC 2, HIPAA, GDPR)
• references/REPLAY.md — How to replay, search, and analyze audit trails
• scripts/log-event.py — Python event logger (cross-platform)
• scripts/verify-chain.py — Chain integrity verification
• scripts/export-report.py — Generate compliance-ready reports

Based On

• IETF draft-sharif-agent-audit-trail-00 (Mar 2026): Standardized AI agent audit trail format
• AgentReceipt (2026): Immutable audit trails for AI agents
• OWASP Agentic AI Top 10: Logging and monitoring requirements
• GDPR Article 5 + EU AI Act Article 52: Regulatory audit trail mandates

License

MIT — Audit trails should be a public good.