YaqeenDocs
Back to Yaqeen

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 returns intact and a list of breaks.
  • 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 includes chain_intact, first_prev_hash and last_row_hash.

What verification catches#

Change to the databaseResult
A line is editedrow content does not match its hash
A line is removed from the middle, or one is insertedprevious hash does not match the row before
Lines are removed from the end, or added outside the servicechain 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.

Up Down to moveEnter to openEsc to close