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

Security Scan

The skill is an instruction-only design for a local append-only hash-chained audit log; its requirements and instructions align with the stated purpose and it does not request unrelated credentials or install software.

Purpose & Capability

Name, description, and runtime instructions all describe creating and maintaining a local append-only, sha256 hash-chained NDJSON audit log for agent events. No unrelated binaries, credentials, or remote endpoints are requested — this is coherent with an on-disk audit trail implementation.

Instruction Scope

Instructions are narrowly scoped to creating an audit directory/file, adding guidance to workspace docs (TOOLS.md, SOUL.md), and an optional local Python helper that appends hash-chained entries. However, the spec explicitly includes event kinds such as `credential-access` and `external-write`, which means logs could contain secrets or sensitive data if the agent records raw values; the guidance does not include explicit caution about redacting or protecting secrets in the log.

Install Mechanism

There is no install spec and no code files that need to be installed system-wide; the skill is instruction-only and the only code shown is an optional helper script intended to be placed under the workspace (no downloads or external installs). This is low risk from an install perspective.

Credentials

The skill requests no environment variables or credentials (proportional). But because it suggests auditing 'credential-access' events and external writes, operators should be aware the log may capture sensitive values. No env vars are required by the skill itself, so there is no direct credential exfiltration request in the manifest.

Persistence & Privilege

The skill is not always-on and is user-invocable; it does not request permanent platform privileges. Being instruction-only it does not modify other skill configurations or require platform-wide changes.

Scan Findings in Context

[no_regex_findings] expected: The regex-based scanner had no findings because this is an instruction-only skill with no packaged code to analyze. The included helper script is shown in SKILL.md and _meta.json but there were no automated matches flagged.

Assessment

This skill appears coherent and low-risk, but review these practical issues before installing: (1) Protect the audit file — set strict filesystem permissions (e.g., owner-only, 600) and consider append-only or immutable flags where supported. (2) Avoid logging raw secrets — decide whether credential-access events should record only metadata (justification, actor) and not secret values. (3) Consider atomicity and concurrency: multiple agents appending may cause ord/hash inconsistencies; implement locking or a centralized log writer for multi-agent environments. (4) For compliance, consider signing or storing logs in secure tamper-evident storage (WORM, secure object store, HSM-backed signing) rather than only local files. (5) Confirm timezone/ts expectations (the helper uses a fixed +01:00 offset) and adjust to your deployment. If you accept those precautions, the skill can be used as a local compliance audit trail.

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