Hash-Chained Audit Trail

Every governance evaluation produces an immutable audit record linked to the previous record via cryptographic hash, creating a tamper-evident chain.

How It Works

Each audit record contains:

• Agent ID, action type, target, parameters

• Governance verdict (ALLOW, DENY, ESCALATE, MODIFY, SUSPEND)

• UCS score

• All 14 per-dimension scores

• Which tier decided and the reasoning

• Timestamp

• record_hash — SHA-256 hash linking this record to the previous

Hash Chain

Record 1: hash = SHA-256(genesis_seed + record_1_data)
Record 2: hash = SHA-256(record_1_hash + record_2_data)
Record 3: hash = SHA-256(record_2_hash + record_3_data)
...

If any record is modified, deleted, or reordered, the hash chain breaks. Verification walks the chain from any record back to the genesis record, checking each link.

Tamper Evidence

The hash chain provides:

• Insertion detection — new records between existing ones break the chain

• Modification detection — changing any field changes the hash

• Deletion detection — removing a record breaks the chain

• Reordering detection — records out of order break the chain

Viewing the Audit Trail

CLI

nomotic audit <agent-id>                           # View recent records
nomotic audit <agent-id> --filter denied           # Filter by verdict
nomotic audit <agent-id> --from 2026-01-01 --to 2026-01-31

Programmatic

records = runtime.get_audit_trail("my-agent", limit=50)

for record in records:
    print(f"{record.timestamp} | {record.verdict} | {record.action_type} → {record.target}")

Chain Verification

CLI

nomotic audit <agent-id> --verify

API

POST /v1/ui/audit/verify/{record_id}
GET  /v1/audit/{agent_id}/verify

Programmatic

from nomotic.audit_store import LogStore

store = LogStore(base_dir)
verification = store.verify_chain(agent_id)
print(f"Chain valid: {verification.valid}")
print(f"Records verified: {verification.count}")

Export Formats

Audit records can be exported for external analysis:

# CSV
nomotic audit <agent-id> --export csv

# JSON
nomotic audit <agent-id> --export json

# SIEM formats
nomotic siem-export --format cef    # Common Event Format
nomotic siem-export --format syslog # Syslog
nomotic siem-export --format jsonl  # JSON Lines

Compliance Evidence Bundles

Export audit records packaged with governance context for compliance reviews:

bundle = runtime.export_compliance_bundle(
    agent_id="my-agent",
    framework="SOC2",
    date_range=("2026-01-01", "2026-03-31")
)
bundle.save("compliance-evidence-q1-2026.zip")

Audit Retention

nomotic config set --retention 90d

Governance Scorecard Integration

The governance scorecard uses the latest audit record hash as a provenance marker. The scorecard's audit_record_hash field lets auditors verify that the scorecard was generated from an unmodified audit trail.

BehaviorLedger

The audit trail logs what happened. The BehaviorLedger extends this by reconstructing why it happened. Each BehaviorLedgerEntry is a complete, self-contained decision record that captures the full pipeline trace, behavioral state, contract snapshot, semantic context, causal links to previous decisions, and what would need to change for a different outcome. Enable with enable_behavior_ledger=True in RuntimeConfig.