audit

Displays the append-only hash-chained audit log. Every mutation (ingest, extraction, classification, reconstruction, policy creation) is recorded as an event. The hash chain can be verified to detect tampering.

Usage

bash

unsterwerx audit [OPTIONS]

Options

Option	Short	Type	Default	Description
`--action`		string		Filter by action type
`--target`		UUID		Filter by target document ID
`--limit`	`-l`	integer	50	Maximum number of events to display
`--verify`		flag		Verify hash chain integrity

Examples

View recent events

bash

unsterwerx audit --limit 10

Audit Log (10 events)
══════════════════════════════════════════════════════════════════════
  2026-02-25T18:51:31 142 [reconstruct         ] b6fae057 → success 848474a429ce
  2026-02-25T18:51:18 141 [reconstruct         ] b6fae057 → success 972ead08bada
  2026-02-25T16:38:39 140 [similarity_index    ] all → success 394171df36af
  2026-02-25T16:38:02 139 [reconstruct         ] 4b3205f1 → success 5766bf972d60
  2026-02-25T16:36:19 137 [reconstruct         ] 3fce0ad4 → success a7a679503bce
  2026-02-25T16:36:07 136 [policy_create       ] 082efb83 → success f29ca56501f9
  2026-02-25T16:36:03 135 [policy_create       ] b2569bbf → success b28b676b51cc
  2026-02-25T16:35:56 134 [policy_create       ] da05a5d5 → success 167020740ab2
  2026-02-25T16:35:55 133 [policy_create       ] 0e24c365 → success 15cb07bfa8b6
  2026-02-25T16:34:56 132 [classify            ] all → success 77f49dfb5c1d
══════════════════════════════════════════════════════════════════════

Filter by target document

bash

unsterwerx audit --target a1b2c3d4-...

Audit Log (1 events)
══════════════════════════════════════════════════════════════════════
  2026-02-25T16:36:19 137 [reconstruct         ] 3fce0ad4 → success a7a679503bce
══════════════════════════════════════════════════════════════════════

Verify hash chain integrity

bash

unsterwerx audit --verify

Verifying audit hash chain...
Chain verified: 142 events, integrity OK

Notes

Each event contains a timestamp, sequence number, action type, target, result, and hash linking to the previous event.
Action types: ingest, parse, canonical_extract, similarity_index, diff_compute, classify, archive, delete, rule_create, rule_update, rule_delete, policy_create, policy_update, reconstruct, search, config_change, import, signed_doc_modification_blocked, signature_detected, knowledge_build, knowledge_train.
The --verify flag walks the entire chain and confirms every event's hash links to its predecessor. If any event has been modified or removed, verification fails.
The trailing hex string on each event line is a truncated hash used for chain linking.