Agent Audit Trail

Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256...

An append-only, hash-chained audit log for AI agents. Every significant action, decision, tool call, and external write is recorded with a sha256 chain linking entries together — making tampering detectable and providing an authoritative compliance record.

Overview

This skill provides:

• Append-only NDJSON log at audit/atlas-actions.ndjson
• Hash-chained entries — each entry includes the sha256 of the previous entry
• Monotonic ordering — ord field ensures strict sequence
• Structured fields — consistent schema across all event types
• EU AI Act Article 12 compliance implementation

Log Location

audit/atlas-actions.ndjson

The file is append-only. Never truncate, overwrite, or reorder entries.

Log Entry Schema

Each line is a valid JSON object:

{
  "ts":         "2026-04-02T18:00:00.000+01:00",
  "kind":       "tool-call",
  "actor":      "atlas",
  "domain":     "agirails",
  "plane":      "action",
  "gate":       "external-write",
  "ord":        42,
  "provenance": "session:agent:main:discord:channel:1472016988741177520",
  "target":     "audit/atlas-actions.ndjson",
  "summary":    "Appended audit log entry",
  "prev_hash":  "sha256:abc123...",
  "hash":       "sha256:def456..."
}

Field Reference

Field	Type	Description
ts	ISO-8601	Timestamp with timezone offset (Europe/London)
kind	string	Event type (see below)
actor	string	Agent or component that triggered the event
domain	string	Domain partition (agirails, client-lab, personal)
plane	string	Four-plane label (ingress, interpretation, decision, action)
gate	string	Truth gate applied (see SOUL.md)
ord	integer	Monotonically increasing sequence number
provenance	string	Source session or external identity
target	string	File, URL, or resource affected
summary	string	Human-readable description of the event
prev_hash	string	sha256 of the previous log entry (hex, prefixed sha256:)
hash	string	sha256 of this entry excluding the hash field itself

Event Kinds

Kind	Plane	Description
tool-call	action	Any tool invocation
external-write	action	Write to external system (file, API, DB)
credential-access	action	Secret or key accessed
install-extend	action	Package install or skill activation
decision	decision	Agent decision with reasoning
override	decision	Safety override applied
ingress	ingress	External input received
session-start	ingress	Agent session initialised
session-end	ingress	Agent session terminated
state-transition	decision	Behaviour surface change
payment	action	ACTP/x402 payment event (amount, counterparty, txhash)

Setup

1. Create the audit directory

mkdir -p audit
touch audit/atlas-actions.ndjson

2. Wire into TOOLS.md

Add to your workspace TOOLS.md:

## Audit Log
- Path: `audit/atlas-actions.ndjson`
- Format: append-only NDJSON, hash-chained (sha256), monotonic `ord`
- Timestamps: Europe/London ISO-8601 with offset
- Fields: ts, kind, actor, domain, plane, gate, ord, provenance, target, summary

3. Wire into SOUL.md

Add to your workspace SOUL.md invariants:

4. Append-only, hash-chained audit log with monotonic ordering
10. Behavior surface changes logged as state transitions

And to Truth Gates:

- external-write: provenance + intent + approval + tool-log + ordering
- credential-access: domain scope + justification + audit + human approval
- install-extend: integrity proof + scope + rollback ref + human approval

4. Helper script (optional)

# scripts/audit_append.py
import json, hashlib, time, sys
from datetime import datetime, timezone, timedelta
from pathlib import Path

LOG = Path("audit/atlas-actions.ndjson")
TZ  = timezone(timedelta(hours=1))  # Europe/London BST; adjust for GMT

def last_hash():
    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []
    if not lines:
        return "sha256:0" * 1  # genesis
    last = json.loads(lines[-1])
    return last.get("hash", "sha256:genesis")

def last_ord():
    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []
    if not lines:
        return 0
    return json.loads(lines[-1]).get("ord", 0)

def append(kind, actor, domain, plane, gate, provenance, target, summary):
    entry = {
        "ts":         datetime.now(TZ).isoformat(),
        "kind":       kind,
        "actor":      actor,
        "domain":     domain,
        "plane":      plane,
        "gate":       gate,
        "ord":        last_ord() + 1,
        "provenance": provenance,
        "target":     target,
        "summary":    summary,
        "prev_hash":  last_hash(),
    }
    raw    = json.dumps({k: v for k, v in entry.items()}, separators=(",", ":"))
    digest = "sha256:" + hashlib.sha256(raw.encode()).hexdigest()
    entry["hash"] = digest
    with LOG.open("a") as f:
        f.write(json.dumps(entry) + "\n")
    return entry

if __name__ == "__main__":
    # Example: python3 scripts/audit_append.py
    append("session-start", "atlas", "personal", "ingress", "none",
           "manual", "audit/atlas-actions.ndjson", "Session initialised")

Verification

To check chain integrity:

python3 - <<'EOF'
import json, hashlib
from pathlib import Path

LOG = Path("audit/atlas-actions.ndjson")
lines = LOG.read_text().strip().splitlines()
prev = "sha256:genesis"

