← Back to Skills Marketplace
Audit Trail
by
Adnane Arharbi
· GitHub ↗
· v1.0.0
· MIT-0
100
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install audit-trail
Description
Governance — immutable, timestamped, hash-chained audit log of all agent actions. Forensic-ready for compliance, investigation, and accountability.
README (SKILL.md)
Audit Trail — Immutable Action Log
Purpose
Provide a tamper-evident, complete record of every agent action for forensic investigation, compliance auditing, and accountability.
Integration
Always-on hook on ALL agent actions:
- Tool use (exec, file read/write, network)
- Skill invocations
- Channel messages (in/out)
- Memory reads/writes
- Configuration changes
- Error events
Log Format (JSONL, append-only)
{"id":"ACT-20260331-000001","ts":"2026-03-31T14:30:00.123Z","agent":"openclaw-main","session":"sess_abc123","type":"tool_use","tool":"exec","args":{"cmd":"npm test"},"skill":"contract-tester","channel":"telegram","user_hash":"sha256:a1b2c3...","outcome":"success","duration_ms":4200,"prev_hash":"sha256:000000","hash":"sha256:d4e5f6..."}
Fields
| Field | Type | Description |
|---|---|---|
id |
string | Unique sequential ID |
ts |
ISO 8601 | Microsecond timestamp |
agent |
string | Agent identifier |
session |
string | Session ID |
type |
enum | tool_use, skill_invoke, channel_in, channel_out, memory_write, config_change, error |
tool |
string | Tool name (if applicable) |
args |
object | Sanitized arguments (secrets redacted) |
skill |
string | Invoking skill |
channel |
string | Source channel |
user_hash |
string | SHA-256 of user identifier (never raw) |
outcome |
enum | success, failure, timeout, blocked |
duration_ms |
number | Execution time |
prev_hash |
string | SHA-256 of previous log entry (chain) |
hash |
string | SHA-256 of this entry (including prev_hash) |
Storage
.security/audit-trail/
├── 2026-03-31.jsonl (today, active)
├── 2026-03-30.jsonl (yesterday)
├── 2026-03-29.jsonl.gz (compressed, >7 days)
└── integrity-check.log (chain verification results)
Integrity Verification
- Each entry's
hash= SHA-256(id + ts + type + tool + outcome + prev_hash) - Chain validation:
entry[n].prev_hash == entry[n-1].hash - Run verification:
jq -r '.hash' | sha256sum --check - Tampering detection: broken chain → CRITICAL alert
Retention Policy
| Age | Storage | Access |
|---|---|---|
| 0-7 days | Raw JSONL | Direct read |
| 7-90 days | Compressed JSONL.gz | Decompress on query |
| 90-365 days | Archive (if configured) | Restore on request |
| >365 days | Purge (manual only, human approval) | — |
Query Examples
# All actions by a specific skill
jq 'select(.skill=="contract-tester")' .security/audit-trail/2026-03-31.jsonl
# All failures
jq 'select(.outcome=="failure")' .security/audit-trail/*.jsonl
# Actions in a time window
jq 'select(.ts >= "2026-03-31T14:00" and .ts \x3C "2026-03-31T15:00")' .security/audit-trail/2026-03-31.jsonl
# Channel activity summary
jq -s 'group_by(.channel) | map({channel: .[0].channel, count: length})' .security/audit-trail/2026-03-31.jsonl
Guardrails
- Log file is APPEND-ONLY — agent cannot delete or modify entries
- Secrets in arguments are redacted BEFORE logging (using agent-firewall patterns)
- User identifiers are hashed, never stored in plaintext
- Log integrity verified on every read
- Manual purge requires human approval + logged as audit action itself
Usage Guidance
This skill largely does what it says (hash-chained JSONL logs, chain verification, queries, reports) and does not exfiltrate data or call external services, but there are practical and correctness issues you should address before trusting it for compliance:
- Do not assume immutability: the code writes files to the agent's working directory but does not set OS-level append-only flags or permissions to prevent deletion/modification. Protect the log directory with appropriate filesystem ACLs or an external immutable storage backend.
- Review and fix implementation bugs: sanitizeEntry can produce invalid JSON for truncated inputs, user hashing truncates the SHA-256 output (collision risk), and parts of the code appear truncated/unfinished. These flaws could break redaction or integrity checks.
- Test redaction and hashing in a safe environment with realistic inputs to confirm secrets are consistently removed and user identifiers are anonymized as required by policy.
- Consider audit log access controls and encryption at rest. The skill writes plain files by default; ensure the logs are only readable by authorized processes and consider encrypting archives.
- Prefer explicit operational controls: human-approval purge flows, tamper-evidence stored in an external immutable store, and signed log entries if you need a forensic-grade chain.
Given these mismatches between claims and implementation, review and fix the code (or obtain a vetted implementation) before relying on this skill for compliance or forensic purposes.
Capability Assessment
Purpose & Capability
Name/description align with the code: it writes JSONL logs, chains hashes, verifies chains, and can query/generate reports. However, the SKILL.md claims 'append-only' and 'agent cannot delete or modify entries' — the code simply writes files to a directory under the agent's cwd and does not enforce OS-level immutability, append-only filesystem flags, or access controls. Storing logs in the working directory ('.security/audit-trail') may capture arbitrary sensitive context depending on targetDir.
Instruction Scope
SKILL.md describes 'always-on hook on ALL agent actions' and 'verify on every read' and promises secrets will be redacted before logging. The implementation does sanitize args using regexes, but the code has correctness issues: sanitizeEntry JSON-parses a possibly-truncated string (which will break for very large entries), user hashing truncates the SHA-256 digest to 16 hex chars (increasing collision risk), and some code appears truncated/unfinished (matchesQuery is cut off). Also, the doc's claim that the agent cannot delete/modify entries is not enforced by the implementation.
Install Mechanism
No install spec or external downloads; the skill is provided as local JS code and SKILL.md. No third-party packages are fetched at install time. This is low install risk.
Credentials
The skill requests no environment variables or external credentials and does not contact external endpoints. It includes patterns to redact many common secret formats (AWS keys, GH tokens, bearer tokens). That is reasonable for an auditing tool, but redaction is implemented by regex replacements in-memory which can be brittle; the truncated user-hash and potential redaction/parsing bugs reduce privacy guarantees.
Persistence & Privilege
The skill persists logs and writes integrity and report files to disk, which is expected for an audit tool. It does not declare 'always: true' and does not request elevated platform privileges. Still, persistent logs can contain sensitive data and require careful filesystem permissioning and operational controls (retention/purge workflows, manual approval hooks) that the code/documentation do not technically enforce.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install audit-trail - After installation, invoke the skill by name or use
/audit-trail - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: Immutable, forensic-ready audit log for agent actions.
- Logs all agent activities (tools, skills, memory, messages, config, errors) in append-only, hash-chained JSONL.
- Timestamps, user hashes, and redacted arguments ensure compliance and privacy.
- Integrity verification with chain validation and alerting on tampering.
- Automatic log retention and compression policy by age; manual purge requires approval.
- Query examples provided for flexible investigation and auditing.
Metadata
Frequently Asked Questions
What is Audit Trail?
Governance — immutable, timestamped, hash-chained audit log of all agent actions. Forensic-ready for compliance, investigation, and accountability. It is an AI Agent Skill for Claude Code / OpenClaw, with 100 downloads so far.
How do I install Audit Trail?
Run "/install audit-trail" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Audit Trail free?
Yes, Audit Trail is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Audit Trail support?
Audit Trail is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Audit Trail?
It is built and maintained by Adnane Arharbi (@arhadnane); the current version is v1.0.0.
More Skills