Agent Audit Trail Skill

Tamper-evident, hash-chained audit logging for AI agents.

Why

Agents act on your behalf. You need to know what they did, when, and be able to prove nothing was altered after the fact.

This skill provides:

• Append-only NDJSON logs — human-readable, grep-friendly
• Hash chaining — each entry includes SHA-256 of previous + current, making tampering detectable
• Monotonic ordering — sequential ord tokens for gate-relevant events
• Verification — one command to validate the entire chain

Quick Start

1. Add to your agent's workspace

Copy scripts/auditlog.py to your workspace's scripts/ directory.

cp scripts/auditlog.py /path/to/your/workspace/scripts/
chmod +x /path/to/your/workspace/scripts/auditlog.py

2. Log an action

./scripts/auditlog.py append \
  --kind "file-write" \
  --summary "Created config.yaml" \
  --target "config.yaml" \
  --domain "personal"

3. Verify integrity

./scripts/auditlog.py verify
# Output: OK (or error with line number if tampered)

Usage

Appending entries

./scripts/auditlog.py append \
  --kind <event-type> \
  --summary <description> \
  [--domain <domain>] \
  [--target <identifier>] \
  [--gate <gate-reference>] \
  [--provenance '{"source": "...", "channel": "..."}'] \
  [--details '{"key": "value"}']

Required:

• --kind: Event type (e.g., file-write, exec, api-call, credential-access)
• --summary: Human-readable description

Optional:

• --domain: Logical domain (default: unknown)
• --target: What was acted upon (file path, URL, command)
• --gate: Reference to approval gate (for gated actions)
• --provenance: JSON object with source attribution
• --details: JSON object with additional structured data

Verifying the chain

./scripts/auditlog.py verify [--log path/to/audit.ndjson]

Returns exit code 0 and prints OK if valid, or prints the failing line number and hash mismatch details.

Log Format

Each line is a JSON object:

{
  "ts": "2026-02-05T07:15:00+00:00",
  "kind": "file-write",
  "actor": "atlas",
  "domain": "personal",
  "plane": "action",
  "target": "config.yaml",
  "summary": "Created config.yaml",
  "ord": 42,
  "chain": {
    "prev": "abc123...",
    "hash": "def456...",
    "algo": "sha256(prev\nline_c14n)"
  }
}

Fields

Integration with OpenClaw

Heartbeat verification