for i, line in enumerate(lines):
    entry = json.loads(line)
    stored_hash = entry.pop("hash")
    raw = json.dumps(entry, separators=(",", ":"))
    computed = "sha256:" + hashlib.sha256(raw.encode()).hexdigest()
    if stored_hash != computed:
        print(f"CHAIN BROKEN at entry {i} (ord={entry.get('ord')})")
        break
    if entry.get("prev_hash") != prev:
        print(f"PREV_HASH MISMATCH at entry {i}")
        break
    prev = stored_hash

else:
    print(f"Chain OK — {len(lines)} entries verified")
EOF

Usage Patterns

Log every external write

append(
    kind="external-write",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="external-write",
    provenance="session:agent:main:discord:...",
    target="https://api.agirails.xyz/v1/escrow",
    summary="Created ACTP escrow 0xabc... for 10 USDC"
)

Log credential access

append(
    kind="credential-access",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="credential-access",
    provenance="session:agent:main",
    target=".env:ACTP_KEY_PASSWORD",
    summary="Accessed ACTP wallet key for testnet payment"
)

Log payment events

append(
    kind="payment",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="external-write",
    provenance="session:agent:main",
    target="base-sepolia:0xabc...def",
    summary="x402 payment: 5 USDC → counterparty 0x123, txhash 0xdef..."
)

---

EU AI Act Compliance

Article 12 — Automatic Event Recording

EU AI Act Article 12 mandates that providers of high-risk AI systems must ensure their systems can automatically record events ("logging") throughout their operational lifetime. Requirements include:

• Automatic recording of the period of each use (date, time)
• Reference database(s) searched or verified against
• Input data that led to the system output
• Identity of the natural/legal persons involved in verification

August 2026 deadline — High-risk AI systems must be compliant by the enforcement date under the EU AI Act transition schedule.

How This Skill Implements Article 12

Article 12 Requirement	This Skill's Implementation
Automatic event recording	audit_append.py — every tool call, decision, ingress
Period of use (timestamps)	ts field — ISO-8601 with timezone offset
Input data traceability	provenance + ingress kind entries
Decision traceability	decision kind entries with reasoning summary
Identity of actors	actor + provenance fields
Tamper detection	sha256 hash chain — prev_hash + hash fields
Ordering guarantees	Monotonic ord field

Classification Guidance

Assess whether your agent deployment qualifies as high-risk under Annex III of the EU AI Act. If operating in:

• Critical infrastructure
• Employment/HR decisions
• Access to essential services
• Law enforcement adjacent systems
• Migration/asylum decisions

…then Article 12 logging is mandatory, not optional. Run the Agent Compliance & Security Assessment skill first to determine your risk classification.

---

Companion Skills

agent-self-assessment (v2.2.1)

Run the assessment first, then set up logging for ongoing compliance.

The self-assessment skill provides a 14-check compliance and security framework with RED/AMBER/GREEN ratings. Use it to determine your EU AI Act risk classification before configuring this audit trail.

Install:

clawhub install agent-self-assessment

Or if already available in your workspace:

Read ~/.openclaw/workspace/skills/agent-self-assessment/SKILL.md

Workflow:

1. Run agent-self-assessment → identify gaps + risk tier
2. Install agent-audit-trail → implement logging for ongoing compliance
3. Schedule periodic re-assessments (monthly/quarterly)

---

agirails (v3.0.0)

Enable payment tracking in your audit trail.

AGIRAILS provides ACTP escrow and x402 instant payment primitives for AI agents. All payments should be logged using the payment kind in this audit trail.

Install:

clawhub install agirails

Or if already available in your workspace:

Read ~/.openclaw/workspace/skills/agirails/SKILL.md

Payment logging integration:

• Every ACTP escrow creation → external-write entry
• Every x402 settlement → payment entry with txhash
• Every wallet balance change → state-transition entry
• Wallet address and amount included in summary

See TOOLS.md → Audit Log and SOUL.md invariant #4 for the full integration.

---

Roadmap (v2.1+)

The following features are planned for upcoming releases:

export command

Generate a structured compliance report from the NDJSON log:

• Filter by date range, domain, kind, actor
• Output: Markdown, PDF, or JSON summary
• EU AI Act Article 12 report template included
• Example: python3 scripts/audit_export.py --from 2026-01-01 --to 2026-04-01 --domain agirails

stats command

Event counts, domain breakdown, and time-range queries:

• Total events per kind
• Events per domain over configurable time window
• Busiest hours / session lengths
• Example: python3 scripts/audit_stats.py --range 7d --by domain

JSON Schema for log validation

A formal JSON Schema (audit/log-schema.json) to validate entries:

• Validate all required fields are present and correctly typed
• CI-friendly: run on every log append or as a pre-push hook
• Schema versioned alongside SKILL.md

Optional remote log shipping (append-only S3/GCS)

Ship log entries to an append-only remote bucket for disaster recovery:

• AWS S3 (object lock / WORM policy)
• Google Cloud Storage (object retention policy)
• Configurable flush interval (real-time or batched)
• No reads from remote — write-only pipeline

Compliance report template (EU AI Act Article 12)

A structured report template covering:

• System description and risk classification
• Logging configuration and retention policy
• Chain integrity verification results
• Event summary by category
• Named actors and provenance registry
• Attestation block for human signatory

---

This skill is part of the Atlas workspace compliance stack. See also: SOUL.md (invariants), TOOLS.md (audit log config), agent-self-assessment (risk classification).