quantumsafe-scan 0.1.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- quantumsafe_scan-0.3.0/PKG-INFO +963 -0
- quantumsafe_scan-0.3.0/README.md +931 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/__init__.py +1 -1
- quantumsafe_scan-0.3.0/cli/callgraph.py +306 -0
- quantumsafe_scan-0.3.0/cli/certchain.py +400 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/cli.py +108 -8
- quantumsafe_scan-0.3.0/cli/dependencies.py +486 -0
- quantumsafe_scan-0.3.0/cli/diff.py +171 -0
- quantumsafe_scan-0.3.0/cli/horizon.py +281 -0
- quantumsafe_scan-0.3.0/cli/origins.py +263 -0
- quantumsafe_scan-0.3.0/cli/reachability.py +154 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/recommender.py +29 -0
- quantumsafe_scan-0.3.0/cli/remediation.py +188 -0
- quantumsafe_scan-0.3.0/cli/reporter.py +657 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/scanner.py +328 -13
- quantumsafe_scan-0.3.0/cli/taint.py +200 -0
- quantumsafe_scan-0.3.0/cli/tlsscan.py +425 -0
- quantumsafe_scan-0.3.0/pyproject.toml +56 -0
- quantumsafe_scan-0.3.0/quantumsafe_scan.egg-info/PKG-INFO +963 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/SOURCES.txt +21 -1
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/setup.cfg +4 -4
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_api.py +65 -0
- quantumsafe_scan-0.3.0/tests/test_callgraph.py +71 -0
- quantumsafe_scan-0.3.0/tests/test_certchain.py +423 -0
- quantumsafe_scan-0.3.0/tests/test_conformance.py +176 -0
- quantumsafe_scan-0.3.0/tests/test_cors.py +123 -0
- quantumsafe_scan-0.3.0/tests/test_diff.py +328 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_features.py +28 -0
- quantumsafe_scan-0.3.0/tests/test_horizon.py +348 -0
- quantumsafe_scan-0.3.0/tests/test_origins.py +284 -0
- quantumsafe_scan-0.3.0/tests/test_remediation.py +149 -0
- quantumsafe_scan-0.3.0/tests/test_scanner.py +284 -0
- quantumsafe_scan-0.3.0/tests/test_seeded.py +26 -0
- quantumsafe_scan-0.3.0/tests/test_taint.py +66 -0
- quantumsafe_scan-0.3.0/tests/test_tlsscan.py +436 -0
- quantumsafe_scan-0.1.0/PKG-INFO +0 -569
- quantumsafe_scan-0.1.0/README.md +0 -552
- quantumsafe_scan-0.1.0/cli/reporter.py +0 -343
- quantumsafe_scan-0.1.0/pyproject.toml +0 -37
- quantumsafe_scan-0.1.0/quantumsafe_scan.egg-info/PKG-INFO +0 -569
- quantumsafe_scan-0.1.0/tests/test_conformance.py +0 -92
- quantumsafe_scan-0.1.0/tests/test_scanner.py +0 -144
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/LICENSE +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/scorer.py +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/dependency_links.txt +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/entry_points.txt +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/requires.txt +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/top_level.txt +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_benchmark.py +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_pqc.py +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_quantum.py +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_schema.py +0 -0
- {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_scorer.py +0 -0
|
@@ -0,0 +1,963 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: quantumsafe-scan
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Scan codebases and dependencies for quantum-vulnerable cryptography and generate a NIST-aligned migration plan (SARIF + CycloneDX CBOM).
|
|
5
|
+
Author: QuantumSafe
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Danny-397/Quantum-Safe-Scan
|
|
8
|
+
Project-URL: Repository, https://github.com/Danny-397/Quantum-Safe-Scan
|
|
9
|
+
Project-URL: Issues, https://github.com/Danny-397/Quantum-Safe-Scan/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/Danny-397/Quantum-Safe-Scan/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: quantum,post-quantum,pqc,cryptography,nist,security,kyber,ml-kem,dilithium,ml-dsa,sarif,cbom,cyclonedx,sast,crypto-agility,sbom
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Security :: Cryptography
|
|
25
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.9
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Requires-Dist: rich>=13.0
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<div align="center">
|
|
34
|
+
|
|
35
|
+
<img src="docs/banner.png" alt="QuantumSafe — find the cryptography quantum computers will break" width="840">
|
|
36
|
+
|
|
37
|
+
<p>
|
|
38
|
+
<a href="https://pypi.org/project/quantumsafe-scan/"><img src="https://img.shields.io/pypi/v/quantumsafe-scan?style=flat-square&logo=pypi&logoColor=white&color=5b73e8" alt="PyPI version"></a>
|
|
39
|
+
<img src="https://img.shields.io/pypi/pyversions/quantumsafe-scan?style=flat-square&logo=python&logoColor=white" alt="Python versions">
|
|
40
|
+
<a href="https://github.com/Danny-397/Quantum-Safe-Scan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Danny-397/Quantum-Safe-Scan/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI status"></a>
|
|
41
|
+
<a href="https://github.com/Danny-397/Quantum-Safe-Scan/tags"><img src="https://img.shields.io/github/v/tag/Danny-397/Quantum-Safe-Scan?style=flat-square&logo=github&label=version&color=5b73e8" alt="Latest version"></a>
|
|
42
|
+
<a href="https://github.com/Danny-397/Quantum-Safe-Scan/stargazers"><img src="https://img.shields.io/github/stars/Danny-397/Quantum-Safe-Scan?style=flat-square&logo=github" alt="Stars"></a>
|
|
43
|
+
<img src="https://img.shields.io/github/last-commit/Danny-397/Quantum-Safe-Scan?style=flat-square&color=555" alt="Last commit">
|
|
44
|
+
<img src="https://img.shields.io/github/license/Danny-397/Quantum-Safe-Scan?style=flat-square&color=3fb950" alt="License: MIT">
|
|
45
|
+
<br>
|
|
46
|
+
<img src="https://img.shields.io/badge/tests-545%20passing-3fb950?style=flat-square&logo=pytest&logoColor=white" alt="545 tests passing">
|
|
47
|
+
<img src="https://img.shields.io/badge/benchmark-100%25%20precision-3fb950?style=flat-square" alt="100% precision on benchmark">
|
|
48
|
+
<img src="https://img.shields.io/badge/SARIF%202.1.0-schema--validated-3fb950?style=flat-square" alt="SARIF schema-validated">
|
|
49
|
+
<img src="https://img.shields.io/badge/NIST-FIPS%20203%2F204%2F205-5b73e8?style=flat-square" alt="NIST FIPS 203/204/205">
|
|
50
|
+
<img src="https://img.shields.io/badge/PRs-welcome-5b73e8?style=flat-square" alt="PRs welcome">
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
<strong>Scan your code for the encryption quantum computers will break, score it 0–100, and get the NIST-approved replacement for every finding — free & open source.</strong>
|
|
54
|
+
|
|
55
|
+
<br><br>
|
|
56
|
+
|
|
57
|
+
<a href="https://quantumsafescan.com"><b>Live demo</b></a> ·
|
|
58
|
+
<a href="https://pypi.org/project/quantumsafe-scan/"><b>Install</b></a> ·
|
|
59
|
+
<a href="docs/WHITEPAPER.md"><b>Documentation</b></a> ·
|
|
60
|
+
<a href="#the-three-layers"><b>How it works</b></a> ·
|
|
61
|
+
<a href="https://github.com/Danny-397/Quantum-Safe-Scan/issues"><b>Report a bug</b></a>
|
|
62
|
+
|
|
63
|
+
</div>
|
|
64
|
+
|
|
65
|
+
QuantumSafe scans code across 11 languages for the cryptography that quantum
|
|
66
|
+
computers will break (RSA, ECC, Diffie-Hellman) or weaken (AES-128, SHA-256),
|
|
67
|
+
scores the risk 0–100, and maps every finding to its NIST FIPS 203/204/205
|
|
68
|
+
replacement — backed by a real Qiskit implementation of Shor's and Grover's
|
|
69
|
+
algorithms and a from-scratch lattice (LWE) key-encapsulation mechanism.
|
|
70
|
+
|
|
71
|
+
<p align="center">
|
|
72
|
+
<a href="https://quantumsafescan.com">
|
|
73
|
+
<img src="docs/demo.gif" width="860"
|
|
74
|
+
alt="QuantumSafe scanning pasted code — the Quantum Risk Score climbs to 66/100 and each finding maps to its NIST replacement">
|
|
75
|
+
</a>
|
|
76
|
+
</p>
|
|
77
|
+
|
|
78
|
+
> ⚠️ **Disclaimer.** QuantumSafe is a security-awareness and triage tool. It uses
|
|
79
|
+
> static pattern + AST analysis and is **not** a substitute for a professional
|
|
80
|
+
> cryptographic audit. Findings are heuristic and may include false
|
|
81
|
+
> positives/negatives.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## The three layers
|
|
86
|
+
|
|
87
|
+
QuantumSafe covers the full arc of the post-quantum problem — not just naming it,
|
|
88
|
+
but **executing** the attack, **finding** the vulnerable code, and **running** the
|
|
89
|
+
solution:
|
|
90
|
+
|
|
91
|
+
| Layer | Module | What it does |
|
|
92
|
+
|-------|--------|--------------|
|
|
93
|
+
| **1. Attack** | [`quantum/`](quantum/) | Shor's and Grover's algorithms in **Qiskit**, run on a quantum simulator. At simulator scale Shor factors a small number and reconstructs a toy RSA key — an educational demonstration of *why* RSA/ECC are rated HIGH (not a break of real key sizes). |
|
|
94
|
+
| **2. Detection** | [`cli/`](cli/) | A hybrid **AST + regex** static-analysis engine over 11 languages, with cross-language usage-awareness, **dependency + lockfile scanning**, **reachability ranking**, and **call-site-specific fixes**, that scores risk and produces a NIST-aligned migration plan. **100% precision on the labeled [benchmark](benchmark/)** (18 files) and **100% recall on 50 seeded cases** — see [methodology](benchmark/RESULTS.md). |
|
|
95
|
+
| **3. Fix** | [`pqc/`](pqc/) | A from-scratch **lattice (LWE) key-encapsulation mechanism** — the math behind CRYSTALS-Kyber / ML-KEM — so the recommended fix is runnable and provable. |
|
|
96
|
+
|
|
97
|
+
The detection layer ships through three surfaces that share **one** engine:
|
|
98
|
+
|
|
99
|
+
- A **free CLI** (`pip install quantumsafe-scan`) — scan local dirs or public GitHub
|
|
100
|
+
repos (and their **dependency manifests**); export JSON / HTML / SARIF / CBOM / SVG badge.
|
|
101
|
+
- A **Flask REST API** — powers the dashboard, ingests scans, handles auth.
|
|
102
|
+
- A **dark, terminal-style web dashboard** — scan history, findings, migration
|
|
103
|
+
plans, and exports. **Free, no paywall.**
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Why it matters
|
|
108
|
+
|
|
109
|
+
RSA-2048 and elliptic-curve crypto secure almost everything — HTTPS/TLS,
|
|
110
|
+
certificates, SSH, code signing, VPNs. **Shor's algorithm breaks all of it.** The
|
|
111
|
+
math is settled; only the hardware is missing (RSA-2048 needs millions of
|
|
112
|
+
error-corrected qubits, and today's machines have a few hundred noisy ones).
|
|
113
|
+
|
|
114
|
+
That gap is the reason to act now, not later:
|
|
115
|
+
|
|
116
|
+
- **"Harvest now, decrypt later":** an adversary can record encrypted traffic
|
|
117
|
+
today and decrypt it once the hardware exists. Anything that must stay secret
|
|
118
|
+
for 5–15 years is effectively at risk *now*.
|
|
119
|
+
- **Migration is slow:** swapping cryptography across a large codebase takes years
|
|
120
|
+
— which is why NIST finalized the post-quantum standards (FIPS 203/204/205) in
|
|
121
|
+
2024.
|
|
122
|
+
|
|
123
|
+
QuantumSafe makes that migration tractable: **find** the vulnerable crypto,
|
|
124
|
+
**understand** why it's vulnerable, and **adopt** the quantum-safe replacement.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Architecture
|
|
129
|
+
|
|
130
|
+

|
|
131
|
+
|
|
132
|
+
One shared detection engine (`cli/`) sits behind three surfaces — the CLI, the
|
|
133
|
+
REST API, and the web dashboard — and is flanked by two runnable companions: the
|
|
134
|
+
`quantum/` attack module (which *justifies* the risk ratings) and the `pqc/`
|
|
135
|
+
defense module (which *implements* the recommended fix). Full write-up in
|
|
136
|
+
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md); the diagram is regenerated by
|
|
137
|
+
`python docs/make_architecture.py` (vector source: [docs/architecture.svg](docs/architecture.svg)).
|
|
138
|
+
|
|
139
|
+
## Documentation
|
|
140
|
+
|
|
141
|
+
| Document | What's in it |
|
|
142
|
+
|----------|--------------|
|
|
143
|
+
| [docs/WHITEPAPER.md](docs/WHITEPAPER.md) | Full technical whitepaper: threat model, design, scoring, evaluation, limitations, future work |
|
|
144
|
+
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Components, the CLI→API→Scanner→Risk→Export pipeline, data flow, deployment topology |
|
|
145
|
+
| [docs/architecture_diagram.txt](docs/architecture_diagram.txt) | One-screen ASCII system diagram |
|
|
146
|
+
| [docs/EXAMPLES.md](docs/EXAMPLES.md) | **Real** scan output — terminal table, JSON, SARIF, HTML, badge |
|
|
147
|
+
| [docs/NIST_MAPPING.md](docs/NIST_MAPPING.md) | Every detected family → its NIST PQC replacement, with the reasoning |
|
|
148
|
+
| [docs/CVE_MAPPING.md](docs/CVE_MAPPING.md) | Findings mapped to general vulnerability classes (no invented CVEs) |
|
|
149
|
+
| [benchmark/RESULTS.md](benchmark/RESULTS.md) | Precision/recall/F1, risk distribution, reproducible charts |
|
|
150
|
+
| [TECHNICAL_OVERVIEW.md](TECHNICAL_OVERVIEW.md) | Design decisions, quantum-threat background, honest limitations |
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Key features
|
|
155
|
+
|
|
156
|
+
- **11-language detection** — Python (AST-aware), JavaScript/TypeScript, Java, Go,
|
|
157
|
+
Ruby, C#, PHP, Rust, C/C++, Kotlin, Swift.
|
|
158
|
+
- **Data-flow (taint) analysis** — optional `--taint` pass builds a call graph and
|
|
159
|
+
propagates taint to fixpoint, so it catches quantum-vulnerable crypto reached
|
|
160
|
+
through Python **wrapper functions**, not just direct calls.
|
|
161
|
+
- **0–100 Quantum Risk Score** computed from real findings (never hardcoded), with
|
|
162
|
+
Low/Medium/High/Critical bands.
|
|
163
|
+
- **NIST-aligned migration plan** — each finding mapped to ML-KEM/ML-DSA/SHA-3/
|
|
164
|
+
AES-256 with the relevant FIPS standard and a complexity estimate.
|
|
165
|
+
- **Six export formats** — terminal, JSON, HTML, **SARIF** (GitHub code scanning),
|
|
166
|
+
**CycloneDX CBOM**, and an embeddable **SVG risk badge**. The SARIF output is
|
|
167
|
+
validated against the official OASIS 2.1.0 JSON Schema and the CBOM against the
|
|
168
|
+
CycloneDX 1.6 crypto structure in the test suite, so they interoperate for real.
|
|
169
|
+
- **Real quantum demos** — Shor + Grover in Qiskit, plus circuit resource
|
|
170
|
+
estimates.
|
|
171
|
+
- **Real post-quantum crypto** — an LWE KEM verified over 200+ key exchanges with
|
|
172
|
+
zero failures.
|
|
173
|
+
- **Measured, not asserted** — a labeled benchmark with adversarial decoys, plus an
|
|
174
|
+
empirical study (88% of real repos affected).
|
|
175
|
+
- **Production practice** — one shared engine for CLI + API, **80 automated
|
|
176
|
+
tests**, CI, Docker, a reusable GitHub Action, and multi-service deploy configs.
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## What it detects
|
|
181
|
+
|
|
182
|
+
| Risk | Algorithms |
|
|
183
|
+
|------|------------|
|
|
184
|
+
| **HIGH** — migrate immediately | RSA (any size, incl. RSA-2048/4096), ECDSA / ECDH / ECC, DSA, Diffie-Hellman, MD5, SHA-1 |
|
|
185
|
+
| **MEDIUM** — plan migration | TLS 1.0 / 1.1, 3DES / Triple DES, RC4, RSA key sizes under 2048 |
|
|
186
|
+
| **LOW** — monitor | SHA-256, AES-128, TLS 1.2 |
|
|
187
|
+
|
|
188
|
+
Each finding includes the file, line number, algorithm, risk level, *why* it is
|
|
189
|
+
vulnerable, and a NIST-approved replacement:
|
|
190
|
+
|
|
191
|
+
- RSA/ECC key exchange → **CRYSTALS-Kyber (ML-KEM, FIPS 203)**
|
|
192
|
+
- RSA/ECDSA/DSA signatures → **CRYSTALS-Dilithium (ML-DSA, FIPS 204)** / SPHINCS+ (FIPS 205)
|
|
193
|
+
- Hash functions → **SHA-3** or SHA-256
|
|
194
|
+
- Symmetric encryption → **AES-256**
|
|
195
|
+
|
|
196
|
+
## Quantum Risk Score
|
|
197
|
+
|
|
198
|
+
A 0–100 score computed **from real findings**:
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
score = min(100, 15*HIGH + 5*MEDIUM + 1*LOW)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
| Score | Band | Meaning |
|
|
205
|
+
|-------|------|---------|
|
|
206
|
+
| 0–30 | Low | Good quantum hygiene |
|
|
207
|
+
| 31–60 | Medium | Plan migration |
|
|
208
|
+
| 61–80 | High | Prioritize migration |
|
|
209
|
+
| 81–100 | Critical | Immediate action required |
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Scanning a live website (`--url`)
|
|
214
|
+
|
|
215
|
+
A website's quantum exposure is not in its source code — it is in the TLS
|
|
216
|
+
handshake, and almost all of it sits in two brief public-key steps:
|
|
217
|
+
|
|
218
|
+
- the **key exchange**, which Shor's algorithm breaks to recover the session
|
|
219
|
+
key. This is harvest-now-decrypt-later: traffic recorded today becomes
|
|
220
|
+
readable when a quantum computer exists, so it is *retroactive* and cannot be
|
|
221
|
+
fixed afterwards.
|
|
222
|
+
- the **certificate signature**, which Shor also breaks — but only to forge
|
|
223
|
+
*future* certificates, and those rotate every ~90 days anyway.
|
|
224
|
+
|
|
225
|
+
Symmetric cryptography is not the problem: Grover's algorithm square-roots a
|
|
226
|
+
brute-force search, so AES-128 drops to ~2⁶⁴ work and AES-256 is comfortable.
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
quantumsafe scan --url github.com
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
TLS handshake github.com:443 (140.82.112.4)
|
|
234
|
+
Key exchange : X25519 (classical)
|
|
235
|
+
Protocol : TLSv1.3
|
|
236
|
+
Cipher : TLS_AES_128_GCM_SHA256 (128-bit symmetric)
|
|
237
|
+
Certificate : github.com issued by Sectigo Limited, expires Nov 29 2026
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
| Host | Key exchange | |
|
|
241
|
+
|---|---|---|
|
|
242
|
+
| `cloudflare.com` | `X25519MLKEM768` | post-quantum |
|
|
243
|
+
| `google.com` | `X25519MLKEM768` | post-quantum |
|
|
244
|
+
| `github.com` | `X25519` | classical |
|
|
245
|
+
|
|
246
|
+
**Why this needs a hand-built ClientHello.** In TLS 1.2 the cipher suite named
|
|
247
|
+
the key exchange (`ECDHE_RSA_WITH_AES_128_GCM_SHA256`). TLS 1.3 removed it —
|
|
248
|
+
every modern site reports only `TLS_AES_128_GCM_SHA256`, which says nothing
|
|
249
|
+
about key exchange. The group lives in the `key_share` extension, and Python's
|
|
250
|
+
`ssl` cannot read it: `SSLContext.set_groups` and `SSLObject.group_used` need
|
|
251
|
+
OpenSSL 3.5+ and Python 3.14, and ML-KEM groups need OpenSSL 3.5 at all. On
|
|
252
|
+
OpenSSL 3.0 the most important fact about the connection is invisible.
|
|
253
|
+
|
|
254
|
+
So the scanner speaks the handshake directly: it offers the hybrid groups in
|
|
255
|
+
`supported_groups` but a `key_share` for X25519 only. A server preferring a
|
|
256
|
+
hybrid must then reply with a HelloRetryRequest naming it (RFC 8446 §4.1.3).
|
|
257
|
+
The server states its choice, and no ML-KEM implementation is needed to ask.
|
|
258
|
+
No new dependencies.
|
|
259
|
+
|
|
260
|
+
**What it measures.** The group the server *selects from what we offer* — the
|
|
261
|
+
same answer a browser offering that set would get. Not proof of everything the
|
|
262
|
+
server could support, which is why findings say "negotiated", not "supports".
|
|
263
|
+
|
|
264
|
+
### The whole certificate chain, not just the leaf
|
|
265
|
+
|
|
266
|
+
A chain is only as strong as its weakest signature, and the weak link is
|
|
267
|
+
usually not the server certificate. Real output:
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
Certificate chain (a chain is only as strong as its weakest signature)
|
|
271
|
+
leaf sig=ECDSA with SHA-256 key=EC P-256
|
|
272
|
+
intermediate sig=ECDSA with SHA-384 key=EC P-256
|
|
273
|
+
intermediate sig=SHA-256 with RSA key=EC P-384
|
|
274
|
+
root sig=SHA-1 with RSA key=RSA-2048 (trust-store anchored)
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Cloudflare's leaf is modern ECDSA — but an intermediate above it is signed
|
|
278
|
+
**SHA-256 with RSA**. Forging that signature mints a leaf for any name under
|
|
279
|
+
it, and a checker that reads only the server certificate reports "ECDSA,
|
|
280
|
+
modern" and never sees it.
|
|
281
|
+
|
|
282
|
+
Two deliberate distinctions:
|
|
283
|
+
|
|
284
|
+
- **Certificate signatures are a forgery risk, not a retroactive one.** Shor
|
|
285
|
+
breaks them, but that forges *future* certificates — it does not decrypt
|
|
286
|
+
traffic already recorded, and certificates rotate every ~90 days, so this
|
|
287
|
+
largely follows the CA ecosystem's own migration. The key exchange above is
|
|
288
|
+
the urgent one. The findings say so rather than implying equal urgency.
|
|
289
|
+
- **A root's own signature is not a finding.** A root is trusted because it is
|
|
290
|
+
in the client's trust store, not because of its self-signature, so forging
|
|
291
|
+
that signature gains an attacker nothing. Roots are shown for completeness
|
|
292
|
+
and excluded from the score — otherwise every chain carries an unactionable
|
|
293
|
+
HIGH, as the SHA-1 root above would.
|
|
294
|
+
|
|
295
|
+
The signature algorithm and public key are the only two certificate fields
|
|
296
|
+
that matter here, and they are the two `ssl.getpeercert()` does not return.
|
|
297
|
+
Rather than take on `cryptography` as a runtime dependency, the handful of
|
|
298
|
+
fields needed are walked out of the DER directly — a minimal tag-length-value
|
|
299
|
+
reader that parses structure and OIDs and verifies nothing, since `ssl` has
|
|
300
|
+
already validated the chain by the time it arrives.
|
|
301
|
+
|
|
302
|
+
### The origins a page actually depends on (`--origins`)
|
|
303
|
+
|
|
304
|
+
A site can negotiate a hybrid on its own domain and still pull scripts, fonts
|
|
305
|
+
and analytics from a dozen other origins over classical key exchange — and the
|
|
306
|
+
author chose every one of them.
|
|
307
|
+
|
|
308
|
+
```bash
|
|
309
|
+
quantumsafe scan --url github.com --origins
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
```
|
|
313
|
+
Third-party origins 2 post-quantum, 3 classical of 5 scanned
|
|
314
|
+
github.githubassets.com X25519
|
|
315
|
+
avatars.githubusercontent.com X25519
|
|
316
|
+
github-cloud.s3.amazonaws.com X25519MLKEM768
|
|
317
|
+
user-images.githubusercontent.com X25519
|
|
318
|
+
images.ctfassets.net X25519MLKEM768
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
One aggregate finding, not one per origin — a dozen separate HIGHs for other
|
|
322
|
+
people's servers would bury the findings you can act on. It is MEDIUM rather
|
|
323
|
+
than HIGH when your own key exchange is fine, because a third-party server is
|
|
324
|
+
not yours to fix: the action is to drop the dependency or press the vendor.
|
|
325
|
+
|
|
326
|
+
**A page is attacker-controlled input**, so the SSRF guard runs on every
|
|
327
|
+
*discovered* origin, not once on the entry URL. Anyone can publish markup whose
|
|
328
|
+
script tags point at `169.254.169.254`, and a sweep that followed what it found
|
|
329
|
+
would be an SSRF with extra steps. The page read, the origin count and each
|
|
330
|
+
handshake are all bounded.
|
|
331
|
+
|
|
332
|
+
**Scanning someone else's server.** This is exactly one TLS handshake, which is
|
|
333
|
+
what a browser does on every visit: passive and non-intrusive. It is not port
|
|
334
|
+
scanning or vulnerability probing, and stays that way deliberately. The target
|
|
335
|
+
must resolve *entirely* to public addresses on port 443/8443, and the
|
|
336
|
+
connection goes to the address that was checked — private ranges, loopback,
|
|
337
|
+
link-local (including cloud metadata at `169.254.169.254`), carrier-grade NAT
|
|
338
|
+
and IPv4-mapped IPv6 forms of all of those are refused.
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Scan diffing: a ratchet for CI
|
|
343
|
+
|
|
344
|
+
A single scan is a snapshot, and a snapshot is a poor gate. A repository with
|
|
345
|
+
forty known findings cannot adopt `--fail-on-high` without failing every build
|
|
346
|
+
from day one — so in practice the check gets removed and nothing is enforced.
|
|
347
|
+
What a team *can* adopt is a ratchet: tolerate the backlog, fail only when it
|
|
348
|
+
grows.
|
|
349
|
+
|
|
350
|
+
```bash
|
|
351
|
+
quantumsafe scan --path . --output baseline.json # once, committed
|
|
352
|
+
quantumsafe scan --path . --baseline baseline.json --fail-on-new
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
```
|
|
356
|
+
Since baseline REGRESSED
|
|
357
|
+
0 fixed 2 new 19 unchanged score 100 -> 100 (+0)
|
|
358
|
+
NEW newly_added.py:1 DSA [HIGH]
|
|
359
|
+
NEW newly_added.py:2 DSA [HIGH]
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
| | exit code |
|
|
363
|
+
|---|---|
|
|
364
|
+
| regression, `--fail-on-new` | **1** |
|
|
365
|
+
| no regression, `--fail-on-new` | **0** — the 19-finding backlog is tolerated |
|
|
366
|
+
| same scan, `--fail-on-high` | **1** — fails on the backlog |
|
|
367
|
+
|
|
368
|
+
Note `score 100 -> 100 (+0)` above. The risk score caps at 100, so a codebase
|
|
369
|
+
already at the cap can acquire new HIGH findings with the number unmoved. The
|
|
370
|
+
verdict is therefore driven by new findings, never by the score delta — a
|
|
371
|
+
score-driven gate would have waved that DSA file straight through.
|
|
372
|
+
|
|
373
|
+
**Findings are identified without their line number.** Line numbers move when
|
|
374
|
+
an import is added or a file is reformatted, and keying on them turns a no-op
|
|
375
|
+
edit into one "fixed" plus one "new". A diff that cries wolf gets ignored,
|
|
376
|
+
which is worse than no diff. Identity is `(file_path, family, algorithm)`, and
|
|
377
|
+
because several findings of one kind can share a key, counts are tracked per
|
|
378
|
+
key: three RSA call sites in a file becoming five is two new findings.
|
|
379
|
+
|
|
380
|
+
**What a diff cannot tell you**, and says so in its output: a finding that is
|
|
381
|
+
gone was not necessarily fixed — the file may have been deleted, excluded or
|
|
382
|
+
renamed, and a rename appears as one fixed plus one new.
|
|
383
|
+
|
|
384
|
+
Two saved scans can also be compared through the dashboard:
|
|
385
|
+
|
|
386
|
+
```http
|
|
387
|
+
GET /api/v1/scans/{id}/diff?against={other_id} (JWT)
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Both scans are looked up scoped to the caller, so one account cannot diff
|
|
391
|
+
against another's history; omit `against` to compare with the previous scan.
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
## Migration horizon (Mosca's inequality)
|
|
396
|
+
|
|
397
|
+
The risk score says *how much* vulnerable cryptography you have. It cannot say
|
|
398
|
+
whether you will finish migrating in time, which is the question the threat
|
|
399
|
+
model actually poses. One RSA key exchange protecting data that must stay
|
|
400
|
+
secret for fifty years is worse than forty MD5 checksums.
|
|
401
|
+
|
|
402
|
+
Michele Mosca's formulation:
|
|
403
|
+
|
|
404
|
+
```
|
|
405
|
+
X how long the data must stay confidential
|
|
406
|
+
Y how long the migration takes
|
|
407
|
+
Z how long until a quantum computer can break it
|
|
408
|
+
|
|
409
|
+
X + Y > Z -> data sent today is already exposed
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
The reason is harvest-now-decrypt-later: an adversary records ciphertext today
|
|
413
|
+
and decrypts it when Z arrives. Migration has to *finish* by `Z - X`, not at Z.
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
quantumsafe scan --path . --secrecy-years 10 --crqc-years 12
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
```
|
|
420
|
+
Migration horizon (Mosca's inequality)
|
|
421
|
+
Data must stay confidential (X) : 10 years
|
|
422
|
+
Estimated migration (Y) : 2.77-8.66 years
|
|
423
|
+
Assumed quantum threat (Z) : 12 years
|
|
424
|
+
Break-even year : 2038-2044
|
|
425
|
+
ALREADY LATE Already too late: even on the optimistic estimate, data sent
|
|
426
|
+
today that must stay confidential for this long will still be sensitive when
|
|
427
|
+
the migration finishes.
|
|
428
|
+
Design changes needed : dsa, ecc, rsa
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
**What this will not claim.** Z is unknowable, so there is no default for it —
|
|
432
|
+
`--crqc-years` is yours to choose, and omitting it gives no verdict rather than
|
|
433
|
+
a guess. What is always computed is the **break-even year**: the latest a
|
|
434
|
+
quantum computer could arrive while still leaving time to migrate. That is a
|
|
435
|
+
property of your code and your data, not a forecast.
|
|
436
|
+
|
|
437
|
+
Y is an engineering estimate, so it is reported as a range, counted per
|
|
438
|
+
cryptographic *family* rather than per call site (five hundred RSA call sites
|
|
439
|
+
are not five hundred migrations), and every coefficient is printed in the JSON
|
|
440
|
+
report under `horizon.assumptions` so you can disagree with a specific number
|
|
441
|
+
rather than with the whole figure. Replace them with measurements from your own
|
|
442
|
+
migration if you have them — that is strictly better.
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
## Evaluation (does the detector actually work?)
|
|
447
|
+
|
|
448
|
+
The scanner is measured against a labeled [benchmark](benchmark/) of 18 files
|
|
449
|
+
across 9 languages, including adversarial decoys (crypto names in comments,
|
|
450
|
+
docstrings, log strings, trailing/block comments, and word-boundary traps like
|
|
451
|
+
`md5sumLabel`) designed to trip a naive matcher. `evaluate.py` runs the scanner
|
|
452
|
+
twice — a naive line-regex baseline vs. the usage-aware engine — so the
|
|
453
|
+
improvement is measured:
|
|
454
|
+
|
|
455
|
+
```bash
|
|
456
|
+
python benchmark/evaluate.py
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
| Configuration | FP | Precision | Recall | F1 |
|
|
460
|
+
|---|--:|--:|--:|--:|
|
|
461
|
+
| Naive line-regex baseline | 27 | 49.1% | 100% | 65.8% |
|
|
462
|
+
| **QuantumSafe (usage-aware)** | **0** | **100%** | **100%** | **100%** |
|
|
463
|
+
|
|
464
|
+
Usage-awareness removes 27 false positives (crypto keywords inside comments,
|
|
465
|
+
docstrings, and log/exception strings) without losing a true positive — and now
|
|
466
|
+
across **all** supported languages, not just Python: genuine string-argument
|
|
467
|
+
usages such as Java's `getInstance("SHA-1")` are preserved by a dedicated
|
|
468
|
+
recovery pass. `evaluate.py` prints the exact false
|
|
469
|
+
positives/negatives so the numbers are auditable, and the thresholds are enforced
|
|
470
|
+
by `tests/test_benchmark.py`.
|
|
471
|
+
|
|
472
|
+
**Recall is measured too.** Because a small labeled corpus can't prove recall,
|
|
473
|
+
`benchmark/seeded.py` runs a **mutation benchmark** with ground truth by
|
|
474
|
+
construction — 50 real quantum-vulnerable API calls (many idiomatic variants
|
|
475
|
+
per family, 7 languages) that must be detected, plus 50 comment/string decoys
|
|
476
|
+
that must not be. Latest run: **100% recall, 100% mutation precision**
|
|
477
|
+
([RESULTS-seeded.md](benchmark/RESULTS-seeded.md)), enforced by
|
|
478
|
+
`tests/test_seeded.py`. Honest limits are documented in
|
|
479
|
+
[benchmark/README.md](benchmark/README.md) — these are regression benchmarks, not
|
|
480
|
+
a claim of perfection on arbitrary code.
|
|
481
|
+
|
|
482
|
+
These charts are generated from **live scanner output** by
|
|
483
|
+
`python benchmark/graphs/generate_graphs.py` (not hardcoded):
|
|
484
|
+
|
|
485
|
+
| Vulnerabilities by family | Severity split | Scan time vs. files |
|
|
486
|
+
|---|---|---|
|
|
487
|
+
|  |  |  |
|
|
488
|
+
|
|
489
|
+
**See real scan output** — terminal table, JSON, SARIF, HTML, and an SVG risk
|
|
490
|
+
badge from an actual scan — in [docs/EXAMPLES.md](docs/EXAMPLES.md).
|
|
491
|
+
|
|
492
|
+
### Real-world scan: paramiko (the SSH library)
|
|
493
|
+
|
|
494
|
+
Run against a shallow clone of [`paramiko/paramiko`](https://github.com/paramiko/paramiko)
|
|
495
|
+
— the SSH implementation behind Ansible, Fabric, and much of the Python ecosystem.
|
|
496
|
+
SSH key exchange leans on RSA, ECDSA, and Diffie-Hellman, all broken by Shor's
|
|
497
|
+
algorithm, which makes it a textbook "harvest now, decrypt later" target:
|
|
498
|
+
|
|
499
|
+
```bash
|
|
500
|
+
quantumsafe scan --repo https://github.com/paramiko/paramiko
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
| Metric | Result |
|
|
504
|
+
|---|---|
|
|
505
|
+
| Quantum Risk Score | **100 / 100 (Critical)** |
|
|
506
|
+
| Findings (usage-aware) | **110** — 89 HIGH, 6 MEDIUM, 15 LOW |
|
|
507
|
+
| Top algorithms | ECDSA ×23, ECC ×21, SHA-1 ×18, RSA ×15, MD5 ×10, 3DES ×6 |
|
|
508
|
+
| Most-affected files | `paramiko/pkey.py`, `rsakey.py`, `transport.py`, `ecdsakey.py` |
|
|
509
|
+
|
|
510
|
+
The usage-aware engine matters here: a naive line-regex reports **451 raw
|
|
511
|
+
matches**, but most are the same algorithms repeated in docstrings, comments, and
|
|
512
|
+
SSH protocol-name strings (`"ssh-rsa"`, `"ecdsa-sha2-nistp256"`). Focusing on real
|
|
513
|
+
code brings that to **110** findings — a ~4× noise reduction. *Honest caveat: on a
|
|
514
|
+
protocol library, a few of those suppressed string constants are arguably real
|
|
515
|
+
signals, so 110 is a deliberately conservative, code-focused count — not a claim
|
|
516
|
+
that the other 341 were all false positives.*
|
|
517
|
+
|
|
518
|
+
### Real-world benchmark — 37 of the most-downloaded PyPI packages
|
|
519
|
+
|
|
520
|
+
`benchmark/realworld.py` scales the paramiko example up: it pulls the latest
|
|
521
|
+
sdist of 37 widely-used packages straight from the PyPI JSON API, extracts each
|
|
522
|
+
(nothing is built or executed), and runs the real scanner. Fully reproducible:
|
|
523
|
+
|
|
524
|
+
```bash
|
|
525
|
+
python benchmark/realworld.py
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
| Metric | Result |
|
|
529
|
+
|---|---|
|
|
530
|
+
| Packages scanned | **37** |
|
|
531
|
+
| Packages with ≥1 finding | **32 (86%)** |
|
|
532
|
+
| Python files analyzed | **10,938** |
|
|
533
|
+
| Total findings | **5,512** — **4,083 HIGH-risk** |
|
|
534
|
+
| Most common families | `ecc` ×1,709, `sha256` ×956, `rsa` ×770, `sha1` ×576, `dsa` ×355, `md5` ×351 |
|
|
535
|
+
|
|
536
|
+
Every finding is a concrete `file:line` an auditor can open — e.g. Diffie-Hellman
|
|
537
|
+
in `twisted/conch/ssh/transport.py`, MD5 in `requests/auth.py` (HTTP Digest), and
|
|
538
|
+
ECDSA throughout `paramiko`. Full per-package table and examples:
|
|
539
|
+
[benchmark/RESULTS-realworld.md](benchmark/RESULTS-realworld.md).
|
|
540
|
+
|
|
541
|
+
| Findings by family (colored by risk tier) | Packages with the most HIGH-risk findings |
|
|
542
|
+
|---|---|
|
|
543
|
+
|  |  |
|
|
544
|
+
|
|
545
|
+
_Charts are generated from `benchmark/realworld.json` by
|
|
546
|
+
`python benchmark/graphs/generate_realworld_graphs.py` — not hand-drawn._
|
|
547
|
+
|
|
548
|
+
> *Honest caveat: some of these packages **are** cryptography libraries
|
|
549
|
+
> (`cryptography`, `pycryptodome`, `ecdsa`, `rsa`, `pyopenssl`), so their large
|
|
550
|
+
> counts are expected — they implement RSA/ECC on purpose. The more telling signal
|
|
551
|
+
> is the *application* and *infrastructure* code that still reaches for
|
|
552
|
+
> quantum-vulnerable primitives: `django`, `botocore`, `pymongo`, `scrapy`,
|
|
553
|
+
> `celery`, `requests`, `aiohttp`. That's exactly the "harvest now, decrypt later"
|
|
554
|
+
> surface the tool is built to inventory.*
|
|
555
|
+
|
|
556
|
+
### Empirical study — how widespread is the problem?
|
|
557
|
+
|
|
558
|
+
Scanning 8 widely-used open-source projects ([`study/`](study/), reproducible via
|
|
559
|
+
`python study/run_study.py`):
|
|
560
|
+
|
|
561
|
+
- **88%** contained at least one **HIGH-risk** (Shor-breakable) cryptographic usage.
|
|
562
|
+
- Average Quantum Risk Score: **61.4 / 100**.
|
|
563
|
+
|
|
564
|
+
Full results and caveats: [study/REPORT.md](study/REPORT.md).
|
|
565
|
+
|
|
566
|
+
---
|
|
567
|
+
|
|
568
|
+
## Quantum demonstrations (Shor & Grover)
|
|
569
|
+
|
|
570
|
+
```bash
|
|
571
|
+
pip install -r quantum/requirements.txt
|
|
572
|
+
python quantum/shor.py # quantum order-finding factors N=15, then breaks a toy RSA key
|
|
573
|
+
python quantum/grover.py # recovers a hidden k-bit key in ~sqrt(2^k) steps
|
|
574
|
+
python quantum/resources.py # qubit count, circuit depth, gate counts vs. RSA-2048 estimates
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
- **`shor.py`** uses quantum phase estimation over modular exponentiation to find
|
|
578
|
+
the order of `a mod N`, factors `N`, and reconstructs an RSA private key — the
|
|
579
|
+
concrete reason RSA/ECC are rated **HIGH**.
|
|
580
|
+
- **`grover.py`** uses amplitude amplification to search a key space in ~√N
|
|
581
|
+
queries, halving effective key strength — the reason AES-128/SHA-256 are **LOW**.
|
|
582
|
+
|
|
583
|
+
Honest scope: these run at small scale (factoring 15), the genuine state of the art
|
|
584
|
+
for end-to-end Shor. See [quantum/README.md](quantum/README.md).
|
|
585
|
+
|
|
586
|
+
## Post-quantum solution ([`pqc/`](pqc/))
|
|
587
|
+
|
|
588
|
+
```bash
|
|
589
|
+
pip install -r pqc/requirements.txt
|
|
590
|
+
python pqc/lwe_kem.py # Alice & Bob agree on a shared secret; an eavesdropper can't
|
|
591
|
+
python pqc/benchmark.py # measured latency + key/ciphertext sizes vs RSA & ML-KEM
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
Why a quantum computer can't break it: LWE has **no periodic structure** for Shor
|
|
595
|
+
to exploit. See [pqc/README.md](pqc/README.md).
|
|
596
|
+
|
|
597
|
+
---
|
|
598
|
+
|
|
599
|
+
## CLI: install & usage
|
|
600
|
+
|
|
601
|
+
```bash
|
|
602
|
+
pip install quantumsafe-scan # from PyPI once published
|
|
603
|
+
# or, from this repo:
|
|
604
|
+
pip install -e .
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
### Commands
|
|
608
|
+
|
|
609
|
+
```bash
|
|
610
|
+
# Scan a local directory (colored terminal table)
|
|
611
|
+
quantumsafe scan --path ./myproject
|
|
612
|
+
|
|
613
|
+
# Scan a public GitHub repo (shallow-cloned to a temp dir, then cleaned up)
|
|
614
|
+
quantumsafe scan --repo https://github.com/org/app
|
|
615
|
+
|
|
616
|
+
# Write a report: JSON, HTML, SARIF, CycloneDX CBOM, or an SVG risk badge
|
|
617
|
+
quantumsafe scan --path ./myproject --output report.json
|
|
618
|
+
quantumsafe scan --path ./myproject --output report.html
|
|
619
|
+
quantumsafe scan --path ./myproject --output report.sarif # GitHub code scanning
|
|
620
|
+
quantumsafe scan --path ./myproject --output report.cbom.json # CycloneDX CBOM
|
|
621
|
+
quantumsafe scan --path ./myproject --output badge.svg # embeddable risk badge
|
|
622
|
+
|
|
623
|
+
# Also flag crypto reached through Python wrapper functions (data-flow analysis)
|
|
624
|
+
quantumsafe scan --path ./myproject --taint
|
|
625
|
+
|
|
626
|
+
# Skip paths with glob patterns (repeatable)
|
|
627
|
+
quantumsafe scan --path . --exclude 'tests/*' --exclude 'vendor/*'
|
|
628
|
+
|
|
629
|
+
# Fail the process (exit 1) if any HIGH finding exists — handy in CI
|
|
630
|
+
quantumsafe scan --path . --fail-on-high
|
|
631
|
+
|
|
632
|
+
# Try it on the bundled examples
|
|
633
|
+
quantumsafe scan --path examples
|
|
634
|
+
|
|
635
|
+
# Link the CLI to your dashboard, then scans auto-upload to your history
|
|
636
|
+
quantumsafe auth --key qs_live_xxxxxxxx --api-url https://quantumsafe-api.onrender.com
|
|
637
|
+
quantumsafe scan --path ./myproject # prints results AND syncs to dashboard
|
|
638
|
+
quantumsafe scan --path ./myproject --no-sync # local only, don't upload
|
|
639
|
+
|
|
640
|
+
# Version
|
|
641
|
+
quantumsafe version
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
| Flag | Description |
|
|
645
|
+
|------|-------------|
|
|
646
|
+
| `--path` | Local directory or file to scan |
|
|
647
|
+
| `--repo` | Public `https://github.com/<org>/<repo>` URL |
|
|
648
|
+
| `--url` | Live HTTPS host — scans the TLS handshake and certificate chain |
|
|
649
|
+
| `--origins` | With `--url`, also scan every third-party origin the page loads from |
|
|
650
|
+
| `--output` | Write to `.json`, `.cbom.json` (CycloneDX CBOM), `.html`, `.sarif`, or `.svg` (risk badge); terminal summary still printed |
|
|
651
|
+
| `--exclude` | Glob of paths to skip (repeatable) |
|
|
652
|
+
| `--taint` | Also run interprocedural data-flow analysis (Python): flag quantum-vulnerable crypto reached through wrapper functions, **across files** (whole-program call graph with import resolution), not just direct calls |
|
|
653
|
+
| `--no-deps` | Skip dependency scanning (on by default): parses manifests **and lockfiles** (`requirements.txt`, `pyproject.toml`, `package.json`, `go.mod`, `pom.xml`, `Gemfile`, `package-lock.json`, `poetry.lock`, `Pipfile.lock`, `Gemfile.lock`, `yarn.lock`, `go.sum`) and flags known quantum-vulnerable crypto libraries (with purl + direct/transitive scope) in the CBOM |
|
|
654
|
+
| `--no-rank` | Skip reachability ranking (on by default): labels each source finding `reachable` / `test-example` / `unreferenced` so exploitable findings sort above dead or example code |
|
|
655
|
+
| `--fail-on-high` | Exit non-zero on any HIGH finding (CI gate) |
|
|
656
|
+
| `--baseline` | Compare against a saved JSON report: fixed / new / unchanged |
|
|
657
|
+
| `--fail-on-new` | With `--baseline`, exit non-zero only on NEW findings (the ratchet) |
|
|
658
|
+
| `--secrecy-years` | How long the data must stay confidential — enables the migration horizon |
|
|
659
|
+
| `--crqc-years` | The quantum-threat year you want to reason about (no default: nobody knows it) |
|
|
660
|
+
| `--no-sync` | Don't upload the result to your linked dashboard |
|
|
661
|
+
|
|
662
|
+
After `quantumsafe auth --key <key> --api-url <your-api>`, every `quantumsafe scan`
|
|
663
|
+
also uploads its report to your dashboard (`POST /api/v1/scan/import`). Use
|
|
664
|
+
`--no-sync` to keep a scan local.
|
|
665
|
+
|
|
666
|
+
**Suppressing a finding:** add `# quantumsafe: ignore` (any comment style) to the
|
|
667
|
+
line.
|
|
668
|
+
|
|
669
|
+
### Use in CI (GitHub Action)
|
|
670
|
+
|
|
671
|
+
Drop this in `.github/workflows/quantumsafe.yml`. Findings land in the repo's
|
|
672
|
+
**Security → Code scanning** tab, annotated on the exact file and line.
|
|
673
|
+
|
|
674
|
+
```yaml
|
|
675
|
+
name: QuantumSafe
|
|
676
|
+
|
|
677
|
+
on: [push, pull_request]
|
|
678
|
+
|
|
679
|
+
permissions:
|
|
680
|
+
contents: read
|
|
681
|
+
security-events: write # required for upload-sarif
|
|
682
|
+
|
|
683
|
+
jobs:
|
|
684
|
+
quantumsafe:
|
|
685
|
+
runs-on: ubuntu-latest
|
|
686
|
+
steps:
|
|
687
|
+
- uses: actions/checkout@v4
|
|
688
|
+
|
|
689
|
+
- uses: Danny-397/Quantum-Safe-Scan@main
|
|
690
|
+
with:
|
|
691
|
+
path: .
|
|
692
|
+
exclude: tests/*,vendor/*
|
|
693
|
+
fail-on-high: "true" # fail the build on any HIGH finding
|
|
694
|
+
|
|
695
|
+
# Or ratchet instead of gating on absolutes: tolerate the existing
|
|
696
|
+
# backlog and fail only when it grows. A missing baseline warns and
|
|
697
|
+
# skips the comparison, so the first run still works.
|
|
698
|
+
# baseline: quantumsafe-baseline.json
|
|
699
|
+
# fail-on-new: "true"
|
|
700
|
+
|
|
701
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
702
|
+
with:
|
|
703
|
+
sarif_file: quantumsafe.sarif
|
|
704
|
+
category: quantumsafe
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
| Input | Default | Meaning |
|
|
708
|
+
|---|---|---|
|
|
709
|
+
| `path` | `.` | Directory to scan |
|
|
710
|
+
| `output` | `quantumsafe.sarif` | Where to write the SARIF report |
|
|
711
|
+
| `exclude` | *(none)* | Comma-separated globs to skip |
|
|
712
|
+
| `fail-on-high` | `"false"` | Exit non-zero if any HIGH finding is present |
|
|
713
|
+
| `version` | *(latest)* | Pin `quantumsafe-scan`, e.g. `0.2.0` |
|
|
714
|
+
|
|
715
|
+
Pin to a released tag rather than `@main` once one exists — `@main` moves under
|
|
716
|
+
you, which is the same class of problem as an unpinned linter.
|
|
717
|
+
|
|
718
|
+
---
|
|
719
|
+
|
|
720
|
+
## API documentation
|
|
721
|
+
|
|
722
|
+
Base URL (dev): `http://localhost:5000` · all endpoints under `/api/v1`.
|
|
723
|
+
Authentication: **JWT** (`Authorization: Bearer <token>`) for the dashboard, or a
|
|
724
|
+
**CLI API key** (`X-API-Key: qs_live_...`) for the scan endpoint.
|
|
725
|
+
|
|
726
|
+
### Auth
|
|
727
|
+
|
|
728
|
+
```http
|
|
729
|
+
POST /api/v1/auth/register { "email", "password" } -> { token, user }
|
|
730
|
+
POST /api/v1/auth/login { "email", "password" } -> { token, user }
|
|
731
|
+
GET /api/v1/auth/verify?token=... -> { message }
|
|
732
|
+
POST /api/v1/auth/forgot { "email" } -> { message }
|
|
733
|
+
POST /api/v1/auth/reset { "token", "password" } -> { message }
|
|
734
|
+
GET /api/v1/auth/me (JWT) -> { user }
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
### Scanning
|
|
738
|
+
|
|
739
|
+
```http
|
|
740
|
+
POST /api/v1/scan (JWT or X-API-Key)
|
|
741
|
+
{ "repo_url": "https://github.com/org/app" } # or multipart file=<.zip>
|
|
742
|
+
-> { scan_id, report }
|
|
743
|
+
|
|
744
|
+
POST /api/v1/scan/import (X-API-Key) # used by the CLI to upload results
|
|
745
|
+
{ "report": { ...quantumsafe report... } } -> { scan_id }
|
|
746
|
+
|
|
747
|
+
POST /api/v1/demo-scan (public, rate-limited) # landing-page live demo
|
|
748
|
+
{ "code": "..." } -> { report } # runs the real engine, stores nothing
|
|
749
|
+
|
|
750
|
+
POST /api/v1/scan-url (public, 10/hour) # live TLS endpoint scan
|
|
751
|
+
{ "url": "example.com" } -> { report } # one handshake, stores nothing
|
|
752
|
+
|
|
753
|
+
POST /api/v1/horizon (public, 120/hour) # Mosca's inequality
|
|
754
|
+
{ "findings": [{"family": "rsa"}], "secrecy_years": 10 } -> { horizon }
|
|
755
|
+
# only the family is read; the dashboard fetches Y once and moves its
|
|
756
|
+
# sliders locally, since X + Y > Z is arithmetic
|
|
757
|
+
|
|
758
|
+
GET /api/v1/scans?page=1&per_page=20 (JWT) -> paginated list
|
|
759
|
+
GET /api/v1/scans/{id} (JWT) -> scan + findings
|
|
760
|
+
GET /api/v1/scans/{id}/export?format=json|html|csv|sarif|cbom|svg (JWT)
|
|
761
|
+
GET /api/v1/scans/{id}/migration (JWT) -> grouped migration plan
|
|
762
|
+
GET /api/v1/scans/{id}/diff?against={id} (JWT) -> fixed / new / unchanged
|
|
763
|
+
GET /api/v1/overview (JWT) -> dashboard stats + trend
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
### API key management
|
|
767
|
+
|
|
768
|
+
```http
|
|
769
|
+
GET /api/v1/user/apikey (JWT) -> { has_api_key, api_key_prefix }
|
|
770
|
+
POST /api/v1/user/apikey (JWT) -> { api_key } # full key shown ONCE
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
All endpoints are rate-limited; CORS is restricted to `FRONTEND_ORIGIN`. GDPR-style
|
|
774
|
+
endpoints (`/user/data` export, `/user/account` delete) let a user export or erase
|
|
775
|
+
all of their data.
|
|
776
|
+
|
|
777
|
+
---
|
|
778
|
+
|
|
779
|
+
## Dashboard
|
|
780
|
+
|
|
781
|
+
The dashboard, showing a **real scan of [paramiko](https://github.com/paramiko/paramiko)**
|
|
782
|
+
(100/100 Critical, 110 findings):
|
|
783
|
+
|
|
784
|
+
| Overview | Findings | Migration plan |
|
|
785
|
+
|---|---|---|
|
|
786
|
+
|  |  |  |
|
|
787
|
+
|
|
788
|
+
A static site (`frontend/`) — no build step. Pages:
|
|
789
|
+
|
|
790
|
+
- **Landing** — hero, in-browser live scanner, feature pillars (free, no paywall).
|
|
791
|
+
- **Auth** — login, register, forgot/reset password.
|
|
792
|
+
- **Dashboard** — Overview (risk score, totals, trend chart, recent scans),
|
|
793
|
+
Scans (paginated), Findings (filterable), Settings (API key + account).
|
|
794
|
+
- **Scan detail** — full findings table, filter by risk, export JSON/HTML/CSV/SARIF/CBOM/SVG.
|
|
795
|
+
- **Migration plan** — findings grouped by risk with NIST replacement, standard
|
|
796
|
+
reference, and estimated complexity.
|
|
797
|
+
- **Research** — a public explainer of Shor/Grover/LWE/Kyber and the NIST standards.
|
|
798
|
+
|
|
799
|
+
Point the dashboard at your API by editing one line in `frontend/config.js`:
|
|
800
|
+
|
|
801
|
+
```js
|
|
802
|
+
window.QUANTUMSAFE_API = "https://quantumsafe-api.onrender.com";
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
(Leave it `""` for local development — it falls back to `http://localhost:5000`.)
|
|
806
|
+
|
|
807
|
+
---
|
|
808
|
+
|
|
809
|
+
## Local development setup
|
|
810
|
+
|
|
811
|
+
Requires Python 3.9+.
|
|
812
|
+
|
|
813
|
+
```bash
|
|
814
|
+
git clone https://github.com/Danny-397/Quantum-Safe-Scan
|
|
815
|
+
cd Quantum-Safe
|
|
816
|
+
|
|
817
|
+
# 1) Install the shared scanner package (CLI) in editable mode
|
|
818
|
+
pip install -e .
|
|
819
|
+
|
|
820
|
+
# 2) Install backend dependencies
|
|
821
|
+
pip install -r backend/requirements.txt
|
|
822
|
+
|
|
823
|
+
# 3) Configure environment
|
|
824
|
+
cp .env.example .env # fill in SECRET_KEY / JWT_SECRET_KEY at minimum
|
|
825
|
+
|
|
826
|
+
# 4) Run the API (creates SQLite tables automatically)
|
|
827
|
+
cd backend
|
|
828
|
+
python app.py # http://localhost:5000 (health: /health)
|
|
829
|
+
|
|
830
|
+
# 5) Serve the dashboard (any static server)
|
|
831
|
+
cd ../frontend
|
|
832
|
+
python -m http.server 3000 # http://localhost:3000
|
|
833
|
+
```
|
|
834
|
+
|
|
835
|
+
### Run the whole stack with Docker
|
|
836
|
+
|
|
837
|
+
```bash
|
|
838
|
+
docker compose up --build
|
|
839
|
+
# Dashboard -> http://localhost:3000 API -> http://localhost:5000
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
### Tests
|
|
843
|
+
|
|
844
|
+
```bash
|
|
845
|
+
pip install -r requirements-dev.txt
|
|
846
|
+
pytest -q # 545 tests; in-memory DB, no setup
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
Seed a demo account so the dashboard is populated:
|
|
850
|
+
|
|
851
|
+
```bash
|
|
852
|
+
cd backend && python seed_demo.py # demo@quantumsafe.dev / demodemo123
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
Without `MAIL_SERVER` configured, verification/reset emails are printed to the
|
|
856
|
+
server log instead of being sent — so you can develop without SMTP.
|
|
857
|
+
|
|
858
|
+
---
|
|
859
|
+
|
|
860
|
+
## Environment variables
|
|
861
|
+
|
|
862
|
+
See [`.env.example`](.env.example).
|
|
863
|
+
|
|
864
|
+
| Variable | Required | Where to get it |
|
|
865
|
+
|----------|----------|-----------------|
|
|
866
|
+
| `SECRET_KEY` | ✅ | Generate: `python -c "import secrets;print(secrets.token_hex(32))"` |
|
|
867
|
+
| `JWT_SECRET_KEY` | ✅ | Generate the same way (use a different value) |
|
|
868
|
+
| `DATABASE_URL` | prod | Render Postgres dashboard → *Connections* (SQLite used if unset) |
|
|
869
|
+
| `FRONTEND_ORIGIN` | ✅ | Your dashboard URL, e.g. `https://quantumsafescan.com` |
|
|
870
|
+
| `DASHBOARD_URL` | ✅ | Same as above (used in emails) |
|
|
871
|
+
| `API_URL` | ✅ | The deployed API URL (used for email verify links) |
|
|
872
|
+
| `MAIL_SERVER` / `MAIL_PORT` / `MAIL_USE_TLS` | email | Your SMTP provider (e.g. `smtp.gmail.com` / 587 / true) |
|
|
873
|
+
| `MAIL_USERNAME` / `MAIL_PASSWORD` | email | SMTP credentials (Gmail: an App Password) |
|
|
874
|
+
| `MAIL_DEFAULT_SENDER` | email | The "from" address |
|
|
875
|
+
| `RATELIMIT_STORAGE_URI` | optional | `memory://` (dev) or a Redis URL (prod) |
|
|
876
|
+
|
|
877
|
+
---
|
|
878
|
+
|
|
879
|
+
## Deployment
|
|
880
|
+
|
|
881
|
+
[](https://render.com/deploy?repo=https://github.com/Danny-397/Quantum-Safe-Scan)
|
|
882
|
+
|
|
883
|
+
See **[DEPLOYMENT.md](DEPLOYMENT.md)** for the full walkthrough. In short:
|
|
884
|
+
|
|
885
|
+
- **CLI → PyPI:** `python -m build && twine upload dist/*`
|
|
886
|
+
- **Backend → Render:** push the repo; Render reads [`render.yaml`](render.yaml)
|
|
887
|
+
(web service + Postgres). Set the `sync: false` env vars in the dashboard.
|
|
888
|
+
- **Frontend → Vercel:** set Root Directory to `frontend/`; point
|
|
889
|
+
`frontend/config.js` at your Render API URL.
|
|
890
|
+
|
|
891
|
+
---
|
|
892
|
+
|
|
893
|
+
## Project structure
|
|
894
|
+
|
|
895
|
+
```
|
|
896
|
+
Quantum-Safe/
|
|
897
|
+
├── quantum/ # REAL quantum computing (Qiskit): the attacks themselves
|
|
898
|
+
│ ├── shor.py # Shor's algorithm — factors N, breaks RSA
|
|
899
|
+
│ ├── grover.py # Grover's algorithm — key-search speedup
|
|
900
|
+
│ ├── resources.py # qubit / depth / gate-count estimation
|
|
901
|
+
│ └── README.md
|
|
902
|
+
├── pqc/ # Post-quantum SOLUTION: lattice (LWE) crypto from scratch
|
|
903
|
+
│ ├── lwe_kem.py # quantum-safe key encapsulation (the math behind Kyber)
|
|
904
|
+
│ ├── benchmark.py # latency & sizes vs RSA / ML-KEM
|
|
905
|
+
│ └── README.md
|
|
906
|
+
├── cli/ # the `quantumsafe` package (CLI + shared engine)
|
|
907
|
+
│ ├── scanner.py # AST + regex detection, cross-language usage-awareness
|
|
908
|
+
│ ├── dependencies.py # dependency + lockfile crypto scanning (purl + CBOM)
|
|
909
|
+
│ ├── reachability.py # reachability ranking (reachable/test/unreferenced)
|
|
910
|
+
│ ├── taint.py # intra-module data-flow (wrapper) analysis
|
|
911
|
+
│ ├── callgraph.py # whole-program cross-file taint (import resolution)
|
|
912
|
+
│ ├── scorer.py # risk score
|
|
913
|
+
│ ├── recommender.py # NIST family-level recommendations
|
|
914
|
+
│ ├── remediation.py # call-site-specific fixes (before/after)
|
|
915
|
+
│ ├── reporter.py # terminal / JSON / HTML / SARIF / CBOM / SVG output
|
|
916
|
+
│ └── cli.py # argparse entry point
|
|
917
|
+
├── backend/ # Flask REST API
|
|
918
|
+
│ ├── app.py config.py extensions.py models.py
|
|
919
|
+
│ ├── auth.py api.py scanner_service.py
|
|
920
|
+
│ └── requirements.txt
|
|
921
|
+
├── frontend/ # static dashboard (no build step)
|
|
922
|
+
│ ├── index.html login.html dashboard.html scan.html migration.html
|
|
923
|
+
│ ├── research.html privacy.html terms.html
|
|
924
|
+
│ └── style.css app.js config.js
|
|
925
|
+
├── benchmark/ # labeled precision/recall evaluation (+ graphs/)
|
|
926
|
+
├── study/ # empirical scan over real open-source repos
|
|
927
|
+
├── docs/ # whitepaper, architecture, NIST & vuln-class mappings
|
|
928
|
+
├── pyproject.toml # packages cli/ as `quantumsafe`
|
|
929
|
+
└── render.yaml .env.example README.md
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
---
|
|
933
|
+
|
|
934
|
+
## NIST PQC references
|
|
935
|
+
|
|
936
|
+
- **FIPS 203** — Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM / Kyber)
|
|
937
|
+
- **FIPS 204** — Module-Lattice-Based Digital Signature Algorithm (ML-DSA / Dilithium)
|
|
938
|
+
- **FIPS 205** — Stateless Hash-Based Digital Signature Algorithm (SLH-DSA / SPHINCS+)
|
|
939
|
+
- **NIST SP 800-52 Rev. 2** — TLS guidance
|
|
940
|
+
- **NIST SP 800-131A Rev. 2** — transitioning cryptographic algorithms/key lengths
|
|
941
|
+
- **NIST IR 8547** — transition to post-quantum cryptography standards
|
|
942
|
+
|
|
943
|
+
Full reasoning per algorithm: [docs/NIST_MAPPING.md](docs/NIST_MAPPING.md).
|
|
944
|
+
|
|
945
|
+
---
|
|
946
|
+
|
|
947
|
+
## If this were a product
|
|
948
|
+
|
|
949
|
+
QuantumSafe is intentionally **free and open source** — the core scan needs no
|
|
950
|
+
account, and the CLI / GitHub Action are the primary way it's meant to be used.
|
|
951
|
+
That's a deliberate choice, not a missing feature: a login wall would only add
|
|
952
|
+
friction to a tool whose value is instant.
|
|
953
|
+
|
|
954
|
+
For the record, the productization thinking exists even though it isn't built:
|
|
955
|
+
the free tier would stay everything shown here (scan, score, migration plan, all
|
|
956
|
+
exports); a paid tier would be the things that only make sense for an
|
|
957
|
+
organization — scheduled re-scans with drift alerts, multi-repo/org dashboards,
|
|
958
|
+
SSO, and audit-ready CBOM history for compliance. Those are operational features,
|
|
959
|
+
not gates on the core detection, which is the part that should always be open.
|
|
960
|
+
|
|
961
|
+
## License
|
|
962
|
+
|
|
963
|
+
MIT — see [LICENSE](LICENSE).
|