arcaeon-audit

Tamper-evident, audit-ready logs for AI agents. Observability shows you what your agent did. This lets you prove it wasn't altered — the evidence your ISO 42001 / SOC 2 auditor (and, by 2027, the EU AI Act) asks for.

pip install arcaeon-audit

Why this exists

If you ship an AI agent into anything regulated or enterprise-sold, you're already being asked to keep records of what it did and produce them on demand — by your SOC 2 auditor, by ISO/IEC 42001 (Annex A.6.2.8: keep AI event logs across the lifecycle), and by the security/AI-governance questionnaires your enterprise customers send today. The EU AI Act, Article 12 adds a hard tamper-evident-logging mandate for high-risk systems from 2 December 2027 (Digital Omnibus, Reg. (EU) 2026/1744; penalties to €35M or 7% of revenue).

Almost all of that forces you to keep records. Almost none of it is satisfied by a plain log file — anyone with write access can edit, delete, or reorder a past record and nothing shows. What auditors and regulators want is an append-only, integrity-protected record you can hand over and have independently verified. That integrity layer — the provable part — is exactly what this gives you.

A normal log file doesn't meet the bar: anyone with write access can edit, delete, or reorder a past record and nothing shows. The regulators' expectation is an append-only, integrity-protected record — in practice, a hash chain.

arcaeon-audit is the small, boring, correct layer that gives you exactly that, in two lines and a folder. It wraps arcaeon-ledger (a hash-chained append-only log, zero heavy deps) with the event vocabulary and the regulator-ready export that Article 12 asks for.

Use

from arcaeon_audit import AuditLog

log = AuditLog("agent-audit.jsonl", system_id="triage-agent-v3", provider="Acme AI")

log.record(event="system_start", agent="triage-agent-v3")
log.record(event="input",  agent="triage-agent-v3", inputs={"patient_msg": "chest pain"})
log.record(event="decision", agent="triage-agent-v3", decision="escalate",
           outputs={"routed_to": "ER", "priority": 1}, capability_version="v2")

log.verify().ok            # True — any edit to history would make this False
log.export_bundle("audit-export/")   # regulator-ready folder

export_bundle() writes a self-verifying folder:

The bundle is self-verifying: records.jsonl is hash-chained, so anyone can re-run arcaeon-ledger's verify_file() and reproduce integrity.json. Tamper evidence does not depend on trusting this tool or its author — that's the point.

CLI

arcaeon-audit verify  agent-audit.jsonl
arcaeon-audit export  agent-audit.jsonl audit-export/ --system-id triage-v3 --provider "Acme AI"

What this is and isn't

Is: an engineering control that produces automatic, tamper-evident, exportable records — the integrity + export primitive Article 12 leans on.

Isn't: legal advice, and not compliance-in-a-box on its own. Article 12 compliance also depends on what you choose to log and your broader obligations under the Act. This tool gives you the hard part (provable integrity + a clean export); the coverage is yours to define.

How it works

Every record is hash-chained: chain = sha256(prev_chain + canonical(row)). Edit, delete, or reorder any record and every later link breaks; verify() names the exact row. Records also carry an authority block (principal + capability version) so "was this edited?" sharpens to "was this edited and was the writer authorized?"

MIT licensed. Built by Arcaeon — the evidence layer for AI.