Skip to content

Documentation

CLI reference

The seven verbs, the detect command and its real flags, raw-file key handling, and the exit-code contract.

Install#

The command-line tool is logflip; the repository and Python package are logflip-closed. It requires Python 3.11 or newer and runs as python -m logflip.

install
python -m pip install -e ".[dev]"

The seven verbs#

The parser registers exactly seven subcommands.

detectRun the full pipeline on one known $MFT record.
scanEnumerate candidate records and run the pipeline on each.
verify-leafRe-verify a signed evidence leaf offline.
verify-dbVerify the HMAC integrity of a signed fingerprint database.
build-dbBuild and sign a fingerprint database from a capture manifest.
keygenGenerate a sealed 32-byte engagement key.
ingest-capturesTurn operator capture bundles into a build-db manifest.

detect and its input modes#

detect runs the full pipeline on one known MFT record. It accepts either a block source, a raw image or a live volume, or a metafile source: pre-extracted $LogFile, $MFT, and optional $UsnJrnl streams. The published one-line synopsis covers image mode; metafile mode adds the stream flags.

image mode
python -m logflip detect --image disk.img \
  --mft-record 5 --output leaf.json --report report.html

The canonical run on this site uses metafile mode against the pre-extracted streams:

metafile mode
python -m logflip detect --logfile-file logfile.bin --mft-file mft.bin -m 24 --mft-slot 44 --usnjrnl-file usnjrnl_j.bin --report report.html
  • -m / --mft-record is the logical record the reverse replay keys on; --mft-slot is its physical slot when a record was relocated.
  • --db and --key-file are optional. When absent, the stub database and the synthetic demo key are used, and the verdict stays provisional at most.
  • --output writes the signed leaf JSON; --report writes the HTML report. Both write only on a successful run.

Keys

Every key is read from a raw 32-byte file via --key-file and must never be passed as a plain argument.

Exit codes#

The exit code is part of the contract, scriptable in a pipeline:

  • 0 clean: no tampering evidence found.
  • 2 finding: a provisional or confirmed verdict. An exit of 2 means a finding was surfaced, not proof of a confirmation, and with the demo key it is always provisional. Anomalies alone never set this code.
  • 1 error: corrupt input, an I/O failure, or a fail-safe stop.