name: guardian-audit
version: 1.1
description: 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.
Support: support@ikkf.info

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

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.