Verify your audit log

1. Export the log

Download the integrity export and unpack it. It holds events.ndjson (every event, in order, with its hashes), anchor.json (the latest signed checkpoint), manifest.json (what the export contains) and README.txt (these steps in short, and where the tools are published). The tools are deliberately not inside the file: a verifier shipped by the system it checks proves nothing. Keep anchor.json — you can use it to check a later export.

unzip tellus-audit-integrity-<chain>-<time>.zip

2. Check the checkpoint’s signature

This is the step that establishes trust, so it uses nothing from Tellus except the public key. Download the key for the version the checkpoint names, compare its fingerprint with the one listed on this site, and run verify-anchor.sh.

openssl pkey -pubin -in key.pem -outform DER | openssl dgst -sha256

bash verify-anchor.sh anchor.json key.pem

When the signature holds, it ends with:

VERIFIED — this checkpoint was signed by Tellus and has not been altered since.

If it does not, the tool lists the likely causes in order: the wrong key version, a file that changed in transit, and only then a checkpoint that is not authentic.

3. Check the log against the checkpoint

Run verify_audit.py on the zip file. It checks that every event links to the one before it from the start of the chain, that every hash recomputes from its event’s content, and that the chain holds exactly the head the checkpoint signed. Tellus also has a compiled version of the same checks; the two are tested to print exactly the same thing for every file.

python3 verify_audit.py tellus-audit-integrity-<chain>-<time>.zip

A verified export looks like this:

  [PASS] 0 Format
  [ -- ] 1 Signature
         no key given: run again with the key published on the Tellus trust portal, or check the signature yourself with verify-anchor.sh
  [PASS] 2 Linkage
  [PASS] 3 Recomputation
  [PASS] 4 Anchor binding
  [ -- ] 5 Continuity
         nothing to compare with yet: this is the first export of this chain this program has verified

VERIFIED - the events in this export are the history behind the anchor.

When a check fails, the output names the check, the event and what it means. Here one event was altered after export; everything before it still holds:

  [ -- ] 0 Format
         held for the first 56 events; not checked past ingestSeq 57
  [PASS] 1 Signature
  [ -- ] 2 Linkage
         held for the first 56 events; not checked past ingestSeq 57
  [FAIL] 3 Recomputation
         at ingestSeq 57, event 85e848bf-a22b-4201-9d52-3e2f64ff51d9
         eventHash does not recompute from rawEvent: the event's content was changed
  [ -- ] 4 Anchor binding
         not completed: verification stops at the first failure
  [ -- ] 5 Continuity
         not completed: verification stops at the first failure

NOT VERIFIED - recomputation failed.

The strongest form of the check is to bind a new export to a checkpoint you saved yourself, from an earlier export. A checkpoint you already held cannot have been made to fit the new file:

python3 verify_audit.py <export>.zip --anchor anchor-saved-earlier.json

The tools

Both are plain text, so you can read them before you run them. Check the SHA-256 of each file after downloading.

• verify-anchor.sh: step 2 (bash, openssl, jq)verify-anchor.sh

  SHA-256 85acf9248725e7a49415512cd812e0dee3e89d7f4bbcfe740ee6ef8569f1d4ad

• verify_audit.py: step 3 (python3, standard library only)verify_audit.py

  SHA-256 8329906c1654937e2b38842d32f67ae47a487b79cfec09a993301380dd2a4704

• tellus-audit-verify: the same checks as a compiled program, and the reference implementation. It is what step 2 above downloads; its source is the code the audit service verifies with itself.

sha256sum verify_audit.py verify-anchor.sh

Technical specification

For anyone who wants to reimplement the checks. This section is normative: an implementation that follows it reproduces the Tellus hashes byte for byte.

Each event’s hash covers the previous event’s hash and the canonical form of the event. rawEvent is carried as a JSON string: decode it, then canonicalize.

eventHash = SHA-256( prevHash || UTF-8( canonical( rawEvent ) ) )
prevHash(first event) = 32 × 0x00

Canonical form: object keys sorted by UTF-16 code unit, duplicates kept in their order; arrays in order; no whitespace; numbers exactly as written; true, false and null as they are. Strings are escaped as follows:

0x20–0x7E as itself, except  "  &  '  +  <  >  `
" → \u0022   & → \u0026   ' → \u0027   + → \u002B   < → \u003C   > → \u003E   ` → \u0060
\ → \\   and   \b \t \n \f \r
everything else → \uXXXX (upper-case hex); beyond U+FFFF → two escaped UTF-16 surrogates

A checkpoint signs its signedPayload: five fields, each ended by the byte 0x1F. The signature is ECDSA P-256 over SHA-256, DER-encoded.

chainKey 0x1F headEventHash 0x1F headIngestSeq 0x1F eventCount 0x1F yyyy-MM-ddTHH:mm:ss.fffffffZ 0x1F
signature = hex( "vault:vN:" + base64( ECDSA-P256-SHA256-DER( signedPayload ) ) )

Binding: the event at the checkpoint’s ingestSeq must carry the checkpoint’s head hash, and exactly the checkpoint’s event count must lead up to it, that event included.