Quantum Readiness Copilot

Quantum Readiness Copilot is a local developer-security tool for post-quantum migration planning. It scans a real repository for cryptographic dependencies and unsafe configuration, groups code-level evidence into migration assets, calculates an explainable readiness baseline, and uses ChatGPT-authenticated Codex with GPT-5.6 Sol to turn that evidence into an implementation plan.

Apache-2.0 licensed | Contributing | Security policy

Why this exists

Teams know post-quantum migration matters, but usually lack a file-level inventory of where classical public-key cryptography lives, what should move first, and which changes depend on external protocols or libraries. This project connects that strategic risk to the repository where developers can act on it.

The scanner does not claim to prove runtime reachability or complete cryptographic safety. It provides evidence, confidence boundaries, and a concrete review path.

Core judge path

npm install
npm run interop:setup
npm run verify:judge
npm start

interop:setup installs the pinned Python peer dependencies into the currently selected Python environment. Activate a virtual environment first if you do not want to install them into your default interpreter.

1. Open http://localhost:4173. The bundled fixture is loaded and scanned automatically.
2. Select the hardcoded secret finding in src/auth/keys.ts, then click Analyze to inspect the GPT-5.6 Sol decision and evidence-grounded roadmap.
3. Follow the runtime-evidence guide to capture a bounded local Node test or staging run, then import its JSONL output. The product marks an asset as observed only when the captured path directly correlates with that static asset.
4. Click Generate patch, then Verify impact. The Evidence & guarantees strip distinguishes static discovery, directly correlated runtime evidence, Codex's read-only patch scope, and isolated verification. Codex proposes a reviewable diff; the app applies it only to a temporary copy, rescans it, maps static blast radius, and performs syntax or JSON preflight without modifying the source repository. For a trusted repository, Run repository checks is an explicit follow-up that runs recognized npm validation scripts in that temporary copy only.
5. Open Evaluation to inspect the pinned real-repository benchmark, 12/12 GPT-5.6 quality gates, and checksum-bound judge receipt.

Analyze and Generate patch require an authenticated Codex CLI. A fresh GPT-5.6 Sol run at high reasoning can take several minutes per generation; identical evidence and selected findings reuse the verified cache. The deterministic scan, local verification gates, evaluation artifacts, and exports remain available without a model call.

Evidence package

• Architecture and trust boundaries
• Governed CI, baselines, suppressions, and SARIF
• Static call-site and reachability evidence
• Opt-in Node runtime evidence
• Quantum exposure horizon and Mosca inequality
• Migration dependency graph and rollout waves
• Evidence-bound migration execution ledger
• Cryptographic provenance and interoperability evidence
• Implementation-bound candidate qualification
• Evaluation methodology
• One-command judge verification
• Reproduced benchmark result
• GPT-5.6 report evaluation
• Sample end-to-end run
• Threat model
• Under-three-minute demo script
• Narrated demo package
• 2:31 Deepgram-narrated demo draft

Screenshots

Product workflow

1. Choose a local path, public GitHub URL, or repository ZIP.
2. Import remote sources into an isolated temporary workspace and scan supported files with deterministic rules.
3. Group findings into unique crypto assets by file and rule.
4. Trace supported JavaScript and TypeScript symbols to static repository references and configured package entrypoints.
5. Evaluate repository-owned data lifetime, migration lead time, and quantum threat horizon assumptions with an auditable Mosca inequality.
6. Validate exact NIST parameter sets, pinned provider versions, integration-file digests, runner-bound transcripts, independently bound peer components, and hybrid downgrade resistance from a repository-owned provenance manifest.
7. Explicitly execute a trusted Node adapter and separately versioned Python peer to reproduce bidirectional ML-KEM, ML-DSA, X-Wing draft-10, tamper, and fail-closed negotiation evidence without writing secret material to artifacts or process arguments.
8. Qualify the exact candidate implementation against repository-owned wire-size budgets and record local p95 timing observations in an implementation-bound snapshot.
9. Build an evidence-backed dependency graph across validation, hygiene, agility, candidate proof, qualification, interoperability, and controlled rollout.
10. Record node progress, owner attestations, evidence references, blockers, and decisions in a server-validated hash-chained ledger.
11. Bind verified decisions to automatic node, file, policy, cryptographic-provenance, qualification, repository-reference, and optional patch-impact fingerprints; project drifted attestations as stale without rewriting history.
12. Calculate an explainable readiness score and evaluate the repository-owned policy and baseline.
13. Distinguish new, existing, resolved, suppressed, and expired migration debt.
14. Ask GPT-5.6 to explain the deterministic critical path and produce a strict now/next/later roadmap informed by unresolved execution state.
15. Select a finding and generate a repository-aware, reviewable unified diff through Codex.
16. Apply the proposed diff to an isolated temporary copy, rescan it, map static blast radius, and show the measured before/after impact. For a trusted source only, explicitly run recognized repository checks in that copy.
17. Optionally preload the local Node runtime-evidence agent in a trusted test or staging run, import its safe JSONL output, and distinguish observed paths from static-only assets.
18. Export the evidence, execution ledger, and proposed patch as Markdown or download SARIF 2.1 for CI and security tooling.

