Agent 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 INLINECODE0
- 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
CODEBLOCK0
The file is append-only. Never truncate, overwrite, or reorder entries.
Log Entry Schema
Each line is a valid JSON object:
CODEBLOCK1
Field Reference
| Field | Type | Description |
|---|
| INLINECODE2 | ISO-8601 | Timestamp with timezone offset (Europe/London) |
| INLINECODE3 |
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 |
|---|
| INLINECODE23 | action | Any tool invocation |
| INLINECODE24 |
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
CODEBLOCK2
2. Wire into TOOLS.md
Add to your workspace TOOLS.md:
CODEBLOCK3
3. Wire into SOUL.md
Add to your workspace SOUL.md invariants:
CODEBLOCK4
And to Truth Gates:
CODEBLOCK5
4. Helper script (optional)
CODEBLOCK6
Verification
To check chain integrity:
CODEBLOCK7
Usage Patterns
Log every external write
CODEBLOCK8
Log credential access
CODEBLOCK9
Log payment events
CODEBLOCK10
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 | INLINECODE36 — 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:
CODEBLOCK11
Or if already available in your workspace:
CODEBLOCK12
Workflow:
- 1. Run
agent-self-assessment → identify gaps + risk tier - Install
agent-audit-trail → implement logging for ongoing compliance - 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:
CODEBLOCK13
Or if already available in your workspace:
CODEBLOCK14
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 INLINECODE54
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: INLINECODE58
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: INLINECODE60
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).代理审计追踪
AI代理的仅追加、哈希链式审计日志。每个重要操作、决策、工具调用和外部写入都通过SHA256链记录并链接条目——使篡改可检测，并提供权威的合规记录。
概述
本技能提供：
- - 仅追加NDJSON日志，位于audit/atlas-actions.ndjson
- 哈希链式条目——每个条目包含前一条目的SHA256哈希
- 单调排序——ord字段确保严格顺序
- 结构化字段——所有事件类型的一致模式
- 欧盟AI法案第12条合规实现
日志位置
audit/atlas-actions.ndjson
该文件仅可追加。切勿截断、覆盖或重新排序条目。
日志条目模式
每行是一个有效的JSON对象：
json
{
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: 已追加审计日志条目,
prev_hash: sha256:abc123...,
hash: sha256:def456...
}
字段参考
| 字段 | 类型 | 描述 |
|---|
| ts | ISO-8601 | 带时区偏移的时间戳（欧洲/伦敦） |
| kind |
字符串 | 事件类型（见下文） |
| actor | 字符串 | 触发事件的代理或组件 |
| domain | 字符串 | 域分区（agirails、client-lab、personal） |
| plane | 字符串 | 四平面标签（ingress、interpretation、decision、action） |
| gate | 字符串 | 应用的真值门（参见SOUL.md） |
| ord | 整数 | 单调递增的序列号 |
| provenance | 字符串 | 源会话或外部身份 |
| target | 字符串 | 受影响的文件、URL或资源 |
| summary | 字符串 | 事件的人类可读描述 |
| prev_hash | 字符串 | 前一条日志条目的SHA256哈希（十六进制，前缀sha256:） |
| hash | 字符串 | 本条目的SHA256哈希（排除hash字段本身） |
事件类型
| 类型 | 平面 | 描述 |
|---|
| tool-call | action | 任何工具调用 |
| external-write |
action | 写入外部系统（文件、API、数据库） |
| credential-access | action | 访问密钥或凭据 |
| install-extend | action | 包安装或技能激活 |
| decision | decision | 带推理的代理决策 |
| override | decision | 应用的安全覆盖 |
| ingress | ingress | 接收的外部输入 |
| session-start | ingress | 代理会话初始化 |
| session-end | ingress | 代理会话终止 |
| state-transition | decision | 行为表面变更 |
| payment | action | ACTP/x402支付事件（金额、对手方、交易哈希） |
设置
1. 创建审计目录
bash
mkdir -p audit
touch audit/atlas-actions.ndjson
2. 接入TOOLS.md
添加到工作区TOOLS.md：
markdown
审计日志
- - 路径：audit/atlas-actions.ndjson
- 格式：仅追加NDJSON，哈希链式（SHA256），单调ord
- 时间戳：欧洲/伦敦 ISO-8601 带偏移
- 字段：ts、kind、actor、domain、plane、gate、ord、provenance、target、summary
3. 接入SOUL.md
添加到工作区SOUL.md不变量：
- 4. 仅追加、哈希链式审计日志，带单调排序
- 行为表面变更记录为状态转换
以及真值门：
- - external-write：来源 + 意图 + 批准 + 工具日志 + 排序
- credential-access：域范围 + 理由 + 审计 + 人工批准
- install-extend：完整性证明 + 范围 + 回滚引用 + 人工批准
4. 辅助脚本（可选）
python
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)) # 欧洲/伦敦夏令时；调整为格林威治标准时间
def last_hash():
lines = LOG.read_text().strip().splitlines() if LOG.exists() else []
if not lines:
return sha256:0 * 1 # 创世
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,
prevhash: lasthash(),
}
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:
# 示例：python3 scripts/audit_append.py
append(session-start, atlas, personal, ingress, none,
manual, audit/atlas-actions.ndjson, 会话已初始化)
验证
检查链完整性：
bash
python3 - <
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链在条目 {i} 处断裂（ord={entry.get(ord)}）)
break
if entry.get(prev_hash) != prev:
print(f条目 {i} 处PREV_HASH不匹配)
break
prev = stored_hash
else:
print(f链正常 — 已验证 {len(lines)} 个条目)
EOF
使用模式
记录每次外部写入
python
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=为10 USDC创建ACTP托管0xabc...
)
记录凭据访问
python
append(
kind=credential-access,
actor=atlas,
domain=agirails,
plane=action,
gate=credential-access,
provenance=session:agent:main,
target=.env:ACTPKEYPASSWORD,
summary=访问ACTP钱包密钥用于测试网支付
)
记录支付事件
python
append(
kind=payment,
actor=atlas,
domain=agirails,
plane=action,
gate=external-write,
provenance=session:agent:main,
target=base-sepolia:0xabc...def
