Audit Trail & Hash Chain

Every action that passes through TheWARDN governance pipeline -- regardless of verdict -- produces an immutable, hash-chained audit record. This audit trail is the evidentiary backbone of the platform. It provides tamper detection, regulatory compliance, and full forensic reconstruction of every governance decision.

Why Hash Chains

Traditional audit logs are append-only text files or database rows. They can be modified, deleted, or reordered without detection. A hash chain solves this by linking each record to the previous one via cryptographic hashing:

Record 1          Record 2          Record 3          Record 4
+----------+      +----------+      +----------+      +----------+
| seq: 1   |      | seq: 2   |      | seq: 3   |      | seq: 4   |
| hash: H1 |      | hash: H2 |      | hash: H3 |      | hash: H4 |
| prev: 0  |--+   | prev: H1 |--+   | prev: H2 |--+   | prev: H3 |
| payload  |  |   | payload  |  |   | payload  |  |   | payload  |
+----------+  +-->+----------+  +-->+----------+  +-->+----------+

If Record 2 is modified after the fact, its hash changes. But Record 3's prev_hash still points to the original H2. The chain breaks, and tampering is detected.

This is the same principle behind blockchain, but without the distributed consensus overhead. TheWARDN uses a single-authority hash chain -- simpler, faster, and equally tamper-evident for a centralized governance system.

Audit Record Structure

Each audit record contains:

Field	Type	Description
seq	integer	Monotonic sequence number. Starts at 1, increments by 1 for every record. No gaps allowed.
hash	string	SHA-256 hash of the current record's payload concatenated with prev_hash.
prev_hash	string	The hash of the immediately preceding record. First record uses "0".
verdict	string	CLEARED, HELD, or BLOCKED.
tier	string	A, B, C, or X.
action_type	string	The type of action that was governed (e.g., code_deploy, data_read).
agent_id	string	The agent that submitted the action.
target_service	string	The service the action targeted.
environment	string	The environment (e.g., production, staging).
reasoning	string	Sentinel's human-readable reasoning for the verdict.
confidence	object	The agent's reported confidence scores (incident, fix, containment).
policies_fired	array	List of CHAM policy IDs that fired during evaluation.
rule_violated	string	If BLOCKED, the SGP or policy that was violated. Null for CLEARED/HELD.
sealed_at	timestamp	ISO 8601 timestamp of when the record was sealed.
escrow_id	string	If the action was HELD, the escrow record ID. Null otherwise.
governance_mode	string	The tenant's governance mode at the time of evaluation.

Hash Computation

The hash for each record is computed as follows:

hash = SHA-256(
  seq + "|" +
  agent_id + "|" +
  action_type + "|" +
  target_service + "|" +
  environment + "|" +
  verdict + "|" +
  tier + "|" +
  JSON.stringify(confidence) + "|" +
  reasoning + "|" +
  JSON.stringify(policies_fired) + "|" +
  (rule_violated || "") + "|" +
  sealed_at + "|" +
  prev_hash
)

The use of prev_hash as input to the current hash creates the chain. Every record's hash is a function of its own content AND the entire history that preceded it.

WARNING

The hash computation is deterministic and reproducible. Anyone with access to the audit records can recompute every hash from scratch and verify the chain's integrity. This is by design -- auditability requires verifiability.

Chain Verification

TheWARDN provides a verification endpoint that walks the entire hash chain and confirms its integrity:

GET /audit/verify

Response (chain valid):

{
  "status": "VALID",
  "records_verified": 10482,
  "first_seq": 1,
  "last_seq": 10482,
  "gaps": [],
  "mismatches": [],
  "verified_at": "2026-04-10T16:00:00Z"
}

Response (chain broken):

{
  "status": "INVALID",
  "records_verified": 10482,
  "first_seq": 1,
  "last_seq": 10482,
  "gaps": [],
  "mismatches": [
    {
      "seq": 4201,
      "expected_hash": "a1b2c3d4...",
      "actual_hash": "e5f6g7h8...",
      "description": "Record 4201 hash does not match recomputed hash. Record may have been modified."
    }
  ],
  "verified_at": "2026-04-10T16:00:00Z"
}