The exposure panel also supports server-validated interactive scenarios. A scenario can change X, Y, Z, data class, and owner without editing source or committed policy; it is labeled as interactive-scenario, invalidates the prior GPT report, and can be reset to the repository profile.

Successful GPT-5.6 reports and selected-finding remediation plans are cached by SHA-256 fingerprints of the model, reasoning effort, repository path, prompt version, and analyzed repository content. Identical scans return immediately; code or finding changes invalidate the relevant cache and trigger a fresh Codex audit.

Architecture

• scanner/: deterministic traversal, detection rules, grouping, scoring, static call-site evidence, standards provenance, opt-in transcript reproduction, implementation-bound candidate qualification, quantum exposure horizons, migration dependency graphs, governed policy, baselines, CLI enforcement, and SARIF
• server/execution-ledger.mjs: repository-scoped append-only decision ledger with prerequisite enforcement, evidence freshness projection, and SHA-256 chain verification
• server/codex-cli.mjs: safe process adapter for ChatGPT-authenticated Codex CLI runs
• server/codex-analysis.mjs: GPT-5.6 Sol repository analysis with strict schema output
• server/repository-intake.mjs: validated public GitHub cloning and traversal-safe ZIP extraction
• server/codex-patch.mjs: selected-finding remediation as strict, structured patch output
• server/patch-impact.mjs: guarded temporary-copy patch application, before/after rescan, static blast-radius evidence, and explicit trusted-repository checks
• server/patch-impact-receipt.mjs: short-lived HMAC receipts binding verified impact to the scanned repository
• server/openai.mjs: optional direct Responses API runtime for separately billed deployments
• public/: operational dashboard for evidence, assets, scoring, and plans
• benchmarks/: pinned real-repository corpus, labels, runner, and reproduced results
• fixtures/: deliberately vulnerable repository used for the judge testing path
• tests/: deterministic scanner and scoring assertions

The deterministic scan runs locally. Detected hardcoded-secret values are replaced with <redacted> in deterministic findings before those findings reach model prompts, reports, or dashboard evidence lists. When the user explicitly requests Analyze or Generate patch, Codex processes repository context under the authenticated user's OpenAI account in a read-only sandbox and may inspect the original source, including sensitive content not recognized by the scanner. Generated patch diffs can quote removed source lines, so model actions should be run only on repositories authorized for OpenAI processing. GitHub imports are shallow public clones with Git metadata removed. ZIP intake rejects traversal paths, limits archive and expanded sizes, and extracts into ignored temporary workspaces. The direct Platform API runtime is optional and disabled by default.

Run locally

Requirements: Node.js 20 or newer and Python 3 with the pinned interoperability dependencies.

npm install
npm run interop:setup
npm test
npm run provenance:verify
npm run qualify
npm run scan
npm run readiness -- --help
npm run readiness:ci
npm run verify:judge
npm start

Open http://localhost:4173. The fixture repository is scanned automatically on first load.

Environment

Install the Codex CLI and sign in with ChatGPT:

npm install -g @openai/codex
codex login

