Getting Started¶
This walks you from an empty shell to your first sealed-and-verified evidence chain. It takes a few minutes. Every command below outputs a JSON report to stdout; logs go to stderr.
1. Install¶
Get the binary from your customer area at
account.litatoli.dev. litatoli-x86_64-linux-static
is statically linked and runs on any x86_64 Linux — the one to use when
verifying evidence on a host you do not control.
Check what you downloaded against the SHA256SUMS published beside it, then put
it on your path:
sha256sum -c SHA256SUMS --ignore-missing
chmod +x litatoli-x86_64-linux-static && sudo mv litatoli-x86_64-linux-static /usr/local/bin/litatoli
Verifying a chain someone sent you needs the same binary and nothing else — no key, no account, no network. If you are auditing a chain rather than producing one, ask whoever gave you the chain for the verifier and the checksum; the licence lets them redistribute it.
Building from source (Rust 1.74+), with the source you were licensed:
Verifying a chain needs nothing else — no key, no config, no network. The
optional checks pull in standard Linux tools: git for commit verification,
psql/sqlite3 for database state, curl for the HTTP and Rekor witnesses.
2. Make your keys¶
Sealing needs key material, and this is the only command that creates it:
keygen writes two secrets: an Ed25519 key (the public-key signature a third
party verifies) and a keyed-BLAKE3 MAC key (which chains entries together and
never leaves your trust domain). Nothing is ever auto-generated. The details of
both keys are in Reference — keygen.
3. Seal something that happened¶
The simplest path signs a result you already have. Pipe a JSON result into
attest and append it to a log:
echo '{"command":"make test","exit_code":0,"stdout":"ok","stderr":""}' \
| litatoli attest --log-file evidence.jsonl
evidence.jsonl is now a chain-linked log with one signed entry. Each entry is
keyed-BLAKE3-signed and linked to the previous one.
You can also run a command and seal it in one go:
This captures the exit code, stdout, stderr, elapsed time, a BLAKE3 signature,
and (on Linux) any new outbound TCP connections. Add --watch-dir ./src to also
record a before/after filesystem diff.
4. Commit to everything so far¶
A checkpoint appends a signed entry carrying the Merkle root of every entry
before it. verify-chain validates checkpoints automatically, which catches
in-place tampering below one:
5. Verify it, pinned¶
This is the command an auditor runs. Pin it to your public key so a log signed end to end by someone else's key cannot pass:
Read proves, not overall_ok. overall_ok is true whether you pinned
anything or not. proves names what the pass actually established. The command
also prints the log's head — the last entry's signature. Record it.
6. Verify again with the head pinned¶
Now pass the head back. This is the step that also proves nothing was removed from the end of the log:
litatoli verify-chain --log-file evidence.jsonl \
--expected-pubkey "$(litatoli export-pubkey)" \
--expected-head <the head from step 5>
Step 6 is not optional ceremony. Without --expected-head, entries cut from the
end of a log are undetectable — the full reasoning is in
Reference — the completeness gap.
Try it against broken chains¶
A worked example, with three deliberately broken chains to run the same commands
against, is in first-chain/. Run the verify commands against
them and watch which check each one fails.
Where to next¶
- Reference — every CLI command, the evidence-log format, hypothesis gating (blocking a costly action until prior evidence exists), the Rust API, and the security model.
- Format specification — the on-disk format, precise enough to build an independent verifier with no litatoli code.