Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Repository map

The endpoint (pge/)

FileWhat it does
pge/service.pyThe endpoint service: one approved model, at most one answer per question, three release rules (arrival order by default, immediate as in v0, fixed time); replies are the proven output or one fixed error; logs use fixed words only
pge/protocol.pyThe message format: fixed-size binary messages for the approved model, parsed strictly
pge/binding.pyEncodes the question exactly as EZKL does, checks the server’s output values, decodes proven outputs
pge/bundle.pyLoads the model’s files only if each matches its pinned hash
pge/domain.pyThe range of questions the test model can answer, so impossible ones are refused up front
pge/verdict.pyTurns a proof check into ACCEPT, REJECT or ERROR
pge/cli.pyChecks proofs with EZKL’s official command-line tool, under resource limits
pge/proc.pyRuns a program with a deadline, an output cap and resource limits
pge/worker.pyRuns one check in a separate process with a deadline (Python version)

Documents (docs/)

FileWhat it covers
docs/THREAT_MODEL.mdAssets, attackers, trust boundaries, assumptions, attack surface, side channels and their status, the MITRE ATLAS mapping
docs/ATTACKS.mdEvery catalogued scenario, its result and its evidence
docs/SERVICE_SPEC.mdThe endpoint service’s exact behaviour
docs/BINDING_SPEC.mdThe request-binding rules, pitfalls and test vectors
docs/EXPERIMENT_PROTOCOL.mdThe spin repeat’s protocol, written before the data
docs/results/Complete analysis output for registered experiments

Tests and experiments

PathWhat it is
tests/Unit tests, comparisons against EZKL’s own encoding, end-to-end checks, a parser fuzz test, service tests including the leakage encoders, and test_docs.py, which fails when a fact copied between pages drifts from its home
tests/fixtures/Two pinned test models: tiny (4 inputs, 3 outputs, with its input range in domain.json) and multi (two inputs, two outputs)
prover/server.pyThe laptop AI server: honest, or misbehaving in one of several ways, including hiding bits in timing, order or failures
observer/client.pyThe outside observer: sends questions, records each answer and its time, decodes hidden bits
observer/analyze_matrix.pySummarises a release-rule experiment
observer/jitter_test.pyTests whether leftover timing differences follow the server’s hidden bits
observer/estimate.pyEstimates leakage as mutual information (bits per answer), with a null and an interval; --selftest checks it on synthetic channels
observer/order_experiment.pyThe ordering experiment on one machine

Running on the Pi (device/)

FileWhat it does
device/verify_on_pi.sh, device/check_verifier.shCopy the pinned model to the Pi and check accept and reject cases with the real tool, timed
device/pi_scenario.shOne experiment: the endpoint on the Pi, the server and observer on this machine
device/pi_matrix.shEvery release rule against every signalling method
device/verify_cost.pyWhat one check costs on the Pi, and how reliable each memory limit is
device/measure.shSnapshot of the device’s attack surface: packages, services, processes, open ports, file hashes

Other

PathWhat it is
image/Builds the stripped-down v1 system with Buildroot (work in progress)
book/This book (mdBook); the reference pages include the files in docs/
book/diagrams/, book/render-diagrams.shDiagram sources (Mermaid) and the script that renders them to book/src/diagrams/*.svg; mdBook has no Mermaid support, so the SVGs are committed
spike/rust-verifier/Side experiment: EZKL’s checker as a small Rust program
spike/stwo-verifier/Side experiment: a pinned checker for S-two (StarkWare) proofs