Create a .env file in the project root:

ANALYSIS_RUNTIME=codex
CODEX_MODEL=gpt-5.6-sol
CODEX_REASONING_EFFORT=high
CODEX_EXEC_ENABLED=true

The server loads .env automatically on startup. Without an authenticated Codex CLI, the deterministic scan, score, asset inventory, fallback roadmap, Codex-ready prompt, and export path still work.

How GPT-5.6 is used

The app invokes Codex non-interactively with the concrete gpt-5.6-sol model and high reasoning effort. Codex receives the deterministic evidence inventory, inspects the target repository in a read-only sandbox, and reconciles scanner evidence with actual call sites.

Structured Outputs constrain the response to a strict schema containing:

• executive decision and risk level
• readiness score and rationale
• evidence-linked top risks with confidence
• deterministic-graph-constrained rollout decision and blockers
• exact deterministic provenance decision and validated, invalid, and unclaimed claim IDs
• exact qualification status, snapshot state, budget counts, enforcement mode, and qualified or failed claim IDs
• ordered now/next/later migration actions
• assumptions requiring human validation
• a targeted Codex prompt

The deterministic scanner remains the baseline source of observed code facts. Its JavaScript and TypeScript call-site layer distinguishes entrypoint references from unreferenced exports while keeping runtime verification false. Its exposure engine preserves the repository-owned X, Y, and Z inputs, Mosca inequality, and migration start-by year. Its provenance and qualification validators own exact evidence status, snapshot state, enforcement mode, counts, and claim IDs. GPT-5.6 must return those values unchanged. It must also preserve the deterministic migration graph version, source, first wave, and critical path, exclude effectively verified nodes from blockers, and retain blocked or stale critical-path nodes. It then performs contextual prioritization and planning, identifies scanner blind spots, and places unsupported contextual claims in the assumptions list.

How Codex is used

Codex is used throughout implementation, testing, review, and documentation. Inside the product, both the GPT-5.6 readiness decision and the selected-finding remediation use authenticated Codex runs. The server invokes the installed CLI through its Node entrypoint, avoiding shell interpolation, and supplies prompts over stdin.

The equivalent read-only repository inspection is:

codex exec --model gpt-5.6-sol --sandbox read-only --output-schema schemas/quantum-readiness-report.schema.json -

Patch generation also runs read-only. It returns a strict JSON contract containing a summary, affected files, unified diff, validation steps, and review risks. The app never silently edits a judge's repository.

Readiness score

The baseline starts at 100 and deducts once per unique production or configuration file and detection-rule pair:

• critical: 14 points
• high: 9 points
• medium: 4 points
• low: 1 point

The score is a prioritization aid, not a compliance certification. Every deduction is preserved in scan.summary.scoreDeductions so the result is reproducible and auditable.

Test, fixture, documentation, and example matches stay in the evidence inventory but do not reduce readiness. This separation prevents mature repositories with large test-vector suites from receiving a worse score solely because their tests exercise more algorithms.

Governed CI

The CLI turns the same evidence into an enforceable repository contract. .quantum-readiness.json defines the minimum score, blocked severities, new-debt behavior, provenance and qualification enforcement, and auditable suppressions. .quantum-provenance.json binds post-quantum candidates to exact standards, provider versions, implementation files, and test artifacts. .quantum-qualification.json owns required wire-size and optional p95 timing budgets. .quantum-readiness-baseline.json distinguishes new, existing, and genuinely resolved assets. Suppressions require an ID, owner, reason, and optional expiry; they improve the effective policy score but never alter the deterministic evidence score or count as remediation.

node scanner/cli.mjs baseline .
node scanner/cli.mjs qualify . --enforce
node scanner/cli.mjs scan . --enforce
node scanner/cli.mjs scan . --format sarif --output reports/quantum-readiness.sarif --enforce

