Explanation
How the audit chain works
How Yaqeen records every change in a tamper-evident log, what verification catches, and what it cannot.
Every decision in Yaqeen writes a line to an audit log. Each line is linked to the line before it by a hash, so an edit leaves a trace. This page explains how the chain is built and how to check it. The log is tamper-evident, not tamper-proof: it can show that a record changed, but it cannot stop someone with enough access from changing it.
How a line is written#
A hold decision, an appeal, a policy change, a key creation and a document opening all write one audit event. The event is written in the same database transaction as the change. If the change fails and rolls back, the event rolls back with it.
Each event stores the SHA-256 hash of the event before it (prev_hash) and its own hash (row_hash). The row hash covers the previous hash, the event id, the time, the actor, the action, the subject and the payload. The first event links to a fixed starting value of 64 zeros. A single locked row holds the latest hash, so all events form one line, even when several people act at once.
A database trigger refuses UPDATE, DELETE and TRUNCATE on the table. Events never hold passwords, tokens or the text of case notes. The audit line for a note records that it was added and how long it is.
How to verify#
Three ways give the same answer:
GET /api/v1/ops/audit-verify/(admins) recomputes every hash and returnsintactand a list ofbreaks.- Yaqeen checks the chain every day and alerts its operators if it is broken.
GET /api/v1/audit/export/?from=&to=(reviewers and admins) returns the lines for a date range of up to 92 days. The response includeschain_intact,first_prev_hashandlast_row_hash.
What verification catches#
| Change to the database | Result |
|---|---|
| A line is edited | row content does not match its hash |
| A line is removed from the middle, or one is inserted | previous hash does not match the row before |
| Lines are removed from the end, or added outside the service | chain head does not match the last row |
What verification does not prove#
Verification proves that the log is consistent. It does not prove that the log is the original, and it cannot show an action that never wrote a line. To guard against a rewrite, keep the last_row_hash of each export somewhere outside Yaqeen and check that later exports still lead to it. We do not claim legal tamper-proofing.
Reading your own lines#
All organizations share one chain, so seq numbers have gaps when you read only your own lines. GET /api/v1/audit/ (reviewers and admins) returns your organization's lines, and can filter by subject_type and subject_id. From an export you can check that each line's prev_hash equals the row_hash of the line before it, which shows a gap if a line is missing. To recompute a row_hash you also need the numeric actor id, which the export does not carry, so only Yaqeen can fully recompute it.
Related#
- Export and verify audit: the steps
- Security: the other controls
- Privacy and trust: what the public trust endpoints show