11 , audit and DPR

Audit and Decision-Provenance Records

Every decision Faramesh makes is permanently recorded. Not in a log file that can be rotated or deleted , in a tamper-evident, hash-chained sequence of Decision-Provenance Records (DPRs). Each record contains a SHA-256 hash of the previous record, forming a cryptographic chain. If any record is altered, inserted, or deleted, the chain breaks and faramesh audit verify catches it.

This is not just logging. This is cryptographic proof that every agent action was governed. An auditor can independently verify the chain without access to the running daemon. They can check that no decision was retroactively changed, that no record was deleted to cover up a policy violation, and that the sequence of events is authentic.

The DPR chain is the foundation for compliance. When a regulator asks "was this agent governed?", you hand them the chain and they can verify it independently. When your security team investigates an incident, the DPR chain tells them exactly what happened, in what order, and which policy rule was responsible for each decision.

DPR chain structure

Each record stores the decision, the policy rule that fired, the tool call arguments, the timestamp, and a SHA-256 hash of the previous record. This forms an append-only chain.

{
  "seq": 1042,
  "prev_hash": "a3f8c1...d4e2",
  "verdict": "DENY",
  "rule_id": "deny-destructive-shell",
  "tool": "shell/run",
  "agent_id": "support-bot",
  "timestamp": "2025-07-14T09:23:01Z",
  "hash": "b7e4f2...c9a1"
}

Stream live decisions

Watch decisions as they happen.

faramesh audit tail

faramesh audit tail --agent support-bot

Verify chain integrity

Walk the entire chain and check every hash link. Any tampered or missing record is flagged.

faramesh audit verify /var/lib/faramesh/faramesh.db

Export records

Export audit records for compliance or analysis. Supports JSON, CSV, and SPDX formats.

faramesh audit export \
  /var/lib/faramesh/faramesh.db \
  --format json \
  --agent support-bot \
  --effect DENY \
  > audit-export.json

Query audit records

Filter decisions by agent, verdict, tool, or time range.

faramesh audit export /var/lib/faramesh/faramesh.db \
  --agent support-bot \
  --effect DENY \
  --format jsonl

Aggregate statistics

Generate high-level decision and agent statistics from DPR history.

faramesh audit stats /var/lib/faramesh/faramesh.db

Compliance export

Generate compliance-ready reports for SOC2, GDPR, or ISO 27001 frameworks.

faramesh compliance export --framework soc2