Audit integrity and verification
This page is for administrators and information security officers who may have to present audit records as evidence, for example in a disciplinary case, an investigation or a dispute about who changed official information. It explains how the integrity of Exponential's audit trail is protected and checked, from 5.3 The hash chain and what verification finds and 4.4 Verify and restore.
Contents
How tampering shows
- Hash chain per channel: every record carries the SHA-256 hash of the record before it; the first file starts from a value derived from the installation id and the channel, so a chain cannot be passed off as another's.
- Signed checkpoints: once a day,
system.audit.checkpointrecords every channel's current position and hash, signed with HMAC-SHA-256, and goes to the sinks. A chain recomputed afterwards no longer matches a checkpoint signed before. - Signed manifests for each archived day, chained to each other, so removing a whole archived day shows too.
An attacker with full control of the server could still delete everything; that is why forwarding records and checkpoints off the machine matters (see "Forwarding the audit trail to a SIEM").
Verifying
./console exp:audit verify --allow-root-user # live files, every channel
./console exp:audit verify --archives --allow-root-user # archives too
./console exp:audit verify --channel=access --date=<YYYY-MM-DD> --allow-root-user
./console exp:audit verify -q --allow-root-user || <your alert command>Exit code 0 means intact, 1 broken, 2 error, so the command fits monitoring. The cronjob part verifies every channel
daily; Verify now on the Audit dashboard does it on demand (audit/manage; with ReauthForManage=enabled the
user's password is asked first). For long retention, the guide recommends running verify --archives monthly and
keeping its output.
What a finding means
| Kind | Means |
|---|---|
altered | a record was changed |
link, gap, reordered | lines removed, inserted or swapped |
missing_file, truncated | a file is gone, or lines were cut off |
rewritten | a signed checkpoint recorded another hash: the chain was recomputed |
checkpoint_invalid, unknown_key | a checkpoint does not verify, or its key is not in the settings |
archive_sha256, hmac_invalid, previous_manifest | an archive changed, a manifest was edited, an archived day removed |
repaired (not a break) | a torn last line followed by a recorded repair |
When a chain is broken
The audit guide's instruction is: do not edit or remove anything.
- Note the file, line and kind of change from the verify output.
- Copy the audit directory to safe, read-only storage.
- Compare with what left the server: syslog or journal copies, the webhook receiver, the checkpoints sent by the sinks, the archives.
- Treat it as a security incident (see "Incident response").
- A broken file stays a record: the console still shows it and marks it.
Keys
The signing and pseudonym keys are in settings/override/audit.ini.append.php (mode 0640, never committed),
generated on first use (4.6 Keys):
- back the file up as a secret; without the signing keys, old archives cannot be verified (
unknown_key); - rotate the signing key once a year, and at once if it may have been read:
./console exp:audit key rotate --apply --allow-root-user; old keys stay for their archives; - keys can come from a secrets store with
[AuditKeySettings] GenerateKeys=disabled.
Related pages
- Audit guide, 5.3
- The audit trail for public bodies
- Audit trail
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.