ADR-055: Acknowledging audit integrity findings
Status
Accepted. Builds on ADR-023: Audit hash chain HMAC consideration and ADR-034: Audit chain tip anchor.
Date
2026-11-14
Context
The backend "Verify chain" view ran only verify and printed bare
error strings. vault: runs the full verification (chain, external
anchor, reason codes), so an administrator who saw a finding in the backend could
neither see the full picture nor close the finding without the command line. The
only repair path on the command line is vault:, which
clears the in-database anchor and records that in the chain, and
vault:, which re-seals the chain and refuses to run on a
chain that fails verification.
A finding about history that cannot be re-written has no repair. Rows that failed their hash stay failed, a deleted row stays deleted, and a restored database stays shorter than the external anchor says. Without a way to record "this was investigated and accepted", the readiness check stays red forever, and the only way back to green is to re-seal, which turns tampering into a valid-looking chain.
Decision
The backend runs the same verification as the command line
(Chain) and shows the reason code of every
finding, the verified range, the epoch distribution, the chain tip and the
comparison with the external anchor. It checks audit., the permission
vault: asserts as well.
An administrator can acknowledge the open findings. The acknowledgement is an append-only audit row, never a repair:
- One chained row with the action
audit_. Itsfindings_ acknowledged reasonis the mandatory free-text reason; its context holds the keys of the acknowledged findings, the old chain tip, the optional ticket reference, the reason codes, the affected uid ranges and, under switch-user, the original backend user. The acting administrator is the row's own actor. - The flagged rows are not touched. They keep failing their own hash, and
verify,Hash Chain () verifyand with them every re-seal path (HMAC migration, master-key rotation, rotation-gap repair) keep refusing the chain.Chain For Reseal () - The acknowledgement is an overlay one level above the raw chain pass
(
Audit).Finding Overlay Chain(and with itTip Anchor Service vault:, the scheduler task and the backend view) and the boundedaudit- verify audit.check read through it, so they agree.hash_ chain vault:reports the raw result and stays unaffected.audit -- verify - When the in-database tip anchor is part of the finding, it is reset and
re-armed in the same transaction, the sequence
--uses. The external anchor is published afresh after the commit, which starts the new verified segment: the acknowledgement row is the new tip.reset- anchor
What an acknowledgement covers
Findings fall in three classes:
-
Row and gap findings. The item key is a hash over the reason code, the position and the complete stored content of the affected row (the digest of the whole row as stored, byte for byte). The verifier treats the item as acknowledged only when all of this holds:
- The acknowledgement row lists the item's key. Editing the flagged row again, in any column, produces another key and reopens the finding. A finding that appears later has another key and fails.
- The acknowledgement row is itself not reported as failing, so a tampered or forged acknowledgement proves nothing.
- The row was written at HMAC epoch 3 or higher, where the MAC covers
reason,contextand the actor columns. At epoch 2 or below a database-write attacker could forge or edit an acknowledgement without the key, so the backend refuses to write one. - The row was chained directly after the tip it recorded
(
previous_equals the recorded tip hash). A row from a concurrent writer landing in between makes the acknowledgement inert, which cannot cover rows written later. The flow reads the verdict back after writing and reports "not in effect, run it again".hash - The row follows the flagged row in the chain.
- Chain-level findings without a row: the chain-wide epoch-floor error and
the comparison with the external anchor (
TABLE_, and the anchored-epochRESET EPOCH_). The key of an external-anchor finding is the compared anchor, not how the chain differs from it: after a restore the same anchor reads first as a shrunken and later as a substituted chain. What stops a later incident from inheriting the acknowledgement is a binding to the chain prefix the administrator saw. The acknowledgement records the tip uid and hash it was chained after; the finding is covered only while the row at that uid still carries that hash. Rewriting or truncating the chain up to that tip uncovers it again. A finding against the external anchor is additionally covered only while the anchors published since stay consistent with the chain. The acknowledgement records how many anchor records the file held; of the records after that position, each one that reaches the acknowledgement row (sequence at or above its uid) must carry the stored entry hash of the row at its sequence, and at least one must exist. A later truncation below such an anchor, an appended record with a wrong tip and a replayed old anchor file all reopen the finding; the timestamp of a record decides nothing, because whoever can append to the file could set it to anything. The flow publishes the fresh anchor; without an external sink the request is refused before anything is written. The reader keeps the anchor with the highest sequence, which after a restore stays the old one, so the later anchors are read from the file directly.DOWNGRADE - The in-database anchor errors are never covered. They carry no per-incident state, so an acknowledgement would also hide a later incident of the same kind. The flow resets and re-arms the in-database anchor in the same transaction, the finding stops being reported, and a recurrence is new.
The administrator is shown the findings and confirms a fingerprint over their keys. If the set of open findings differs when the request arrives, the request is refused as stale. Ordinary appends do not change the set, so a live chain does not make the flow unusable.
Flow and access
- Administrator only, through the same bypass seam as the other vault
operations (
is, so a hardened profile withCurrent Actor Admin () disableneeds an open break-glass window), plusAdmin Override audit.. No new group-grantable permission.view POSTonly; the route token that every backend module route carries is the CSRF protection. A GET is answered with 405. The administrator ticks an explicit confirmation and states a reason (at most 1000 characters; the ticket reference at most 100).- Idempotent: after the first success the findings are acknowledged, so a repeated request is refused as "nothing to acknowledge".
- At most 200 findings per acknowledgement. Beyond that the chain has been damaged wholesale, and the evidence export and an investigation come first.
- Before acting, the administrator can download the evidence (JSON or CSV):
the affected rows with five neighbours on each side, the anchor and the
verification report. The export needs
audit., like every export.export - Only tamper evidence can be acknowledged (
HASH_,MISMATCH UID_,GAP TABLE_,RESET EPOCH_).DOWNGRADE NO_andEXTERNAL_ SINK SINK_are configuration and delivery findings; they get fixed.FAILURE
Consequences
- The readiness check can return to green without the command line and without re-sealing, while the history keeps the incident, who accepted it and why.
- The raw chain pass and the re-seal guards are unchanged by design. A chain that was acknowledged and later needs an HMAC migration is refused until the findings are resolved outside the vault.
- An acknowledgement is not a verification of the acknowledged rows. It states
that an administrator accepted them for a reason. The auditor reads that
reason;
vault:lists the acknowledged items next to the open ones.audit- verify -- format=json vault:dispatches an alert event per open finding on every run. The backend view, the acknowledgement flow and the evidence export useaudit- verify inspect, which does not dispatch, so a page load by any() audit.user does not alert the sinks and one action does not alert three times.view - Known limits of the external-anchor binding, all failing closed. A record appended to the anchor file with a sequence at or above the acknowledgement row and a wrong tip withdraws that acknowledgement, and the verifier keeps the first acknowledgement row per finding, so a second acknowledgement of the same finding does not replace it; clearing it needs an operator to remove the bad record from the file. The anchors after the recorded position are read from the whole file and checked one query each. The position is a count of records, not a content hash, so rewriting the file before it shifts the window; rewriting the anchor file already blinds the external anchor without any acknowledgement involved.
- The key of a row finding hashes every stored column of the row. A release
that adds a column to
tx_therefore changes the key of every acknowledged row finding, and those findings are open again after the database schema update until an administrator acknowledges them again. This fails closed; such a release says so in its upgrade notes.nrvault_ audit_ log - Every failing row becomes a finding item, and its stored content is read once per verification to build the key. A chain that fails as a whole (for example after a restore with the wrong master key) costs memory and queries in proportion to the number of failing rows. The cost has not been measured on large chains.
- When the oldest rows of the chain were deleted, the readiness check, which verifies only the newest 1000 rows, reports a gap from the start of its window to the first remaining row that the full pass does not report. An acknowledgement made in the backend does not cover that gap, so the check stays critical until the window has moved past the first remaining row. This fails closed.