A policy failure exits with code 2. The same policy can enforce a repository-owned Mosca exposure horizon, runner-bound cryptographic provenance, and peer-implementation bindings without changing the deterministic score. quantum-readiness provenance . is a separate opt-in execution gate and must only be run on trusted code. It requires the exact Python dependencies in fixtures/vulnerable-demo-repo/test/interop/requirements.lock, installed with npm run interop:setup, or a compatible interpreter selected with QRC_INTEROP_PYTHON. SARIF 2.1 carries locations, rule metadata, baseline state, policy status, suppression justification, exposure-horizon evidence, provenance claims, peer bindings, transcript and artifact hashes, rollout-wave metadata, and execution evidence. The web app exposes the same static gate and downloads SARIF locally. See the governed CI guide.

Reproducible evaluation

Run the pinned three-repository benchmark:

npm run benchmark

The current result covers 995 files at exact commits in node-jsonwebtoken, jose, and pyca/cryptography. It detects 19/19 selected expected crypto surfaces, including real ML-DSA and ML-KEM implementations, and 13/13 manually reviewed detections are true positives. It also separates 123 production/config post-quantum readiness references from 310 actionable findings. These are deliberately bounded metrics: they do not claim complete recall or precision over every possible repository. See benchmarks/results/latest.md and docs/EVALUATION.md.

The controlled GPT-5.6 report rubric contains twelve deterministic gates covering provenance fidelity, candidate-qualification fidelity, migration-graph fidelity, execution-ledger fidelity, quantum-horizon fidelity, runtime identity, score fidelity, repository-grounded citations, ordered migration phases, uncertainty coverage, balanced PQ interpretation, and standards/hybrid validation. The current cache-bypassed fixture analysis passes 12/12 gates. Reproduce it with authenticated Codex using npm run evaluate:model, or use npm run evaluate:model:fresh to bypass the analysis cache and prove a live model invocation.

npm run verify:judge reruns the local deterministic and trusted-checkout gates, validates the recorded benchmark and uncached GPT-5.6 evaluation against the current implementation and exact prompt evidence, and writes a SHA-256-bound receipt under reports/. Use npm run verify:judge:fresh only when the benchmark and model evaluation should also be regenerated. See the receipt contract.

Judge testing path

1. Run npm run verify:judge; it reruns the local gates and writes a verification receipt. Use npm run verify:judge:fresh only to regenerate the benchmark and uncached GPT-5.6 evidence too.
2. Start the app with npm start, then open http://localhost:4173.
3. Use Local for the bundled fixture, GitHub for a public repository URL, or ZIP for an archive up to 20 MB.
4. Click Import & scan and inspect the analyzed-file manifest, line-level evidence, grouped asset inventory, Governed CI policy panel, Quantum exposure horizon, Standards provenance, Candidate qualification, Migration dependency map, and Static call-site evidence panel.
5. Select graph nodes to inspect prerequisites, downstream gates, owners, and exit criteria.
6. Record an in-progress or blocked node decision, then inspect the automatic node, file, policy, and repository evidence beside its decision history.
7. Change the horizon inputs, click Apply scenario, verify both the horizon and graph source change to interactive-scenario, then click Use policy to restore the repository profile.
8. Download SARIF and verify the policy status, baseline state, suppression justification, exposure source, provenance claims, runner status, transcript and artifact hashes, rollout waves, critical path, and current execution evidence are present.
9. Click Analyze to run GPT-5.6 Sol through authenticated Codex. The first deep run may take a few minutes; identical later scans use the verified evidence cache.
10. Open Evaluation to inspect the reproduced real-repository benchmark and pinned commits.
11. Select the hardcoded secret finding in src/auth/keys.ts.
12. Follow the runtime-evidence guide, import the resulting local JSONL file, and confirm only direct static-asset matches are marked as observed.
13. Click Generate patch, then Verify impact. The Evidence & guarantees strip keeps static discovery, runtime evidence, Codex scope, and isolated verification in one review surface. The diff is applied only to a temporary copy; the change-safety gate maps static blast radius and performs static preflight. The successful secret-removal patch improves the deterministic baseline by 9 points; use Run repository checks only for a trusted checkout.
14. Click Export and inspect the Markdown policy gate, current fingerprints, captured fingerprints, and patch-impact evidence in reports/.

Current scanner coverage

