{"id":"1f6a888e-a77f-469f-ad52-9148b1c44470","entityType":"agent","slug":"clawhub-roosch269-agent-audit-trail","name":"Agent Audit Trail","canonicalUrl":"https://www.xpersona.co/agent/clawhub-roosch269-agent-audit-trail","canonicalPath":"/agent/clawhub-roosch269-agent-audit-trail","generatedAt":"2026-10-09T16:24:56.061Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":null},"description":"Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... Skill: Agent Audit Trail Owner: roosch269 Summary: Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... Tags: accountability:2.1.0, article-12:2.1.0, audit:2.1.0, compliance:2.1.0, eu-ai-act:2.1.0, hash-chain:1.0.0, latest:2.1.0, security:2.1.0, trust:1.0.0 Version history: v2.1.0 | 2026-04-02T17:55:47.302Z | us","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.8K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s177h8y1kddnjj28j50dph6c3983gbsv:agent-audit-trail","sourceUrl":"https://clawhub.ai/roosch269/agent-audit-trail","homepage":"https://clawhub.ai/roosch269/skills/agent-audit-trail","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/roosch269/agent-audit-trail","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/roosch269/skills/agent-audit-trail","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":null},"stars":null,"forks":null,"downloads":2802,"packageName":null,"latestVersion":"2.1.0","tractionLabel":"2.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T11:26:48.273Z","lastCrawledAt":"2026-10-09T11:26:48.273Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T11:26:48.273Z","lastVerifiedAt":null,"highlights":[{"version":"2.1.0","createdAt":"2026-04-02T17:55:47.302Z","changelog":"v2.1: EU AI Act Article 12 compliance mapping, companion skills (Self-Assessment v2.2.1 + AGIRAILS), roadmap for export/stats/remote shipping.","fileCount":3,"zipByteSize":6655},{"version":"2.0.0","createdAt":"2026-02-24T07:27:21.830Z","changelog":"EU AI Act compliance mapping","fileCount":6,"zipByteSize":11728},{"version":"1.0.0","createdAt":"2026-02-15T11:20:28.994Z","changelog":"Initial ClawHub release. Tamper-evident hash-chained audit logging for AI agents. Zero dependencies, Python 3.9+.","fileCount":5,"zipByteSize":9065}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177h8y1kddnjj28j50dph6c3983gbsv:agent-audit-trail","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T16:24:56.061Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-roosch269-agent-audit-trail/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":null},"readme":"Skill: Agent Audit Trail\n\nOwner: roosch269\n\nSummary: Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256...\n\nTags: accountability:2.1.0, article-12:2.1.0, audit:2.1.0, compliance:2.1.0, eu-ai-act:2.1.0, hash-chain:1.0.0, latest:2.1.0, security:2.1.0, trust:1.0.0\n\nVersion history:\n\nv2.1.0 | 2026-04-02T17:55:47.302Z | user\n\nv2.1: EU AI Act Article 12 compliance mapping, companion skills (Self-Assessment v2.2.1 + AGIRAILS), roadmap for export/stats/remote shipping.\n\nv2.0.0 | 2026-02-24T07:27:21.830Z | user\n\nEU AI Act compliance mapping\n\nv1.0.0 | 2026-02-15T11:20:28.994Z | user\n\nInitial ClawHub release. Tamper-evident hash-chained audit logging for AI agents. Zero dependencies, Python 3.9+.\n\nArchive index:\n\nArchive v2.1.0: 3 files, 6655 bytes\n\nFiles: _meta.json (136b), skill-card.md (2281b), SKILL.md (12757b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: Agent Audit Trail\nversion: 2.1.0\ndescription: >\n  Append-only, hash-chained audit log for AI agents. Records agent actions,\n  tool calls, decisions, and external writes with provenance, timestamps, and\n  sha256 chain integrity. Designed for compliance with EU AI Act Article 12\n  automatic event recording requirements for high-risk AI systems.\nauthor:\n  name: Justin Roosch\n  url: https://github.com/roosch269\nlicense: MIT-0\ntags:\n  - audit\n  - compliance\n  - logging\n  - eu-ai-act\n  - article-12\n  - governance\n  - provenance\n  - security\nkeywords:\n  - audit trail\n  - agent logging\n  - hash chain\n  - event log\n  - compliance logging\n---\n\n# Agent Audit Trail\n\nAn 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.\n\n## Overview\n\nThis skill provides:\n- **Append-only NDJSON log** at `audit/atlas-actions.ndjson`\n- **Hash-chained entries** — each entry includes the sha256 of the previous entry\n- **Monotonic ordering** — `ord` field ensures strict sequence\n- **Structured fields** — consistent schema across all event types\n- **EU AI Act Article 12** compliance implementation\n\n## Log Location\n\n```\naudit/atlas-actions.ndjson\n```\n\nThe file is append-only. Never truncate, overwrite, or reorder entries.\n\n## Log Entry Schema\n\nEach line is a valid JSON object:\n\n```json\n{\n  \"ts\":         \"2026-04-02T18:00:00.000+01:00\",\n  \"kind\":       \"tool-call\",\n  \"actor\":      \"atlas\",\n  \"domain\":     \"agirails\",\n  \"plane\":      \"action\",\n  \"gate\":       \"external-write\",\n  \"ord\":        42,\n  \"provenance\": \"session:agent:main:discord:channel:1472016988741177520\",\n  \"target\":     \"audit/atlas-actions.ndjson\",\n  \"summary\":    \"Appended audit log entry\",\n  \"prev_hash\":  \"sha256:abc123...\",\n  \"hash\":       \"sha256:def456...\"\n}\n```\n\n### Field Reference\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `ts` | ISO-8601 | Timestamp with timezone offset (Europe/London) |\n| `kind` | string | Event type (see below) |\n| `actor` | string | Agent or component that triggered the event |\n| `domain` | string | Domain partition (`agirails`, `client-lab`, `personal`) |\n| `plane` | string | Four-plane label (`ingress`, `interpretation`, `decision`, `action`) |\n| `gate` | string | Truth gate applied (see SOUL.md) |\n| `ord` | integer | Monotonically increasing sequence number |\n| `provenance` | string | Source session or external identity |\n| `target` | string | File, URL, or resource affected |\n| `summary` | string | Human-readable description of the event |\n| `prev_hash` | string | sha256 of the previous log entry (hex, prefixed `sha256:`) |\n| `hash` | string | sha256 of this entry excluding the `hash` field itself |\n\n### Event Kinds\n\n| Kind | Plane | Description |\n|------|-------|-------------|\n| `tool-call` | action | Any tool invocation |\n| `external-write` | action | Write to external system (file, API, DB) |\n| `credential-access` | action | Secret or key accessed |\n| `install-extend` | action | Package install or skill activation |\n| `decision` | decision | Agent decision with reasoning |\n| `override` | decision | Safety override applied |\n| `ingress` | ingress | External input received |\n| `session-start` | ingress | Agent session initialised |\n| `session-end` | ingress | Agent session terminated |\n| `state-transition` | decision | Behaviour surface change |\n| `payment` | action | ACTP/x402 payment event (amount, counterparty, txhash) |\n\n## Setup\n\n### 1. Create the audit directory\n\n```bash\nmkdir -p audit\ntouch audit/atlas-actions.ndjson\n```\n\n### 2. Wire into TOOLS.md\n\nAdd to your workspace `TOOLS.md`:\n\n```markdown\n## Audit Log\n- Path: `audit/atlas-actions.ndjson`\n- Format: append-only NDJSON, hash-chained (sha256), monotonic `ord`\n- Timestamps: Europe/London ISO-8601 with offset\n- Fields: ts, kind, actor, domain, plane, gate, ord, provenance, target, summary\n```\n\n### 3. Wire into SOUL.md\n\nAdd to your workspace `SOUL.md` invariants:\n\n```\n4. Append-only, hash-chained audit log with monotonic ordering\n10. Behavior surface changes logged as state transitions\n```\n\nAnd to Truth Gates:\n\n```\n- external-write: provenance + intent + approval + tool-log + ordering\n- credential-access: domain scope + justification + audit + human approval\n- install-extend: integrity proof + scope + rollback ref + human approval\n```\n\n### 4. Helper script (optional)\n\n```python\n# scripts/audit_append.py\nimport json, hashlib, time, sys\nfrom datetime import datetime, timezone, timedelta\nfrom pathlib import Path\n\nLOG = Path(\"audit/atlas-actions.ndjson\")\nTZ  = timezone(timedelta(hours=1))  # Europe/London BST; adjust for GMT\n\ndef last_hash():\n    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []\n    if not lines:\n        return \"sha256:0\" * 1  # genesis\n    last = json.loads(lines[-1])\n    return last.get(\"hash\", \"sha256:genesis\")\n\ndef last_ord():\n    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []\n    if not lines:\n        return 0\n    return json.loads(lines[-1]).get(\"ord\", 0)\n\ndef append(kind, actor, domain, plane, gate, provenance, target, summary):\n    entry = {\n        \"ts\":         datetime.now(TZ).isoformat(),\n        \"kind\":       kind,\n        \"actor\":      actor,\n        \"domain\":     domain,\n        \"plane\":      plane,\n        \"gate\":       gate,\n        \"ord\":        last_ord() + 1,\n        \"provenance\": provenance,\n        \"target\":     target,\n        \"summary\":    summary,\n        \"prev_hash\":  last_hash(),\n    }\n    raw    = json.dumps({k: v for k, v in entry.items()}, separators=(\",\", \":\"))\n    digest = \"sha256:\" + hashlib.sha256(raw.encode()).hexdigest()\n    entry[\"hash\"] = digest\n    with LOG.open(\"a\") as f:\n        f.write(json.dumps(entry) + \"\\n\")\n    return entry\n\nif __name__ == \"__main__\":\n    # Example: python3 scripts/audit_append.py\n    append(\"session-start\", \"atlas\", \"personal\", \"ingress\", \"none\",\n           \"manual\", \"audit/atlas-actions.ndjson\", \"Session initialised\")\n```\n\n## Verification\n\nTo check chain integrity:\n\n```bash\npython3 - <<'EOF'\nimport json, hashlib\nfrom pathlib import Path\n\nLOG = Path(\"audit/atlas-actions.ndjson\")\nlines = LOG.read_text().strip().splitlines()\nprev = \"sha256:genesis\"\n\nfor i, line in enumerate(lines):\n    entry = json.loads(line)\n    stored_hash = entry.pop(\"hash\")\n    raw = json.dumps(entry, separators=(\",\", \":\"))\n    computed = \"sha256:\" + hashlib.sha256(raw.encode()).hexdigest()\n    if stored_hash != computed:\n        print(f\"CHAIN BROKEN at entry {i} (ord={entry.get('ord')})\")\n        break\n    if entry.get(\"prev_hash\") != prev:\n        print(f\"PREV_HASH MISMATCH at entry {i}\")\n        break\n    prev = stored_hash\n\nelse:\n    print(f\"Chain OK — {len(lines)} entries verified\")\nEOF\n```\n\n## Usage Patterns\n\n### Log every external write\n\n```python\nappend(\n    kind=\"external-write\",\n    actor=\"atlas\",\n    domain=\"agirails\",\n    plane=\"action\",\n    gate=\"external-write\",\n    provenance=\"session:agent:main:discord:...\",\n    target=\"https://api.agirails.xyz/v1/escrow\",\n    summary=\"Created ACTP escrow 0xabc... for 10 USDC\"\n)\n```\n\n### Log credential access\n\n```python\nappend(\n    kind=\"credential-access\",\n    actor=\"atlas\",\n    domain=\"agirails\",\n    plane=\"action\",\n    gate=\"credential-access\",\n    provenance=\"session:agent:main\",\n    target=\".env:ACTP_KEY_PASSWORD\",\n    summary=\"Accessed ACTP wallet key for testnet payment\"\n)\n```\n\n### Log payment events\n\n```python\nappend(\n    kind=\"payment\",\n    actor=\"atlas\",\n    domain=\"agirails\",\n    plane=\"action\",\n    gate=\"external-write\",\n    provenance=\"session:agent:main\",\n    target=\"base-sepolia:0xabc...def\",\n    summary=\"x402 payment: 5 USDC → counterparty 0x123, txhash 0xdef...\"\n)\n```\n\n---\n\n## EU AI Act Compliance\n\n### Article 12 — Automatic Event Recording\n\nEU 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:\n\n- Automatic recording of the period of each use (date, time)\n- Reference database(s) searched or verified against\n- Input data that led to the system output\n- Identity of the natural/legal persons involved in verification\n\n**August 2026 deadline** — High-risk AI systems must be compliant by the enforcement date under the EU AI Act transition schedule.\n\n### How This Skill Implements Article 12\n\n| Article 12 Requirement | This Skill's Implementation |\n|------------------------|----------------------------|\n| Automatic event recording | `audit_append.py` — every tool call, decision, ingress |\n| Period of use (timestamps) | `ts` field — ISO-8601 with timezone offset |\n| Input data traceability | `provenance` + `ingress` kind entries |\n| Decision traceability | `decision` kind entries with reasoning summary |\n| Identity of actors | `actor` + `provenance` fields |\n| Tamper detection | sha256 hash chain — `prev_hash` + `hash` fields |\n| Ordering guarantees | Monotonic `ord` field |\n\n### Classification Guidance\n\nAssess whether your agent deployment qualifies as high-risk under Annex III of the EU AI Act. If operating in:\n- Critical infrastructure\n- Employment/HR decisions\n- Access to essential services\n- Law enforcement adjacent systems\n- Migration/asylum decisions\n\n…then Article 12 logging is **mandatory**, not optional. Run the **Agent Compliance & Security Assessment** skill first to determine your risk classification.\n\n---\n\n## Companion Skills\n\n### `agent-self-assessment` (v2.2.1)\n> Run the assessment first, then set up logging for ongoing compliance.\n\nThe 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.\n\n**Install:**\n```bash\nclawhub install agent-self-assessment\n```\n\nOr if already available in your workspace:\n```\nRead ~/.openclaw/workspace/skills/agent-self-assessment/SKILL.md\n```\n\n**Workflow:**\n1. Run `agent-self-assessment` → identify gaps + risk tier\n2. Install `agent-audit-trail` → implement logging for ongoing compliance\n3. Schedule periodic re-assessments (monthly/quarterly)\n\n---\n\n### `agirails` (v3.0.0)\n> Enable payment tracking in your audit trail.\n\nAGIRAILS provides ACTP escrow and x402 instant payment primitives for AI agents. All payments should be logged using the `payment` kind in this audit trail.\n\n**Install:**\n```bash\nclawhub install agirails\n```\n\nOr if already available in your workspace:\n```\nRead ~/.openclaw/workspace/skills/agirails/SKILL.md\n```\n\n**Payment logging integration:**\n- Every ACTP escrow creation → `external-write` entry\n- Every x402 settlement → `payment` entry with txhash\n- Every wallet balance change → `state-transition` entry\n- Wallet address and amount included in `summary`\n\nSee `TOOLS.md` → **Audit Log** and `SOUL.md` invariant #4 for the full integration.\n\n---\n\n## Roadmap (v2.1+)\n\nThe following features are planned for upcoming releases:\n\n### `export` command\nGenerate a structured compliance report from the NDJSON log:\n- Filter by date range, domain, kind, actor\n- Output: Markdown, PDF, or JSON summary\n- EU AI Act Article 12 report template included\n- Example: `python3 scripts/audit_export.py --from 2026-01-01 --to 2026-04-01 --domain agirails`\n\n### `stats` command\nEvent counts, domain breakdown, and time-range queries:\n- Total events per kind\n- Events per domain over configurable time window\n- Busiest hours / session lengths\n- Example: `python3 scripts/audit_stats.py --range 7d --by domain`\n\n### JSON Schema for log validation\nA formal JSON Schema (`audit/log-schema.json`) to validate entries:\n- Validate all required fields are present and correctly typed\n- CI-friendly: run on every log append or as a pre-push hook\n- Schema versioned alongside SKILL.md\n\n### Optional remote log shipping (append-only S3/GCS)\nShip log entries to an append-only remote bucket for disaster recovery:\n- AWS S3 (object lock / WORM policy)\n- Google Cloud Storage (object retention policy)\n- Configurable flush interval (real-time or batched)\n- No reads from remote — write-only pipeline\n\n### Compliance report template (EU AI Act Article 12)\nA structured report template covering:\n- System description and risk classification\n- Logging configuration and retention policy\n- Chain integrity verification results\n- Event summary by category\n- Named actors and provenance registry\n- Attestation block for human signatory\n\n---\n\n*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).*\n\nFile v2.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn71asv5ce1x1ytv32k5av44gx817hff\",\n  \"slug\": \"agent-audit-trail\",\n  \"version\": \"2.1.0\",\n  \"publishedAt\": 1775152547302\n}\n\nFile v2.1.0:skill-card.md\n\n## Description:\n\nAppend-only, hash-chained audit log for AI agents that records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256 chain integrity for EU AI Act Article 12 logging support.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[roosch269](https://clawhub.ai/user/roosch269)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators of AI agents use this skill to add an append-only NDJSON audit log that records actions, tool calls, decisions, external writes, and provenance for compliance review and tamper-evidence.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill creates durable local records of agent activity that may include sensitive session, credential, wallet, transaction, or other operational metadata.\n\nMitigation: Restrict audit-log file permissions, define a retention policy, and redact sensitive identifiers and metadata before using the log for compliance or incident evidence.\n\nRisk: The security evidence notes reliability flaws in the sample integrity logic, including the need to fix hash-chain genesis behavior and writer coordination.\n\nMitigation: Fix the hash-chain genesis mismatch and use locking or a single-writer design before relying on the log for compliance or incident evidence.\n\nRisk: Companion skills may extend agent behavior or integrations beyond this audit trail.\n\nMitigation: Verify companion skills before installing or wiring them into an agent workflow.\n\n## Reference(s):\n\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with JSON, Python, and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local NDJSON audit-log setup and verification guidance; persistent logs may contain sensitive activity metadata.]\n\n## Skill Version(s):\n\n2.1.0 (source: frontmatter, _meta.json, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.0.0: 6 files, 11728 bytes\n\nFiles: examples/basic-usage.sh (1549b), examples/eu-ai-act-compliance.sh (2208b), README.md (10423b), scripts/auditlog.py (9516b), SKILL.md (2851b), _meta.json (136b)\n\nFile v2.0.0:SKILL.md\n\n# Agent Audit Trail Skill\n\nTamper-evident, hash-chained audit logging for AI agents. EU AI Act compliant.\n\n## Why\n\nAI agents act on your behalf. From **2 August 2026**, the EU AI Act requires automatic logging, tamper-evident records, and human oversight capability for AI systems. This skill provides all three with zero dependencies.\n\n## Quick Start\n\n### 1. Add to your agent's workspace\n\n```bash\ncp scripts/auditlog.py /path/to/your/workspace/scripts/\nchmod +x /path/to/your/workspace/scripts/auditlog.py\n```\n\n### 2. Log an action\n\n```bash\n./scripts/auditlog.py append \\\n  --kind \"file-write\" \\\n  --summary \"Created config.yaml\" \\\n  --target \"config.yaml\" \\\n  --domain \"personal\"\n```\n\n### 3. Verify integrity\n\n```bash\n./scripts/auditlog.py verify\n# Output: OK (N entries verified)\n```\n\n## Compliance Mapping\n\n| EU AI Act Article | Requirement | How This Skill Helps |\n|-------------------|-------------|---------------------|\n| **Art. 12** Record-Keeping | Automatic event logging | Every action logged with timestamp, actor, domain, target |\n| **Art. 12** Integrity | Tamper-evident records | SHA-256 hash chaining — modification breaks the chain |\n| **Art. 14** Human Oversight | Human approval linkage | `--gate` flag links actions to human approval references |\n| **Art. 50** Transparency | Auditable records | Human-readable NDJSON, one-command verification |\n| **Art. 12** Traceability | Chronological ordering | Monotonic `ord` tokens |\n\n## Event Kinds\n\nUse these standardised event types for consistent audit trails:\n\n| Kind | When to Use |\n|------|------------|\n| `file-write` | Agent creates or modifies files |\n| `exec` | Agent runs a command |\n| `api-call` | External API interaction |\n| `decision` | AI makes or recommends a decision |\n| `credential-access` | Secrets or credentials accessed |\n| `external-write` | Agent writes to external systems |\n| `human-override` | Human overrides an AI decision |\n| `disclosure` | AI identity disclosed to user |\n\n## Full Documentation\n\nSee [README.md](README.md) for complete usage, integration examples, security model, and EU AI Act compliance guide.\n\n## Log Format\n\n```json\n{\n  \"ts\": \"2026-02-24T07:15:00+00:00\",\n  \"kind\": \"exec\",\n  \"actor\": \"atlas\",\n  \"domain\": \"ops\",\n  \"plane\": \"action\",\n  \"target\": \"pg_dump production\",\n  \"summary\": \"Ran database backup\",\n  \"gate\": \"approval-123\",\n  \"ord\": 42,\n  \"chain\": {\"prev\": \"abc...\", \"hash\": \"def...\", \"algo\": \"sha256(prev\\\\nline_c14n)\"}\n}\n```\n\n## OpenClaw Integration\n\nAdd to `HEARTBEAT.md`:\n\n```markdown\n## Audit integrity check\n- Run: `./scripts/auditlog.py verify`\n  - If fails: alert with line number + hash mismatch\n  - If OK: silent\n```\n\n## Requirements\n\n- Python 3.9+ (zero external dependencies)\n- MIT License\n\n---\n\nBuilt with 🔐 by [Roosch](https://github.com/roosch269) and [Atlas](https://github.com/roosch269/agent-audit-trail)\n\nFile v2.0.0:README.md\n\n# Agent Audit Trail 🔐\n\n**Tamper-evident, hash-chained audit logging for AI agents. EU AI Act ready.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-skill-orange.svg)](https://github.com/openclaw/openclaw)\n\n---\n\n## Why This Exists\n\nAI agents act autonomously — writing files, executing commands, calling APIs, making decisions. **But how do you prove what happened?** How do you demonstrate that records weren't altered after the fact?\n\nFrom **2 August 2026**, the [EU AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689/oj) enters full applicability. If you deploy AI systems that affect EU citizens, you need:\n\n| Requirement | EU AI Act Article | This Tool |\n|-------------|------------------|-----------|\n| **Automatic event logging** | Article 12 (Record-Keeping) | ✅ Every action logged with timestamp, actor, domain |\n| **Tamper-evident records** | Article 12 (Integrity) | ✅ SHA-256 hash chaining — any modification breaks the chain |\n| **Human oversight capability** | Article 14 (Human Oversight) | ✅ Gate references link actions to human approvals |\n| **Transparency / auditability** | Article 50 (Transparency) | ✅ Human-readable NDJSON, one-command verification |\n| **Chronological ordering** | Article 12 (Traceability) | ✅ Monotonic ordering tokens |\n\n**This isn't just good practice anymore. In 163 days, it's the law.**\n\n---\n\n## What It Does\n\nA simple, zero-dependency audit log with cryptographic integrity:\n\n- **Append-only NDJSON** — Human-readable, grep-friendly, machine-parseable\n- **SHA-256 hash chaining** — Each entry cryptographically links to all previous entries\n- **Tamper detection** — Any modification breaks the chain from that point forward\n- **One-command verification** — Instantly validate the entire audit history\n- **Gate references** — Link autonomous actions to human approval events\n- **Domain partitioning** — Separate audit trails by security domain\n- **Zero dependencies** — Python 3.9+ stdlib only. No packages to audit.\n\n---\n\n## Quick Start\n\n```bash\n# Clone or copy the script\ncurl -O https://raw.githubusercontent.com/roosch269/agent-audit-trail/main/scripts/auditlog.py\nchmod +x auditlog.py\n\n# Log an action\n./auditlog.py append --kind \"file-write\" --summary \"Created config.yaml\"\n\n# Verify integrity\n./auditlog.py verify\n# Output: OK (1 entries verified)\n```\n\n---\n\n## Usage\n\n### Log an Action\n\n```bash\n./auditlog.py append \\\n  --kind \"exec\" \\\n  --summary \"Ran database backup\" \\\n  --target \"pg_dump production\" \\\n  --domain \"ops\" \\\n  --gate \"approval-123\" \\\n  --provenance '{\"channel\": \"slack\", \"user\": \"admin\"}' \\\n  --details '{\"duration_ms\": 4500}'\n```\n\n### Verify the Chain\n\n```bash\n./auditlog.py verify\n# OK (42 entries verified)\n```\n\nReturns exit code 0 if valid, 1 if tampered, with details about which line failed.\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `AUDIT_LOG_PATH` | `audit/agent-actions.ndjson` | Log file location |\n| `AUDIT_LOG_TZ` | `UTC` | Timezone for timestamps |\n| `AUDIT_LOG_ACTOR` | `agent` | Default actor name |\n\nOr use CLI flags: `--log`, `--tz`, `--actor`\n\n---\n\n## Log Format\n\nEach line is a self-contained JSON object:\n\n```json\n{\n  \"ts\": \"2026-02-24T07:15:00+00:00\",\n  \"kind\": \"exec\",\n  \"actor\": \"atlas\",\n  \"domain\": \"ops\",\n  \"plane\": \"action\",\n  \"target\": \"pg_dump production\",\n  \"summary\": \"Ran database backup\",\n  \"gate\": \"approval-123\",\n  \"provenance\": {\"channel\": \"slack\", \"user\": \"admin\"},\n  \"ord\": 42,\n  \"chain\": {\n    \"prev\": \"abc123...\",\n    \"hash\": \"def456...\",\n    \"algo\": \"sha256(prev\\\\nline_c14n)\"\n  }\n}\n```\n\n### Field Reference\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `ts` | Auto | ISO-8601 timestamp with timezone offset |\n| `kind` | Yes | Event type (`file-write`, `exec`, `api-call`, `credential-access`, `external-write`) |\n| `actor` | Auto | Who performed the action |\n| `domain` | No | Security domain for partitioning (`ops`, `personal`, `client`, etc.) |\n| `plane` | Auto | Processing plane (default: `action`) |\n| `target` | No | What was acted upon (file path, URL, command) |\n| `summary` | Yes | Human-readable description |\n| `gate` | No | Reference to human approval (for gated actions) |\n| `provenance` | No | Source attribution — channel, user, message ID |\n| `details` | No | Additional structured data |\n| `ord` | Auto | Monotonic ordering token |\n| `chain` | Auto | Hash chain: `prev` hash, current `hash`, algorithm |\n\n---\n\n## EU AI Act Compliance Guide\n\n### For Deployers (Article 12 — Record-Keeping)\n\nThe EU AI Act requires automatic logging of events for AI systems. This tool provides:\n\n1. **What was logged**: Every action includes `kind`, `summary`, `target` — answering *what happened*\n2. **When it happened**: ISO-8601 timestamps with timezone — answering *when*\n3. **Who authorised it**: `gate` field links to human approval — answering *who approved this*\n4. **Proof of integrity**: Hash chain means the record can't be altered without detection\n5. **Traceability**: Monotonic `ord` tokens provide chronological ordering\n\n### For High-Risk Systems (Articles 12 + 14)\n\nIf your AI system is classified as **high-risk** under the EU AI Act:\n\n```bash\n# Log with full provenance for high-risk actions\n./auditlog.py append \\\n  --kind \"decision\" \\\n  --summary \"Credit scoring model output: approved\" \\\n  --target \"application-12345\" \\\n  --domain \"high-risk\" \\\n  --gate \"human-review-req-456\" \\\n  --provenance '{\"model\": \"credit-v2\", \"confidence\": 0.87}' \\\n  --details '{\"input_hash\": \"sha256:abc...\", \"output\": \"approved\", \"reviewer\": \"jane@company.com\"}'\n```\n\n### Recommended Audit Kinds for Compliance\n\n| Kind | When to Use | EU AI Act Relevance |\n|------|------------|-------------------|\n| `decision` | AI makes/recommends a decision | Art. 14 — human oversight |\n| `file-write` | Agent creates or modifies files | Art. 12 — record-keeping |\n| `exec` | Agent runs a command | Art. 12 — traceability |\n| `api-call` | External API interaction | Art. 12 — record-keeping |\n| `credential-access` | Secrets or credentials accessed | Art. 12 — security logging |\n| `external-write` | Agent writes to external systems | Art. 12 + Art. 14 |\n| `human-override` | Human overrides AI decision | Art. 14 — oversight evidence |\n| `disclosure` | AI identity disclosed to user | Art. 50 — transparency |\n\n---\n\n## How It Works\n\n```\nEntry N-1                    Entry N\n┌─────────────────┐         ┌─────────────────┐\n│ ts, kind, ...   │         │ ts, kind, ...   │\n│ chain.hash: H1  │───┬────▶│ chain.prev: H1  │\n└─────────────────┘   │     │ chain.hash: H2  │\n                      │     └─────────────────┘\n                      │            │\n                      └────────────┴──▶ H2 = sha256(H1 + \"\\n\" + canonical(entry))\n```\n\nTampering with any entry changes its hash, which breaks the chain for all subsequent entries. Verification is O(n) — one pass through the log.\n\n---\n\n## Integration\n\n### OpenClaw (Heartbeat)\n\nAdd to your `HEARTBEAT.md` for automatic integrity checks:\n\n```markdown\n## Audit integrity check\n- Run: `./scripts/auditlog.py verify`\n  - If fails: alert with line number\n  - If OK: silent\n```\n\n### CI/CD Pipeline\n\n```yaml\n# .github/workflows/audit-verify.yml\n- name: Verify audit trail\n  run: python scripts/auditlog.py verify\n```\n\n### Python Integration\n\n```python\nfrom scripts.auditlog import append_entry, verify\n\n# Log from your agent code\nappend_entry(\"audit/agent-actions.ndjson\", {\n    \"kind\": \"api-call\",\n    \"summary\": \"Called OpenAI API\",\n    \"target\": \"gpt-4\",\n    \"domain\": \"inference\",\n})\n\n# Verify programmatically\nsuccess, message = verify(\"audit/agent-actions.ndjson\")\nassert success, f\"Audit chain broken: {message}\"\n```\n\n---\n\n## Security Model\n\n**What this provides:**\n- ✅ Evidence of what happened\n- ✅ Detection of post-hoc tampering\n- ✅ Chronological ordering guarantees\n- ✅ Domain-partitioned audit trails\n- ✅ Human approval linkage (gate references)\n\n**What this doesn't provide:**\n- ❌ Prevention of malicious logging (a compromised agent can lie)\n- ❌ Protection against log deletion (use offsite backups)\n- ❌ Root-level security (admins can rewrite everything)\n\nThis is *audit*, not *access control*. It makes tampering **detectable**, not impossible. For comprehensive agent governance, pair with access controls, human-in-the-loop gates, and offsite log replication.\n\n---\n\n## Comparison\n\n| Feature | Agent Audit Trail | Basic file logging | Database logging |\n|---------|------------------|--------------------|-----------------|\n| Tamper detection | ✅ Hash chain | ❌ | ❌ |\n| Zero dependencies | ✅ | ✅ | ❌ |\n| Human-readable | ✅ NDJSON | ✅ | ❌ |\n| Chronological proof | ✅ Monotonic ord | ❌ | Partial |\n| EU AI Act ready | ✅ | ❌ | Partial |\n| Setup time | 30 seconds | 30 seconds | Hours |\n| Gate references | ✅ | ❌ | Custom |\n\n---\n\n## Requirements\n\n- Python 3.9+ (for `zoneinfo`; falls back to UTC on older versions)\n- No external dependencies\n- Works on Linux, macOS, WSL\n\n---\n\n## Roadmap (v2.1+)\n\n- [ ] `export` command — generate compliance report from log\n- [ ] `stats` command — event counts, domain breakdown, time range queries\n- [ ] JSON Schema for log validation\n- [ ] Optional remote log shipping (append-only S3/GCS)\n- [ ] Compliance report template (EU AI Act Article 12)\n\n---\n\n## Contributing\n\nIssues and PRs welcome! Please:\n- Keep it simple (no new dependencies)\n- Maintain backward compatibility with existing logs\n- Add tests for new features\n\n---\n\n## License\n\nMIT — Use freely, contribute back if you improve it.\n\n---\n\n## Links\n\n- **EU AI Act full text**: [eur-lex.europa.eu](https://eur-lex.europa.eu/eli/reg/2024/1689/oj)\n- **OpenClaw**: [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)\n- **ClawHub**: [clawhub.com](https://clawhub.com)\n\n---\n\nBuilt with 🔐 by [Roosch](https://github.com/roosch269) and [Atlas](https://github.com/roosch269/agent-audit-trail)\n\nFile v2.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn71asv5ce1x1ytv32k5av44gx817hff\",\n  \"slug\": \"agent-audit-trail\",\n  \"version\": \"2.0.0\",\n  \"publishedAt\": 1771918041830\n}\n\nArchive v1.0.0: 5 files, 9065 bytes\n\nFiles: examples/basic-usage.sh (1549b), README.md (4296b), scripts/auditlog.py (9516b), SKILL.md (4687b), _meta.json (136b)\n\nFile v1.0.0:SKILL.md\n\n# Agent Audit Trail Skill\n\nTamper-evident, hash-chained audit logging for AI agents.\n\n## Why\n\nAgents act on your behalf. You need to know *what* they did, *when*, and be able to *prove* nothing was altered after the fact.\n\nThis skill provides:\n- **Append-only NDJSON logs** — human-readable, grep-friendly\n- **Hash chaining** — each entry includes SHA-256 of previous + current, making tampering detectable\n- **Monotonic ordering** — sequential `ord` tokens for gate-relevant events\n- **Verification** — one command to validate the entire chain\n\n## Quick Start\n\n### 1. Add to your agent's workspace\n\nCopy `scripts/auditlog.py` to your workspace's `scripts/` directory.\n\n```bash\ncp scripts/auditlog.py /path/to/your/workspace/scripts/\nchmod +x /path/to/your/workspace/scripts/auditlog.py\n```\n\n### 2. Log an action\n\n```bash\n./scripts/auditlog.py append \\\n  --kind \"file-write\" \\\n  --summary \"Created config.yaml\" \\\n  --target \"config.yaml\" \\\n  --domain \"personal\"\n```\n\n### 3. Verify integrity\n\n```bash\n./scripts/auditlog.py verify\n# Output: OK (or error with line number if tampered)\n```\n\n## Usage\n\n### Appending entries\n\n```bash\n./scripts/auditlog.py append \\\n  --kind <event-type> \\\n  --summary <description> \\\n  [--domain <domain>] \\\n  [--target <identifier>] \\\n  [--gate <gate-reference>] \\\n  [--provenance '{\"source\": \"...\", \"channel\": \"...\"}'] \\\n  [--details '{\"key\": \"value\"}']\n```\n\n**Required:**\n- `--kind`: Event type (e.g., `file-write`, `exec`, `api-call`, `credential-access`)\n- `--summary`: Human-readable description\n\n**Optional:**\n- `--domain`: Logical domain (default: `unknown`)\n- `--target`: What was acted upon (file path, URL, command)\n- `--gate`: Reference to approval gate (for gated actions)\n- `--provenance`: JSON object with source attribution\n- `--details`: JSON object with additional structured data\n\n### Verifying the chain\n\n```bash\n./scripts/auditlog.py verify [--log path/to/audit.ndjson]\n```\n\nReturns exit code 0 and prints `OK` if valid, or prints the failing line number and hash mismatch details.\n\n## Log Format\n\nEach line is a JSON object:\n\n```json\n{\n  \"ts\": \"2026-02-05T07:15:00+00:00\",\n  \"kind\": \"file-write\",\n  \"actor\": \"atlas\",\n  \"domain\": \"personal\",\n  \"plane\": \"action\",\n  \"target\": \"config.yaml\",\n  \"summary\": \"Created config.yaml\",\n  \"ord\": 42,\n  \"chain\": {\n    \"prev\": \"abc123...\",\n    \"hash\": \"def456...\",\n    \"algo\": \"sha256(prev\\nline_c14n)\"\n  }\n}\n```\n\n### Fields\n\n| Field | Description |\n|-------|-------------|\n| `ts` | ISO-8601 timestamp with timezone offset |\n| `kind` | Event type |\n| `actor` | Who performed the action (default: script name or agent) |\n| `domain` | Logical domain for partitioning |\n| `plane` | Processing plane (usually `action`) |\n| `target` | What was acted upon |\n| `summary` | Human description |\n| `gate` | Gate reference if action required approval |\n| `provenance` | Source attribution object |\n| `ord` | Monotonic ordering token |\n| `chain` | Hash chain data |\n\n## Integration with OpenClaw\n\n### Heartbeat verification\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## Audit integrity check\n- Run: `./scripts/auditlog.py verify`\n  - If fails: alert with line number + hash mismatch\n  - If OK: silent\n```\n\n### Gated actions\n\nFor actions requiring human approval, log with a gate reference:\n\n```bash\n./scripts/auditlog.py append \\\n  --kind \"external-write\" \\\n  --summary \"Posted to Twitter\" \\\n  --gate \"approval-2026-02-05-001\" \\\n  --target \"https://x.com/status/123\" \\\n  --provenance '{\"channel\": \"telegram\", \"message_id\": \"456\"}'\n```\n\n## Security Model\n\n1. **Append-only**: The script only appends; it never modifies existing entries\n2. **Hash chaining**: Each entry's hash depends on all previous entries\n3. **Tamper detection**: Any modification breaks the chain from that point forward\n4. **File locking**: Uses `fcntl.LOCK_EX` for safe concurrent access\n\n### What this doesn't protect against\n\n- Root/admin access (they can rewrite everything)\n- Compromised agent (it could lie in its logs)\n- Log deletion (use offsite backup for that)\n\nThis is *evidence*, not *prevention*. It makes tampering *detectable*, not impossible.\n\n## Configuration\n\nDefault log path: `audit/atlas-actions.ndjson`\n\nOverride with `--log`:\n\n```bash\n./scripts/auditlog.py --log path/to/my-audit.ndjson append --kind test --summary \"Test entry\"\n```\n\n## Requirements\n\n- Python 3.9+ (for `zoneinfo`)\n- No external dependencies\n\n## Philosophy\n\n> \"Trust, but verify.\" — and make verification trivial.\n\nAgents should be accountable. This skill makes accountability auditable.\n\n## License\n\nMIT — use freely, contribute back if you improve it.\n\n## Contributing\n\nIssues and PRs welcome at: https://github.com/roosch/agent-audit-trail\n\nFile v1.0.0:README.md\n\n# Agent Audit Trail 🔐\n\n**Tamper-evident, hash-chained audit logging for AI agents.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-skill-orange.svg)](https://github.com/openclaw/openclaw)\n\n---\n\n## The Problem\n\nAI agents act autonomously. They write files, execute commands, call APIs, and make decisions. But how do you know what actually happened? How do you prove the record wasn't altered?\n\n## The Solution\n\nA simple, zero-dependency audit log with cryptographic integrity:\n\n- **Append-only NDJSON** — Human-readable, grep-friendly\n- **SHA-256 hash chaining** — Each entry links to all previous entries\n- **Tamper detection** — Any modification breaks the chain\n- **One-command verification** — Instantly validate the entire history\n\n## Quick Start\n\n```bash\n# Clone or copy the script\ncurl -O https://raw.githubusercontent.com/roosch/agent-audit-trail/main/scripts/auditlog.py\nchmod +x auditlog.py\n\n# Log an action\n./auditlog.py append --kind \"file-write\" --summary \"Created config.yaml\"\n\n# Verify integrity\n./auditlog.py verify\n# Output: OK (1 entries verified)\n```\n\n## Example Output\n\n```json\n{\"actor\":\"agent\",\"domain\":\"personal\",\"kind\":\"file-write\",\"ord\":1,\"plane\":\"action\",\"summary\":\"Created config.yaml\",\"target\":\"config.yaml\",\"ts\":\"2026-02-05T07:15:00+00:00\",\"chain\":{\"algo\":\"sha256(prev\\\\nline_c14n)\",\"hash\":\"a1b2c3...\",\"prev\":\"000000...\"}}\n```\n\n## Usage\n\n### Append an entry\n\n```bash\n./auditlog.py append \\\n  --kind \"exec\" \\\n  --summary \"Ran database backup\" \\\n  --target \"pg_dump production\" \\\n  --domain \"ops\" \\\n  --gate \"approval-123\" \\\n  --provenance '{\"channel\": \"slack\", \"user\": \"admin\"}' \\\n  --details '{\"duration_ms\": 4500}'\n```\n\n### Verify the chain\n\n```bash\n./auditlog.py verify\n```\n\nReturns exit code 0 if valid, 1 if tampered, with details about which line failed.\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `AUDIT_LOG_PATH` | `audit/agent-actions.ndjson` | Log file location |\n| `AUDIT_LOG_TZ` | `UTC` | Timezone for timestamps |\n| `AUDIT_LOG_ACTOR` | `agent` | Default actor name |\n\nOr use CLI flags: `--log`, `--tz`, `--actor`\n\n## OpenClaw Integration\n\nAdd to your `HEARTBEAT.md` for automatic integrity checks:\n\n```markdown\n## Audit integrity check\n- Run: `./scripts/auditlog.py verify`\n  - If fails: alert with line number\n  - If OK: silent\n```\n\nSee [SKILL.md](SKILL.md) for full OpenClaw skill documentation.\n\n## How It Works\n\n```\nEntry N-1                    Entry N\n┌─────────────────┐         ┌─────────────────┐\n│ ts, kind, ...   │         │ ts, kind, ...   │\n│ chain.hash: H1  │───┬────▶│ chain.prev: H1  │\n└─────────────────┘   │     │ chain.hash: H2  │\n                      │     └─────────────────┘\n                      │            │\n                      └────────────┴──▶ H2 = sha256(H1 + \"\\n\" + canonical(entry))\n```\n\nTampering with any entry changes its hash, which breaks the chain for all subsequent entries.\n\n## Security Model\n\n**What this provides:**\n- Evidence of what happened\n- Detection of post-hoc tampering\n- Chronological ordering guarantees\n\n**What this doesn't provide:**\n- Prevention of malicious logging (a compromised agent can lie)\n- Protection against log deletion (use offsite backups)\n- Root-level security (admins can rewrite everything)\n\nThis is *audit*, not *access control*. It makes tampering detectable, not impossible.\n\n## Requirements\n\n- Python 3.9+ (for `zoneinfo`; falls back to UTC on older versions)\n- No external dependencies\n\n## Contributing\n\nIssues and PRs welcome! Please:\n- Keep it simple (no new dependencies)\n- Maintain backward compatibility with existing logs\n- Add tests for new features\n\n## License\n\nMIT — Use freely, contribute back if you improve it.\n\n---\n\nBuilt with 🔐 by [Roosch](https://github.com/roosch) and [Atlas](https://github.com/roosch/agent-audit-trail)\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn71asv5ce1x1ytv32k5av44gx817hff\",\n  \"slug\": \"agent-audit-trail\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1771154428994\n}","readmeExcerpt":"Skill: Agent Audit Trail Owner: roosch269 Summary: Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... Tags: accountability:2.1.0, article-12:2.1.0, audit:2.1.0, compliance:2.1.0, eu-ai-act:2.1.0, hash-chain:1.0.0, latest:2.1.0, security:2.1.0, trust:1.0.0 Version history: v2.1.0 | 2026-04-02T17:55:47.302Z | us","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"audit/atlas-actions.ndjson"},{"language":"json","snippet":"{\n  \"ts\":         \"2026-04-02T18:00:00.000+01:00\",\n  \"kind\":       \"tool-call\",\n  \"actor\":      \"atlas\",\n  \"domain\":     \"agirails\",\n  \"plane\":      \"action\",\n  \"gate\":       \"external-write\",\n  \"ord\":        42,\n  \"provenance\": \"session:agent:main:discord:channel:1472016988741177520\",\n  \"target\":     \"audit/atlas-actions.ndjson\",\n  \"summary\":    \"Appended audit log entry\",\n  \"prev_hash\":  \"sha256:abc123...\",\n  \"hash\":       \"sha256:def456...\"\n}"},{"language":"bash","snippet":"mkdir -p audit\ntouch audit/atlas-actions.ndjson"},{"language":"markdown","snippet":"## Audit Log\n- Path: `audit/atlas-actions.ndjson`\n- Format: append-only NDJSON, hash-chained (sha256), monotonic `ord`\n- Timestamps: Europe/London ISO-8601 with offset\n- Fields: ts, kind, actor, domain, plane, gate, ord, provenance, target, summary"},{"language":"text","snippet":"4. Append-only, hash-chained audit log with monotonic ordering\n10. Behavior surface changes logged as state transitions"},{"language":"text","snippet":"- external-write: provenance + intent + approval + tool-log + ordering\n- credential-access: domain scope + justification + audit + human approval\n- install-extend: integrity proof + scope + rollback ref + human approval"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: Agent Audit Trail\nversion: 2.1.0\ndescription: >\n  Append-only, hash-chained audit log for AI agents. Records agent actions,\n  tool calls, decisions, and external writes with provenance, timestamps, and\n  sha256 chain integrity. Designed for compliance with EU AI Act Article 12\n  automatic event recording requirements for high-risk AI systems.\nauthor:\n  name: Justin Roosch\n  url: https://github.com/roosch269\nlicense: MIT-0\ntags:\n  - audit\n  - compliance\n  - logging\n  - eu-ai-act\n  - article-12\n  - governance\n  - provenance\n  - security\nkeywords:\n  - audit trail\n  - agent logging\n  - hash chain\n  - event log\n  - compliance logging\n---\n\n# Agent Audit Trail\n\nAn 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.\n\n## Overview\n\nThis skill provides:\n- **Append-only NDJSON log** at `audit/atlas-actions.ndjson`\n- **Hash-chained entries** — each entry includes the sha256 of the previous entry\n- **Monotonic ordering** — `ord` field ensures strict sequence\n- **Structured fields** — consistent schema across all event types\n- **EU AI Act Article 12** compliance implementation\n\n## Log Location\n\n```\naudit/atlas-actions.ndjson\n```\n\nThe file is append-only. Never truncate, overwrite, or reorder entries.\n\n## Log Entry Schema\n\nEach line is a valid JSON object:\n\n```json\n{\n  \"ts\":         \"2026-04-02T18:00:00.000+01:00\",\n  \"kind\":       \"tool-call\",\n  \"actor\":      \"atlas\",\n  \"domain\":     \"agirails\",\n  \"plane\":      \"action\",\n  \"gate\":       \"external-write\",\n  \"ord\":        42,\n  \"provenance\": \"session:agent:main:discord:channel:1472016988741177520\",\n  \"target\":     \"audit/atlas-actions.ndjson\",\n  \"summary\":    \"Appended audit log entry\",\n  \"prev_hash\":  \"sha256:abc123...\",\n  \"hash\":       \"sha256:def456...\"\n}\n```\n\n### Field Reference\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `ts` | ISO-8601 | Timestamp with timezone offset (Europe/London) |\n| `kind` | string | Event type (see below) |\n| `actor` | string | Agent or component that triggered the event |\n| `domain` | string | Domain partition (`agirails`, `client-lab`, `personal`) |\n| `plane` | string | Four-plane label (`ingress`, `interpretation`, `decision`, `action`) |\n| `gate` | string | Truth gate applied (see SOUL.md) |\n| `ord` | integer | Monotonically increasing sequence number |\n| `provenance` | string | Source session or external identity |\n| `target` | string | File, URL, or resource affected |\n| `summary` | string | Human-readable description of the event |\n| `prev_hash` | string | sha256 of the previous log entry (hex, prefixed `sha256:`) |\n| `hash` | string | sha256 of this entry excluding the `hash` field itself |\n\n### Event Kinds\n\n| Kind | Plane | Description |\n|------|-------|-------------|\n| `tool-call` | action | Any tool invocation |\n| `external-write` | action | Writ"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn71asv5ce1x1ytv32k5av44gx817hff\",\n  \"slug\": \"agent-audit-trail\",\n  \"version\": \"2.1.0\",\n  \"publishedAt\": 1775152547302\n}"},{"path":"skill-card.md","content":"## Description:\n\nAppend-only, hash-chained audit log for AI agents that records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256 chain integrity for EU AI Act Article 12 logging support.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[roosch269](https://clawhub.ai/user/roosch269)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators of AI agents use this skill to add an append-only NDJSON audit log that records actions, tool calls, decisions, external writes, and provenance for compliance review and tamper-evidence.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill creates durable local records of agent activity that may include sensitive session, credential, wallet, transaction, or other operational metadata.\n\nMitigation: Restrict audit-log file permissions, define a retention policy, and redact sensitive identifiers and metadata before using the log for compliance or incident evidence.\n\nRisk: The security evidence notes reliability flaws in the sample integrity logic, including the need to fix hash-chain genesis behavior and writer coordination.\n\nMitigation: Fix the hash-chain genesis mismatch and use locking or a single-writer design before relying on the log for compliance or incident evidence.\n\nRisk: Companion skills may extend agent behavior or integrations beyond this audit trail.\n\nMitigation: Verify companion skills before installing or wiring them into an agent workflow.\n\n## Reference(s):\n\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with JSON, Python, and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local NDJSON audit-log setup and verification guidance; persistent logs may contain sensitive activity metadata.]\n\n## Skill Version(s):\n\n2.1.0 (source: frontmatter, _meta.json, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... Skill: Agent Audit Trail Owner: roosch269 Summary: Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256... Tags: accountability:2.1.0, article-12:2.1.0, audit:2.1.0, compliance:2.1.0, eu-ai-act:2.1.0, hash-chain:1.0.0, latest:2.1.0, security:2.1.0, trust:1.0.0 Version history: v2.1.0 | 2026-04-02T17:55:47.302Z | us","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1055,"uniquenessScore":52,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T11:26:48.273Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:24:56.061Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}