Skip to main content
rootsign verify recomputes every hash in a session and tells you whether the records are intact. Run it before you rely on a session in an investigation, after you receive session files from somewhere else, or on a schedule over everything an agent has recorded. This page covers the command, its exit codes, the Python API, and how to wire it into CI.
Verifying a JSONL session file needs only pip install rootsign. Verifying by session ID reads the PostgreSQL store and needs pip install 'rootsign[postgres]' and ROOTSIGN_BACKEND=postgres.

Verify one session

1

Find the session

With the default JSONL backend, each session is a file named after its ID in ~/.rootsign/sessions/, or in $ROOTSIGN_DATA_DIR/sessions/ if you set it. Your code can print the ID from ctx.session_id, as in the quickstart.
2

Run verify

3

Read the exit code

The command exits 0 for VALID. Any other code means the session cannot be trusted as it stands, or could not be checked at all. The next section lists them.

Exit codes

Codes 0 to 2 only ever report a verdict, so a script can act on them without parsing the output.
Exit code 3 was added after RootSign 0.3.1. In 0.3.1 and earlier, an unknown session ID reported VALID with 0 records and exit code 0, and a missing file exited 1.
What each failure looks like:
A session in which no tools ran is not an error. It verifies as VALID with 0 records.

See each record’s hashes

Add --verbose to list every action with the two hashes that link it to the chain:
Each record’s prev_action_hash is the self_hash of the record before it. How it works explains what goes into each hash.

Verify every session in CI or cron

This script verifies every session file in the sessions folder and fails if any of them is not VALID:
verify-all.sh
With one altered session among them, it prints that file’s path and exits 1:

Verify from Python

verify_session_local() checks a JSONL file and returns a VerifyResult. It does not print anything or exit:
check_local.py
For the PostgreSQL store, verify_session() takes a session ID and an async database session:
check_db.py
The Python functions do not report “nothing to verify” separately. For an empty file, verify_session_local() returns TAMPERED, and it raises FileNotFoundError for a missing one. For an unknown session ID, verify_session() returns VALID with 0 records. Check that the session exists before you rely on the result, or use the CLI, which exits 3 in these cases.

What it does not check

Verification proves that the action records present are unaltered and that none are missing from the middle of the chain. It does not detect records deleted from the end of a session, edits to the session open and close events, or changes to authorization_status. How it works explains each limit.

Export an evidence bundle

Turn a verified session into a report someone else can check.

How it works

What each hash covers and how the verdicts are decided.