StateProof

Version 0.3.0 — proof-carrying post-install Python environment exactness.

StateProof has one security property: it determines whether a selected Python directory matches an approved state. It reports EXACT or NOT_EXACT; it does not classify code as benign or malicious.

Quick start

python -m stateproof.cli capture ./my_env --output approved.px.json
python -m stateproof.cli verify ./my_env --against approved.px.json --evidence evidence.json
python -m stateproof.cli evidence-verify ./my_env --evidence evidence.json --against approved.px.json

Independent Proof of Exact State

A proof is a self-contained, canonical Merkle representation of the captured state. It includes the ordered entry set, a Merkle state_root, inclusion-proof paths, the manifest root, and optionally an Ed25519 signature.

python -m stateproof.cli keygen --private owner.pem --public owner.pub.pem
python -m stateproof.cli prove ./my_env --private owner.pem --output state.proof.json
python -m stateproof.cli proof-verify state.proof.json --public-key owner.pub.pem --require-signature
# PROOF_VALID

PROOF_VALID means that the proof is internally consistent and, when signed, the signature is valid. It does not claim that a different machine's files are still unchanged after the proof was produced. To assert the current machine's files are exact, run verify on that machine; to prove both facts, use verify and a signed proof.

The same flow is available as a library API:

from stateproof import ProofCarryingEnvironment

proof = ProofCarryingEnvironment.create("./my_env", private_path="owner.pem")
assert ProofCarryingEnvironment.verify(proof, "owner.pub.pem", require_signature=True)

Optional manifest signing

python -m stateproof.cli keygen --private owner.pem --public owner.pub.pem
python -m stateproof.cli sign approved.px.json --private owner.pem --output approved.signed.px.json
python -m stateproof.cli verify ./my_env --against approved.signed.px.json --public-key owner.pub.pem --require-signature

Signing is optional and requires cryptography: pip install 'stateproof[signing]'.

Deterministic scope

The snapshot includes regular files, directories, empty directories, and symlinks below the selected root. Symlinks are recorded but never followed. Unsupported special filesystem entries and unstable scans are rejected rather than marked exact. Default cache directories are excluded.

EXACT means byte-for-byte equality for every registered file, with the recorded path, type, size, target, and mode matching. NOT_EXACT means a deterministic mismatch exists.