diff --git a/README.md b/README.md index 755117e..7f49f3b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,31 @@ -# ProbeCrux +
-A Rust workspace audit that emits a signed, replayable receipt alongside its findings. + + + CueCrux arc-loop mark + +

+ + + PROBECRUX + + +### Reproducibility is the product. + +**A Rust workspace audit that emits a signed, replayable receipt alongside its findings.** +Eighteen rules across three tiers, append-only identifiers, and a receipt that pins the +commit, the manifest hash, the advisory snapshot, the pattern set and the toolchain. +Nothing is fetched during a run. Verification is offline. + +[How it works](#how-it-works) · [The receipt](#what-the-receipt-attests) · +[Signing](#signing-whose-receipt-is-it) · [Rule set](#rule-set) · [Docs](#documentation) + +[![ci](https://github.com/CueCrux/ProbeCrux/actions/workflows/ci.yml/badge.svg)](https://github.com/CueCrux/ProbeCrux/actions/workflows/ci.yml) +[![manifest-hash](https://github.com/CueCrux/ProbeCrux/actions/workflows/manifest-hash.yml/badge.svg)](https://github.com/CueCrux/ProbeCrux/actions/workflows/manifest-hash.yml) +[![Licence: Apache-2.0](https://img.shields.io/badge/licence-Apache--2.0-blue)](LICENCE) +![Status: pre-release](https://img.shields.io/badge/status-pre--release-orange) + +
**Status: in development, not released.** The library crates exist and are tested. There is no published binary, no container image on any registry, and no receipt has been @@ -24,6 +49,19 @@ set version, and the toolchain. The rules live in [`probecrux.rules.yaml`](probecrux.rules.yaml). That file is the product; the runner is plumbing. +## How it works + +Every pin is resolved before a single rule runs. A receipt assembled from what a run +happened to use is a description; one assembled from what a run was told to use is a +constraint. The three tiers stay in separate sections all the way to the output, because +a blended total lets an unreproducible finding inherit the credibility of a reproducible +one. + +ProbeCrux pipeline: a repository and optional ref are acquired to a concrete commit SHA, then the manifest hash, advisory snapshot, pattern set, toolchain and build id are pinned before any rule runs; a single scan traversal builds the shared index, rules evaluate as pure functions over it, and findings land in three separate tiers — 15 deterministic, 2 heuristic, 1 advisory — emitted as findings.json, report.md and a signed receipt over an append-only rule manifest + +More detail: [`docs/architecture.md`](docs/architecture.md). + ## Aims **Reproducibility is the product.** Where reproducibility and coverage conflict, @@ -57,6 +95,9 @@ ProbeCrux reports findings for triage. It does not issue assurance. It is not an audit in any regulatory sense, it is not a legal opinion, and a passing run is not evidence that a codebase is safe. +What a ProbeCrux receipt attests — that these rules, at this version, were evaluated against this commit at this time and produced this findings set — set against what it does not attest: that the repository is secure, correct, fit for purpose or free of defects outside the scope of these rules. Two key classes are shown: project, the published key that gives tamper-evidence but names no party, and operator, your own key, which binds the findings to whoever controls it + ## Why a receipt at all Retroactive provenance is not a thing. A report tells you what a tool found; it does @@ -104,11 +145,11 @@ different answer by whoever controls the network, so ours does not fetch. ## Rule set -Seventeen rules across three tiers. +Eighteen rules across three tiers. | Tier | Count | Reproducible | Ships | |---|---|---|---| -| `deterministic` | 14 | Byte-identical on re-run | v1 | +| `deterministic` | 15 | Byte-identical on re-run | v1 | | `heuristic` | 2 | Only with thresholds pinned | v2 | | `advisory` | 1 | No — model-assisted | v2 | diff --git a/docs/Images/readme/CueCrux-Arc-Loop-White.png b/docs/Images/readme/CueCrux-Arc-Loop-White.png new file mode 100644 index 0000000..59fce78 Binary files /dev/null and b/docs/Images/readme/CueCrux-Arc-Loop-White.png differ diff --git a/docs/Images/readme/CueCrux-Arc-Loop.png b/docs/Images/readme/CueCrux-Arc-Loop.png new file mode 100644 index 0000000..4bcf858 Binary files /dev/null and b/docs/Images/readme/CueCrux-Arc-Loop.png differ diff --git a/docs/Images/readme/how-it-works.svg b/docs/Images/readme/how-it-works.svg new file mode 100644 index 0000000..8a9f806 --- /dev/null +++ b/docs/Images/readme/how-it-works.svg @@ -0,0 +1,59 @@ + + + ProbeCrux pins first, then evaluates without mixing tiers + + + + + + + + + + + + PROBECRUX · PIN FIRST · THEN EVALUATE + + no network during evaluation + 18 rules · 3 tiers + + + + + repository + optional ref + acquireshallow clone, resolve toa concrete commit SHA + pinmanifest hash · advisory snapshotpattern set · toolchain · build id + scanone traversal → the shared index:files · items · spans · manifestsresolved dependency graph + + + ── all pins resolved before any rule runs ── + + evaluaterules are pure functions over the index · no I/O + + + + DETERMINISTIC15 rules · byte-identical on re-runships v1 + HEURISTIC2 rules · thresholds must be pinnedreproducible then · v2 + ADVISORY1 rule · model-assisted · v2not reproducible · own section · never merged + + + + + findings.jsondeterministic set + report.mdhuman-readable · tiered sections + receiptsigned · pins everything above + + + + + APPEND-ONLY RULE IDENTITYprobecrux.rules.yaml · blake3 manifest hash over the file with hash_excludes removed▸ deprecated_rules is never emptied + + + silence is never a pass; every rule that did not run says why. + diff --git a/docs/Images/readme/probecrux-dark.svg b/docs/Images/readme/probecrux-dark.svg new file mode 100644 index 0000000..e1c6328 --- /dev/null +++ b/docs/Images/readme/probecrux-dark.svg @@ -0,0 +1,11 @@ + + PROBECRUX wordmark for dark backgrounds + + + + + + + + + diff --git a/docs/Images/readme/probecrux-light.svg b/docs/Images/readme/probecrux-light.svg new file mode 100644 index 0000000..9afdbbf --- /dev/null +++ b/docs/Images/readme/probecrux-light.svg @@ -0,0 +1,11 @@ + + PROBECRUX wordmark for light backgrounds + + + + + + + + + diff --git a/docs/Images/readme/receipt.svg b/docs/Images/readme/receipt.svg new file mode 100644 index 0000000..28643d3 --- /dev/null +++ b/docs/Images/readme/receipt.svg @@ -0,0 +1,34 @@ + + + What a ProbeCrux receipt attests and does not attest + + + + + + + + + + WHAT THE RECEIPT SAYS · AND WHAT IT DOES NOT + verification stays offline + + + ATTESTSThese rules, at this version, were evaluated against thiscommit at this time, and produced this findings set. + DOES NOT ATTESTThat the repository is secure, correct, fit for purpose, orfree of defects outside the scope of these rules. ProbeCruxreports findings for triage. It does not issue assurance. + + + + projectpublic key published in keys/ · verify offlinewith no arrangementtamper-evidence, not attestation of a party + operatoryour own key · never generated and never held by ProbeCruxbinds findings to whoever controls itUSE FOR AN EVIDENCE OBLIGATION + + + if the configured key cannot be loaded, the run fails — there is no code path that invents one. + verification never fetches; the network can be given a different answer. + diff --git a/docs/architecture.md b/docs/architecture.md index bc9e23e..7d04436 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -111,7 +111,7 @@ the format moves. ## v1 scope -Fourteen rules are marked `deterministic`. Not all of them ship in the first release — +Fifteen rules are marked `deterministic`. Not all of them ship in the first release — they differ by an order of magnitude in implementation cost, and the release is bounded by what can be built well rather than by what shares a tier.