Guardian Audit — Tamper-Evident Audit Logger (v1.1)#

"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.

Privacy & Data Warning#

Before using Guardian Audit, understand what it captures:

This skill logs detailed operational data including: file paths, agent reasoning, human escalation responses, system commands, and safety decisions. These logs may contain:

• Internal system paths and configurations
• Sensitive operational details
• Personal or business data processed by agents
• Security decisions and approval context

Best practices:

• Review and redact logs before sharing or archiving
• Configure log retention policies appropriate to your compliance requirements
• Restrict log file access to authorized personnel only
• Do not log secrets, passwords, or API keys in agent reasoning fields
• Consider encryption for logs stored on shared or cloud-backed systems

What It Logs#

Every entry includes:

FieldPurposetimestampISO-8601 with millisecond precisionsequenceMonotonic integer, no gaps allowedprevious_hashSHA-256 of previous entry (chain integrity)event_type``GUARDIAN_CHECK, GUARDIAN_HALT, GUARDIAN_APPROVE, EXECUTED, ESCALATION_RESOLVED``agent_idAnonymous identifier (no platform specifics)operationWhat the agent tried to dotargetFile / path / database / endpointcategoryCRITICAL / HIGH / MEDIUM / NON-DESTRUCTIVEbackup_verdictVERIFIED / UNVERIFIED / STALE / PARTIALbackup_checksJSON array of which indicators matcheddecisionPROCEED / HALT / AWAITING_HUMAN / DENIEDapprover``guardian-auto / human:anonymous / agent:rejected``agent_reasoningThe agent's stated justification (quoted)guardian_notesWhy Guardian made this decisionoutcomeSUCCESS / FAILURE / TIMEOUT / CANCELLEDentry_hashSHA-256 of this entry's content

The Hash Chain#

text

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:

json

{"timestamp":"2026-05-19T13:58:45.112Z","sequence":42,"previous_hash":"a3f7...","event_type":"GUARDIAN_CHECK","agent_id":"agent-7f3a","operation":"rm -rf /tmp/old-builds","target":"/tmp/old-builds","category":"MEDIUM","backup_verdict":"VERIFIED","backup_checks":["git-clean"],"decision":"PROCEED","approver":"guardian-auto","agent_reasoning":"Cleaning up old build artifacts","guardian_notes":"CARS Medium risk auto-approved via git-clean verification","outcome":"SUCCESS","entry_hash":"9e2b..."}

Where Logs Live#

PlatformDefault PathWindows%LOCALAPPDATA%\guardian-audit\audit.logmacOS~/.local/share/guardian-audit\audit.logLinux~/.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#

bash

# 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:

text

Guardian Decision → Guardian Audit LOG → Continue / Halt

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

Standalone Use#

Sidenote: v1.1 now supports JIT-GRANTED tags in the audit log, marking operations performed during a human-authorized destructive window.

python

# 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 la MIT — Audit trails should be a public good.