Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

Runbook: Audit Verifier Failure

Recovery steps for nexus-audit-verify failures (missing artifact, signature, ordering, Merkle mismatch)

Last updated on:

Use this runbook when nexus-audit-verify verify --archive-path <path> reports a missing artifact, signature failure, ordering inconsistency, or Merkle mismatch.

First Checks

Section titled “First Checks”
  1. Confirm the archive path contains meta-roots/ and batches/.
  2. Confirm the verifier binary was built from the same repository revision as the archive schema.
  3. Re-run verification on a read-only copy of the archive so investigation does not mutate evidence.

Failure Classes

Section titled “Failure Classes”
  • Missing artifact: compare the referenced object key in the meta-root manifest with the archive object listing.
  • Signature failure: inspect the manifest signing key id and confirm the corresponding public key is present.
  • Merkle mismatch: recompute the event canonical hash with vortex_audit_core::encode_event and compare it with the batch event list.
  • Ordering inconsistency: inspect the tenant’s batch sequence numbers and prev_merkle_root chain. The chain is one continuous sequence per tenant across the whole archive, not per meta-root: the first batch anchored by a meta-root must link to the last batch anchored by the previous one, and only a tenant’s very first batch has a zero previous root. A batch that restarts from zero mid-history indicates spliced or missing anchors.

Escalation

Section titled “Escalation”

Treat any signature failure, Merkle mismatch, or missing object-lock archive object as a security incident. Preserve the archive, Postgres snapshot, NATS stream state, service logs, and verifier output before attempting repair.