Free and open source · Apache-2.0
hc-verify: check offline that a tamper-evident audit log is intact
Check offline that nothing in a HostCrust change log was edited, removed or reordered.
hc-verify is a free, open-source (Apache-2.0) command-line tool that checks a HostCrust receipts export offline and tells you whether any entry in its hash-chained audit log was edited, removed or reordered. It recomputes every SHA-256 hash itself and trusts nothing in the file. The chain has no signatures, so a pass shows the log is intact, not who wrote it.
It's one Python file with no dependencies and no network access. Add an anchor, a chain head kept outside the log, to also catch deleted recent entries and a log rebuilt with new hashes.
git clone https://github.com/HostCrust/hc-verify
cd hc-verify
python3 hc_verify.py receipts.json
- License
- Apache-2.0
- Version
- 1.0.1 (November 14, 2026)
- Runs on
- Linux, macOS, other systems with Python 3.9+ (tested on 3.12 and 3.14)
- Needs
- Python 3.9 or newer, standard library only
- Written in
- Python
What is a hash-chained receipt?
A hash-chained receipt is a tamper-evident record of one change to a server, built from audit log entries that are linked by SHA-256 hashes. In HostCrust, every step of a change is an entry in the organization's log: request, approval or rejection, dispatch, result and verification. Each entry stores the hash of the entry before it (prev_hash) and its own hash, which is SHA-256 of that previous hash plus the entry's content written as canonical JSON. Entries about the same change also name the previous step of that change, so a receipt holds together even when other log entries sit between its steps. If anyone edits a field, that entry's hash no longer matches. If anyone removes or reorders entries, a link breaks. A receipt doesn't prevent tampering. It makes tampering visible to anyone who recomputes the hashes, which is what hc-verify does.
One real entry from the sample receipt in the repository, the moment a patch job was handed to its server:
{
"id": "7c72f3aa-6f82-40a6-bdb5-5441c7435c05",
"org_id": "f27f98f2-7ad6-4c8e-ac24-52642961e415",
"seq": 9,
"at": "2026-11-14T15:57:48.590542Z",
"actor_type": "agent",
"actor_id": "0317703d-505f-4836-8a02-29ec7425596b",
"event": "job.dispatched",
"target_type": "job",
"target_id": "10ffb73a-6519-4293-b435-821d6ab6c8e5",
"data": {
"action": "patch.packages",
"action_hash": "78d01416e9e0cb439c36075835edb7a3f8a522b8cf575ad6e2bdb159b3be60e3",
"target_prev_hash": "7c338fb2c3453fb01cd756924cd5f07316671e413483f873ad0c4df218d43bdf"
},
"prev_hash": "7c338fb2c3453fb01cd756924cd5f07316671e413483f873ad0c4df218d43bdf",
"hash": "db59db42c34f460b36a973cf797cb7083ff9eeb0809d3d0e0133fe0c8d9e4b92"
}
Its prev_hash is the hash of seq 8, the approval, which was also this job's previous step (data.target_prev_hash). The action_hash ties the dispatch to the exact action requested.
How does a hash chain make an audit log tamper-evident?
A hash chain makes an audit log tamper-evident by making every entry depend on all the entries before it. Each entry's hash covers the previous entry's hash plus its own content, so the newest hash, the chain head, sums up the whole log. Change one character in an old entry and its hash changes, while the next entry still points to the old hash, so the link breaks. Delete an entry and the sequence numbers skip. Swap two entries and they're out of order. What a chain can't catch on its own is someone who removes the newest entries, or who edits an entry and then recomputes every later hash. Both leave a shorter or different chain that is still consistent. Catching those needs a copy of the chain head kept where the log's keeper can't change it, called an anchor.
Verify a receipts export offline
1. Get an export
In HostCrust, open a change and use Receipt (JSON) for that one action (any member of the organization can), or use Actions → Receipts and export for everything in a date range (admins and owners).
hc-verify ignores the hashing rules an export describes and uses its own copy, so a crafted file can't change what it's checked against. To follow along without an account, use the two sample exports in tests/fixtures/, written by the HostCrust app's own test suite: one patch.packages change, and the full date-range export of that test organization.
2. Run hc-verify
From the repository folder:
$ python3 hc_verify.py tests/fixtures/sample-action-receipt.json; echo "exit $?"
hc-verify 1.0.1: tests/fixtures/sample-action-receipt.json
organization Acme (f27f98f2-7ad6-4c8e-ac24-52642961e415)
scope one action: patch.packages (job 10ffb73a-6519-4293-b435-821d6ab6c8e5)
records 5 (seq 7 to 12)
last hash ec4612ab792b348e9b0bf5cb7751ec1adacbc5798d2043157a07ec5164350b46
Limit: an export alone can't show entries cut off after its last one, or a chain rebuilt with new hashes. Check it against an anchor from HostCrust's anchor email (--anchor), the chain head in your dashboard (--head), or an earlier export (--against).
OK: every hash recomputed; no record was edited, removed or reordered. (Not anchored: see the limit above.)
exit 0
Seq 10 is missing on purpose: it's a server inventory entry, not part of this job. The verdict is always the last line, and text from the file is printed above it with escape sequences made visible, so a crafted export can't hide FAILED or fake OK.
3. What a failed check looks like
We changed one field in a copy of the receipt: the approver's email address in seq 8.
$ sed 's/approver@example.com/someone-else@example.com/' tests/fixtures/sample-action-receipt.json > tampered.json
$ python3 hc_verify.py tampered.json; echo "exit $?"
hc-verify 1.0.1: tampered.json
organization Acme (f27f98f2-7ad6-4c8e-ac24-52642961e415)
scope one action: patch.packages (job 10ffb73a-6519-4293-b435-821d6ab6c8e5)
records 5 (seq 7 to 12)
last hash ec4612ab792b348e9b0bf5cb7751ec1adacbc5798d2043157a07ec5164350b46
problem 1: seq 8 (job.approved): edited: the entry's content no longer matches its hash
FAILED: 1 problem (listed above, the earliest first).
exit 1
Deleting the dispatch (seq 9) from the date-range export breaks two checks: the sequence skips, and the job's next step still names the deleted entry.
$ python3 -c 'import json; d = json.load(open("tests/fixtures/sample-range-receipts.json")); d["records"] = [r for r in d["records"] if r["seq"] != 9]; json.dump(d, open("removed.json", "w"))'
$ python3 hc_verify.py removed.json | tail -n 3
problem 1: seq 10 (inventory.classified): missing record(s): seq 9 removed from the chain
problem 2: seq 11 (job.finished): broken link: it names db59db42c34f460b… as the previous entry of this action, but that is seq 8 (7c338fb2c3453fb0…): an entry between them was removed or replaced
FAILED: 2 problems (listed above, the earliest first).
Exit status 1 means verification failed, and 2 means the file couldn't be read.
| Option | What it adds |
|---|---|
--anchor SEQ:HASH | The export must still hold this entry, unchanged (repeatable) |
--head HASH | The export must end at this hash |
--against OLDER.json | Entries in both files must be identical, and none may have gone missing |
--json | The report as JSON, for scripts |
What do anchors catch that the hash chain can't?
An anchor is a copy of the chain head, a sequence number and its hash, kept somewhere the log's keeper can't edit later. It catches the two attacks a hash chain alone misses. The first is tail deletion: removing the newest entries leaves a shorter chain that still links up, but the anchored entry is now missing. The second is full re-hashing: someone with database access edits an old entry and recomputes every later hash, which produces a new chain that is internally perfect but no longer contains the anchored hash. With hc-verify --anchor SEQ:HASH, the export must still hold that exact entry, and a date-range export that ends before it fails. The protection only reaches back from the anchor. Entries written after the most recent anchor are protected by the chain alone until the next anchor is published, so a log that is anchored often leaves a smaller gap.
Once a day while an organization's chain is changing, HostCrust emails its chain head to the organization's owners and writes it to journald on HostCrust's own server, places the app can't rewrite later. Keep those emails: someone in control of HostCrust could stop future anchors, but can't recall sent ones.
Try both attacks on the sample export
This script makes both forgeries with hc-verify's own hash function, so the second file is internally consistent:
# forge.py: two edits that a hash chain on its own can't catch
import json
import hc_verify as h
src = "tests/fixtures/sample-range-receipts.json"
# 1. Cut off the newest entry, and fix the export's own description to match
doc = json.load(open(src))
doc["records"].pop()
doc["scope"]["last_seq"] = doc["records"][-1]["seq"]
json.dump(doc, open("tail-cut.json", "w"), indent=1)
# 2. Change who approved seq 8, then recompute every hash and link after it
doc = json.load(open(src))
prev, last = h.GENESIS, {}
for r in doc["records"]:
if r["seq"] == 8:
r["data"]["approver_email"] = "someone-else@example.com"
if "target_prev_hash" in r["data"]:
r["data"]["target_prev_hash"] = last.get(r["target_id"])
r["prev_hash"] = prev
r["hash"] = prev = h.entry_hash(prev, {k: r[k] for k in h.RECORD_FIELDS})
last[r["target_id"]] = r["hash"]
json.dump(doc, open("rebuilt.json", "w"), indent=1)
Without an anchor, both pass. With the anchor for seq 12, the sample organization's chain head at export, both fail:
$ python3 forge.py
$ python3 hc_verify.py tail-cut.json | tail -n 1
OK: every hash recomputed; no record was edited, removed or reordered. (Not anchored: see the limit above.)
$ python3 hc_verify.py tail-cut.json --anchor 12:ec4612ab792b348e9b0bf5cb7751ec1adacbc5798d2043157a07ec5164350b46; echo "exit $?"
hc-verify 1.0.1: tail-cut.json
organization Acme (f27f98f2-7ad6-4c8e-ac24-52642961e415)
scope date range 2026-11-13T00:00:00Z to 2026-11-15T00:00:00Z
records 11 (seq 1 to 11)
last hash 55507692202175161d56ce9a21cdb29f5f95eef65397726fbc4c0285db0aed2e
problem 1: seq 11 (job.finished): the export ends at seq 11, before the anchored entry seq 12: entries were removed (or the range ends too early)
FAILED: 1 problem (listed above, the earliest first).
exit 1
$ python3 hc_verify.py rebuilt.json | tail -n 1
OK: every hash recomputed; no record was edited, removed or reordered. (Not anchored: see the limit above.)
$ python3 hc_verify.py rebuilt.json --anchor 12:ec4612ab792b348e9b0bf5cb7751ec1adacbc5798d2043157a07ec5164350b46 | tail -n 2
problem 1: seq 12 (job.verified): differs from the anchor (ec4612ab792b348e…): the chain was rewritten after the anchor was published
FAILED: 1 problem (listed above, the earliest first).
An earlier export you kept works like an anchor:
$ python3 hc_verify.py rebuilt.json --against tests/fixtures/sample-range-receipts.json | tail -n 6
problem 1: seq 8 (job.approved): differs from the earlier export: the entry was changed since
problem 2: seq 9 (job.dispatched): differs from the earlier export: the entry was changed since
problem 3: seq 10 (inventory.classified): differs from the earlier export: the entry was changed since
problem 4: seq 11 (job.finished): differs from the earlier export: the entry was changed since
problem 5: seq 12 (job.verified): differs from the earlier export: the entry was changed since
FAILED: 5 problems (listed above, the earliest first).
What hc-verify checks
| Check | What it catches | Applies to |
|---|---|---|
Each hash equals SHA-256 of prev_hash plus the canonical JSON of the entry | Any edited field | Every export |
seq increases through the file | Reordered entries | Every export |
Exactly the expected fields; no duplicate keys, fractions or NaN | Fields the hash doesn't cover; JSON that parsers read differently | Every export |
No gaps in seq; each prev_hash is the hash before it; seq 1 links to 64 zeros | Removed entries and broken links | Date-range exports |
data.target_prev_hash names the job's previous step; a receipt starts with job.requested | A removed or replaced step of one change | Job entries |
The request's action_hash is recomputed; the approval and dispatch must name it | Approving or dispatching a different action than the one requested | Job entries |
--anchor, --head, --against | Deleted recent entries; a re-hashed chain | When you supply one |
What hc-verify can't prove
From the hc-verify README and HostCrust's security documentation:
- Entries after the last anchor are protected by the chain alone. Until the next anchor, someone who controls the HostCrust app or its database could rewrite or cut off those entries and recompute the hashes. Only an earlier export that already holds them would show it.
- Consistent isn't authentic. The chain has no signing key. A file invented from nothing, with correct hashes, also passes. Only an anchor that reached you outside HostCrust, or an earlier export you kept, ties a file to the real log.
- Integrity, not truth. hc-verify shows the log is the same log, not that it records what happened. The request, policy decision, approval and dispatch are HostCrust's own records. The result (
job.finished) and verification (job.verified) are reported by the HostCrust agent on the server, which runs as root there. HostCrust doesn't observe the server independently, so someone with root on it could report a patch that never ran. Verification entries say so with"evidence": "agent-reported", a field added on 14 Nov 2026 (UTC) that the older sample exports lack. - Anchors go to the organization's owners, who usually hand over the export. If you audit someone else's servers, collect exports on a schedule and keep them for
--against. - Only HostCrust exports. It isn't general audit trail software.
How does hc-verify compare with other tamper-evidence approaches?
A hash chain is one of the simplest ways to make an audit trail tamper-evident, and Schneier and Kelsey's 1999 design for secure audit logs uses one. The approaches below are layers more than rivals: strong designs combine prevention, detection and a copy kept elsewhere.
| Approach | Example | What it gives you | Main limit |
|---|---|---|---|
| Append-only database table | PostgreSQL grants without UPDATE or DELETE, plus refusing triggers | The app, or anyone with only its credentials, can't change rows | The table owner can disable triggers, and outsiders get no evidence either way |
| WORM storage | Amazon S3 Object Lock, compliance mode | No user, not even the account's root user, can overwrite or delete a locked version before its retention date | Doesn't show the content was right when written; you trust the provider; new versions can still be added |
| Signed or sealed logs | AWS CloudTrail digest files; journald Forward Secure Sealing | CloudTrail signs an hourly digest (SHA-256 with RSA) that carries the previous digest's signature; journald's verification key is meant to be kept off the host | You trust the signer's keys. journald's sealing key changes every 15 minutes by default, and changes within the current interval can go undetected |
| Database ledger | Ledger tables in SQL Server 2022 and later, and Azure SQL | SHA-256 Merkle trees per transaction, chained blocks, and digests that can be stored in immutable storage | Detects, doesn't prevent, an administrator editing the files; one database engine |
| Transparency log | Sigstore Rekor; Trillian (in maintenance mode) and Tessera; Certificate Transparency (RFC 9162) | A Merkle tree with short proofs of inclusion and append-only growth, watched by independent monitors | Needs a log service and monitors; RFC 9162 warns a log can show clients different views |
| Hash chain with anchors | HostCrust receipts and hc-verify | Anyone with the file sees edits, deletions and reordering; anchors catch tail deletion and re-hashing | No signatures; entries after the last anchor rely on the chain; checks read the whole range |
That last limit matters at scale. Crosby and Wallach report that proving one event is in an 80-million-event log could need an 800 MB trace with a hash chain, against a 3 KB proof with their tree. A receipts export is small and checked whole, so reading every entry costs little. For a large public log, the tree is the better tool.
HostCrust combines two layers. Its app's database role can add and read receipts but not change or delete them, and tests check that. The owner role can rewrite receipts, so it's kept out of the app's environment, and anchors would show any change it made to anchored entries.
Changelog
- 1.0.1, 14 Nov 2026 (UTC), after HostCrust's security review the same day:
- Text from the file is escaped and the verdict printed last; before, a crafted export could use terminal escape sequences to turn
FAILEDintoOK.--jsonis ASCII only. - Malformed input fails cleanly: wrong field types exit 1; a lone surrogate or deep nesting exits 2.
- An
OKwithout--anchor,--heador--againstsays that it wasn't anchored.
- Text from the file is escaped and the verdict printed last; before, a crafted export could use terminal escape sequences to turn
- 1.0.0, 14 Nov 2026 (UTC): first release.
How we checked this: hc-verify 1.0.1 on macOS 14 with Python 3.14.7 on 14 Nov 2026 (UTC), with the tamper checks repeated on Python 3.12.15: the repository's 27 unit tests, the two sample exports in tests/fixtures/ (written by the HostCrust app's own test suite), and the edited, shortened and re-hashed copies made with the commands on this page. Every output block is copied from those runs. Not tested by us: Windows, Python 3.9 to 3.11, and pip install. The comparison with other approaches comes from the vendors' and authors' own documentation, not from tests. Anything we didn't run ourselves comes from the official documentation listed under Sources.
Check which CVEs are really open on your server
HostCrust Patch Proof compares every installed package with your distribution's own security data. It counts fixes your distro backported and checks the kernel that is actually running, not just the one on disk. Read-only, no root, free.
FAQ
Is a hash-chained audit log immutable?
No. A hash chain is tamper-evident, not tamper-proof: anyone who can write to the storage can still change it, but the change shows when the hashes are recomputed. Preventing changes is the storage's job (append-only permissions or WORM storage). You want both, plus a copy of the chain head kept elsewhere.
Does hc-verify upload my receipts anywhere?
No. It reads the file you name and makes no network requests. It's one Python file using only the standard library, so you can read all of it before you run it.
What do hc-verify's exit codes mean?
0: the export is intact. 1: verification failed, with the problems listed above the FAILED line. 2: the file couldn't be read: it's missing, isn't UTF-8 or JSON, or is ambiguous JSON such as a duplicate key.
Can hc-verify prove that a patch was really installed?
No. It proves that log entries weren't changed after they were written. A change's result and verification are reported by the HostCrust agent on the server, which runs as root, so someone with root there could report a patch that never ran. hc-verify shows the report wasn't altered later, not that it was true.
Can I use hc-verify on audit logs from other software?
No. It implements one rule set, hostcrust-chain/1, and refuses exports that name another. The rules are short and written out in the README, so the method is easy to copy, but the tool reads only HostCrust exports.
Sources
- hc-verify README: what it checks, the hostcrust-chain/1 rules, options and limits
- Crosby and Wallach, Efficient Data Structures for Tamper-Evident Logging (USENIX Security 2009)
- Schneier and Kelsey, Secure Audit Logs to Support Computer Forensics (ACM TISSEC, 1999)
- RFC 9162: Certificate Transparency Version 2.0 (append-only Merkle tree logs, monitors, split views)
- Sigstore documentation: Rekor transparency log overview
- Sigstore blog: Rekor v2 GA, a tile-backed transparency log (October 2025)
- Trillian README: verifiable log on a Merkle tree, now in maintenance mode (Tessera recommended for new logs)
- Amazon S3 User Guide: Locking objects with Object Lock (WORM, compliance and governance modes)
- AWS CloudTrail User Guide: Validating CloudTrail log file integrity (signed, chained digest files)
- journalctl(1): --setup-keys, --verify and --interval (Forward Secure Sealing)
- Microsoft Learn: Ledger overview (SQL Server 2022 and Azure SQL)
- PostgreSQL documentation: ALTER TABLE (table ownership, DISABLE TRIGGER)