aasm audit
Query audit log entries and export tamper-evident compliance reports.
Synopsis
aasm audit <SUBCOMMAND> [OPTIONS]
| Subcommand | Purpose |
|---|---|
list | Query audit log entries with filters. |
export | Export audit data fetched from the gateway as CSV/JSON/JSONL. |
verify-chain | Verify the SHA-256 hash chain of a local JSONL audit file. |
compliance-export | Full-fidelity compliance export of a local JSONL audit file. |
All subcommands accept the global options.
Time filters.
--sinceaccepts a duration shorthand (30m,2h,1d) or an ISO 8601 timestamp;--untilaccepts an ISO 8601 timestamp.
aasm audit list
Query audit log entries from the gateway (GET /api/v1/logs) with optional
filters, rendered as a table (or --output json|yaml). The result column is
color-coded: allow=green, deny=red, pending=yellow.
| Flag | Type | Default | Description |
|---|---|---|---|
--agent <AGENT> | string | — | Filter by agent identifier. |
--action <ACTION> | string | — | Filter by action type (e.g. ToolCallIntercepted, PolicyViolation). |
--result <RESULT> | allow | deny | pending | — | Filter by policy decision result. |
--since <SINCE> | string | — | Show events after this duration or ISO 8601 timestamp. |
--until <UNTIL> | string | — | Show events before this ISO 8601 timestamp. |
--limit <LIMIT> | integer | 50 | Maximum number of entries to return. |
--dry-run-only | flag | off | Show only observe-mode shadow events (dry_run: true). When off (default), shadow events are hidden so you see live enforcement decisions only. |
aasm audit list --result deny --since 2h --limit 20
TIMESTAMP AGENT ACTION TOOL RESULT POLICY
2026-06-09T14:01:00Z a1b2c3… PolicyViolation file_write deny block-system-paths
aasm audit export
Export audit entries fetched from the gateway to CSV/JSON/JSONL, with optional
compliance metadata headers. Writes to stdout unless --output-file is given.
| Flag | Type | Default | Description |
|---|---|---|---|
--format <FORMAT> | csv | json | jsonl | required | Export file format. JSONL is preferred for SIEM ingestion. |
--compliance <COMPLIANCE> | eu-ai-act | soc2 | — | Prepend a compliance metadata header. |
--output-file <OUTPUT_FILE> | string | (stdout) | Write output to a file. (Named --output-file to avoid colliding with the global --output.) |
--agent <AGENT> | string | — | Filter by agent identifier. |
--action <ACTION> | string | — | Filter by action type. |
--result <RESULT> | allow | deny | pending | — | Filter by policy decision result. |
--since <SINCE> | string | — | Show events after this duration or ISO 8601 timestamp. |
--until <UNTIL> | string | — | Show events before this ISO 8601 timestamp. |
--limit <LIMIT> | integer | 1000 | Maximum number of entries to fetch. |
aasm audit export --format jsonl --compliance soc2 --since 1d \
--output-file audit-2026-06-09.jsonl
aasm audit verify-chain
Verify the SHA-256 hash chain of a local JSONL audit log file. Reports one of three outcomes, each with its own exit code, so a caller never has to parse stderr wording to tell a capacity event from tamper evidence:
| Outcome | Meaning | Exit code |
|---|---|---|
OK | Every hash matches, every link matches, sequence numbers are contiguous. | 0 |
INCOMPLETE | Hashes and links are intact, but some sequence numbers never reached the file — entries were lost to emission backpressure or a crash before flush. Every entry present is unaltered; this is not tamper evidence. | 3 |
FAIL | An entry’s hash doesn’t match its own fields, or a link to the previous entry is broken — alteration or removal. | 1 |
| Argument | Type | Description |
|---|---|---|
<PATH> | path | Path to the JSONL audit log file to verify. |
aasm audit verify-chain ./audit/session-7f3a.jsonl
OK — 412 entries verified
An INCOMPLETE result names the missing sequence range and points to the
gateway log, where the audit writer logs an "audit sequence gap" warning
the moment it observes one live:
INCOMPLETE — 408 entries verified, chain intact; 4 entries never reached the
file at seq 112-115. Every entry present is unaltered: this is emission loss
(audit backpressure, or a crash before flush), not alteration. Check the
gateway log for "audit sequence gap".
Residual gaps this cannot resolve, so a truthful reading of the output
still needs them in mind: a tail deletion (the last entries in the file
removed with nothing following to break its link against) reads identically
to a tail drop — there is no entry after it to prove which happened. A
prefix deletion is similarly invisible, since a chain that legitimately
resumes mid-sequence after a restart is not itself evidence of loss. And the
chain is unkeyed (SHA-256, not HMAC): an actor who can write the file can
recompute it wholesale — verify-chain proves the file is internally
consistent, not that nobody with write access altered it. Keyed signing is
tracked separately.
aasm audit compliance-export
Full-fidelity compliance export of a local JSONL audit file. Preserves the SHA-256 hash chain anchors, credential findings (kind + offset only — never the raw secret), and delegation lineage for SIEM ingestion and regulatory review.
| Flag | Type | Default | Description |
|---|---|---|---|
--input <INPUT> | path | required | Per-session audit JSONL file produced by the gateway. |
--format <FORMAT> | csv | json | jsonl | jsonl | Export format. JSONL is preferred for SIEM/regulator ingestion. |
--compliance <COMPLIANCE> | eu-ai-act | soc2 | — | Prepend a compliance framework header. |
--output-file <OUTPUT_FILE> | path | (stdout) | Write output to a file. |
--agent <AGENT> | string | — | Filter by hex-encoded agent identifier (32 hex chars). |
--event-type <EVENT_TYPE> | string | — | Filter by audit event-type label (e.g. PolicyViolation). |
--since <SINCE> | string | — | Include entries after this duration shorthand or ISO 8601 timestamp. |
--until <UNTIL> | string | — | Include entries before this ISO 8601 timestamp. |
aasm audit compliance-export --input ./audit/session-7f3a.jsonl \
--format jsonl --compliance eu-ai-act --output-file compliance.jsonl
Last updated: 2026-09-01 by Chisanan232