Verification Checks

The verification endpoint performs three checks:

Check	What It Validates
Sequence continuity	No gaps in the seq numbers. Every integer from 1 to N is present.
Hash chain integrity	Each record's prev_hash matches the previous record's hash.
Hash recomputation	Each record's hash is recomputed from its fields and compared to the stored hash.

If any check fails, the verification returns INVALID with details about which records are affected.

Querying the Audit Trail

List Recent Records

GET /audit?limit=50&offset=0

Filter by Verdict

GET /audit?verdict=BLOCKED&limit=50

Filter by Agent

GET /audit?agent_id=agt_abc123&limit=50

Filter by Time Range

GET /audit?from=2026-04-01T00:00:00Z&to=2026-04-10T23:59:59Z

Filter by Tier

GET /audit?tier=X&limit=50

Combined Filters

GET /audit?agent_id=agt_abc123&verdict=BLOCKED&environment=production&from=2026-04-01T00:00:00Z

Export for Regulators

Audit records can be exported in two formats for regulatory compliance:

PDF Export

GET /reports/audit?format=pdf&from=2026-04-01&to=2026-04-10

Produces a formatted PDF report with:

• Summary statistics (total actions, verdict distribution, tier distribution)
• Hash chain verification status
• Complete audit record listing
• Violation details for BLOCKED actions

CSV Export

GET /reports/audit?format=csv&from=2026-04-01&to=2026-04-10

Produces a CSV file with one row per audit record, suitable for importing into spreadsheets, SIEM systems, or compliance platforms.

TIP

Schedule regular audit exports (weekly or monthly) and store them in a separate, read-only location. This provides an additional layer of evidence preservation beyond the hash chain itself.

Tamper Detection Scenarios

The hash chain detects the following classes of tampering:

Scenario	Detection Method
Record modification	Recomputed hash does not match stored hash
Record deletion	Gap in sequence numbers
Record insertion	Sequence continuity intact but hash chain breaks at insertion point
Record reordering	prev_hash links break at reordered positions
Bulk replacement	Unless the attacker has access to the hash computation and can recompute the entire chain from the point of modification forward, the chain breaks

WARNING

The hash chain protects against undetected tampering, not against tampering itself. If an attacker has write access to the database, they could theoretically recompute the entire chain from a modification point forward. To mitigate this, export and externally store periodic hash chain snapshots. These snapshots act as anchors -- even if the chain is recomputed, the snapshots will not match.

Retention

Audit records are retained according to the tenant's configured retention policy. Default retention is 7 years, which meets the requirements of most regulatory frameworks:

Regulation	Minimum Retention
HIPAA	6 years
SOC 2	7 years
PCI-DSS	1 year (3 years recommended)
GDPR	As long as necessary for the purpose
EU AI Act	Duration of the AI system's lifecycle + 10 years

Retention can be overridden by CHAM compliance_pack policies that specify longer retention periods for specific data classifications or action types.

Audit Trail and SGP

Two SGP principles directly protect the audit trail:

• SGP-2 (Audit Completeness): Every governed action must produce a complete, hash-chained audit record. No exceptions. If audit record creation fails, the action is BLOCKED.
• SGP-7 (Hash Chain Continuity): The audit hash chain must be continuous. A gap in the chain is a governance failure that triggers an alert.

Together, these principles ensure that the audit trail is comprehensive and tamper-evident at a principle level, not just a policy level.

Integration with Governance Dashboard

The audit trail feeds the governance dashboard with real-time metrics:

Dashboard Widget	Audit Data Source
Actions per hour	Count of records per time window
Verdict distribution	Aggregation of verdict field
Tier distribution	Aggregation of tier field
Top policy triggers	Frequency analysis of policies_fired
Violation timeline	Filtered view of tier: X and tier: C records
Agent health	Per-agent aggregation of verdicts and violations
Chain health	Latest verification status