• RSA key generation and RSA signatures
• ECDSA, ECDH, and common elliptic-curve signals
• JWT signing algorithms such as RS256 and ES256
• legacy MD5 and SHA-1 usage
• legacy TLS settings and disabled certificate verification
• hardcoded secrets and crypto material
• crypto-related dependency inventory
• ML-KEM and Kyber key-encapsulation readiness signals
• ML-DSA, Dilithium, SLH-DSA, and SPHINCS+ signature readiness signals
• explicit classical/post-quantum hybrid constructions
• repository-owned FIPS 203, FIPS 204, and FIPS 205 parameter-set provenance with exact provider-version checks
• SHA-256-bound implementation, known-answer, interoperability, and hybrid downgrade-resistance artifacts
• opt-in bidirectional execution of ML-KEM and ML-DSA across Noble and PQCrypto, plus X-Wing draft-10 across Noble and Cryptography's X25519, tamper, and fail-closed negotiation assertions
• repository-owned required wire-size budgets plus environment-labelled p95 timing observations for exact provenance claims
• implementation-, profile-, count-, status-, and environment-bound qualification snapshots with tamper and drift rejection
• JavaScript and TypeScript symbol, import, entrypoint, and static call-site evidence
• repository-owned Mosca inequality and harvest-now-decrypt-later exposure horizons
• deterministic five-wave migration dependency graph with stable node IDs and exit criteria
• persisted node status, owner attestation, evidence, blocker, and hash-chained decision history
• automatic node, file, policy, cryptographic-provenance, repository-reference, and verified patch-impact evidence snapshots
• non-destructive stale-attestation projection that closes dependent verification gates after evidence drift

Known boundaries

• Static matching can produce false positives. JavaScript and TypeScript reference paths improve prioritization but do not prove runtime execution; dynamic imports, reflection, external consumers, feature flags, and production traffic remain outside the deterministic claim. The published precision metric is limited to the reviewed sample in the benchmark manifest.
• A suppression is an auditable policy exception, not proof that the underlying finding was remediated; suppressed assets never count as resolved.
• Data lifetime, migration lead time, threat horizon, protocol peers, and business criticality remain human-owned assumptions; the tool preserves their owner and never presents the threat year as a prediction.
• The dependency graph sequences repository evidence and technical validation gates; it does not prove organizational ownership, peer support, production interoperability, or actual deployment order.
• A current verified ledger node is an actor attestation whose captured deterministic evidence has not drifted. The SHA-256 chain is tamper-evident local storage, not a digital identity signature or independent proof of runtime behavior or migration completion.
• A passing provenance reproduction establishes bounded cross-runtime interoperability for the exact Node/Python vectors and pinned components tested. It is not NIST CAVP evidence, FIPS 140 module validation, production runtime use, deployed-peer compatibility, universal interoperability, or cryptographic certification. X-Wing draft-10 remains an Internet-Draft, not a final RFC.
• The provenance command intentionally imports repository code and must only be run on a trusted checkout; ordinary scans never execute the target repository. The bundled workflow does not reproduce transcripts for fork pull requests and does not persist checkout credentials.
• The qualification command has the same trusted-checkout boundary. Wire-size checks are required, while fixture timing is advisory; one host snapshot is not production capacity, universal performance, protocol deployment, or FIPS 140 validation.
• The judge receipt is an unkeyed, reproducible local digest rather than a digital signature or independent certification. Its trusted execution gates must not run against untrusted code.
• Codex generation is read-only. Impact verification applies the diff only inside an automatically deleted temporary copy; applying it to the source remains an explicit developer decision.
• The change-safety gate is evidence, not a guarantee. It does not prove runtime behavior or full transitive impact. Repository-native checks require an explicit confirmation, run only for trusted local or CI checkouts in the temporary copy, and are not sandboxed.
• GitHub intake supports public github.com repositories only. Private repository credentials are never accepted.
• ZIP intake is capped at 20 MB compressed, 100 MB expanded, and 10,000 files.

Contributing and license

Contributions are welcome. Read CONTRIBUTING.md before proposing a change, and report suspected vulnerabilities through the process in SECURITY.md.

Quantum Readiness Copilot is licensed under the Apache License 2.0.