Guardian Audit
Tamper-evident audit logger that pairs with Guardian safety skill. Captures safety decisions (halts, approvals, escalations) in an append-only, hash-chained log. Use when Guardian makes a safety decision. Use for compliance audit trails. Does NOT activate on general logging requests like 'log this' or routine queries. Requires explicit safety context or compliance intent to trigger.
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:
| 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-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
| 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
Sidenote: v1.1 now supports JIT-GRANTED tags in the audit log, marking operations performed during a human-authorized destructive window.
# 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
- Append-Only: Entries are never deleted. Log rotation creates new files, never modifies existing ones.
- Hash Chain: Every entry references the previous. Tampering is detectable.
- No Agent Modification: The executing agent cannot modify its own audit trail. Ever.
- Minimal Overhead: Logging adds <5ms per decision. No perceptible latency.
- Human Readable: NDJSON format means
tail -f audit.logis 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 rulesreferences/COMPLIANCE-MAPPING.md— Framework requirements (EU AI Act, SOC 2, HIPAA, GDPR)references/REPLAY.md— How to replay, search, and analyze audit trailsscripts/log-event.py— Python event logger (cross-platform)scripts/verify-chain.py— Chain integrity verificationscripts/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.
Related skills
- Downloads
- 1.1kAll time
- Security audit
- Review
- Last updated
- 6mo ago
- Current version
- v1.2.0
- License
- MIT-0
