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.
Files changed (53) hide show
  1. quantumsafe_scan-0.3.0/PKG-INFO +963 -0
  2. quantumsafe_scan-0.3.0/README.md +931 -0
  3. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/__init__.py +1 -1
  4. quantumsafe_scan-0.3.0/cli/callgraph.py +306 -0
  5. quantumsafe_scan-0.3.0/cli/certchain.py +400 -0
  6. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/cli.py +108 -8
  7. quantumsafe_scan-0.3.0/cli/dependencies.py +486 -0
  8. quantumsafe_scan-0.3.0/cli/diff.py +171 -0
  9. quantumsafe_scan-0.3.0/cli/horizon.py +281 -0
  10. quantumsafe_scan-0.3.0/cli/origins.py +263 -0
  11. quantumsafe_scan-0.3.0/cli/reachability.py +154 -0
  12. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/recommender.py +29 -0
  13. quantumsafe_scan-0.3.0/cli/remediation.py +188 -0
  14. quantumsafe_scan-0.3.0/cli/reporter.py +657 -0
  15. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/scanner.py +328 -13
  16. quantumsafe_scan-0.3.0/cli/taint.py +200 -0
  17. quantumsafe_scan-0.3.0/cli/tlsscan.py +425 -0
  18. quantumsafe_scan-0.3.0/pyproject.toml +56 -0
  19. quantumsafe_scan-0.3.0/quantumsafe_scan.egg-info/PKG-INFO +963 -0
  20. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/SOURCES.txt +21 -1
  21. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/setup.cfg +4 -4
  22. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_api.py +65 -0
  23. quantumsafe_scan-0.3.0/tests/test_callgraph.py +71 -0
  24. quantumsafe_scan-0.3.0/tests/test_certchain.py +423 -0
  25. quantumsafe_scan-0.3.0/tests/test_conformance.py +176 -0
  26. quantumsafe_scan-0.3.0/tests/test_cors.py +123 -0
  27. quantumsafe_scan-0.3.0/tests/test_diff.py +328 -0
  28. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_features.py +28 -0
  29. quantumsafe_scan-0.3.0/tests/test_horizon.py +348 -0
  30. quantumsafe_scan-0.3.0/tests/test_origins.py +284 -0
  31. quantumsafe_scan-0.3.0/tests/test_remediation.py +149 -0
  32. quantumsafe_scan-0.3.0/tests/test_scanner.py +284 -0
  33. quantumsafe_scan-0.3.0/tests/test_seeded.py +26 -0
  34. quantumsafe_scan-0.3.0/tests/test_taint.py +66 -0
  35. quantumsafe_scan-0.3.0/tests/test_tlsscan.py +436 -0
  36. quantumsafe_scan-0.1.0/PKG-INFO +0 -569
  37. quantumsafe_scan-0.1.0/README.md +0 -552
  38. quantumsafe_scan-0.1.0/cli/reporter.py +0 -343
  39. quantumsafe_scan-0.1.0/pyproject.toml +0 -37
  40. quantumsafe_scan-0.1.0/quantumsafe_scan.egg-info/PKG-INFO +0 -569
  41. quantumsafe_scan-0.1.0/tests/test_conformance.py +0 -92
  42. quantumsafe_scan-0.1.0/tests/test_scanner.py +0 -144
  43. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/LICENSE +0 -0
  44. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/cli/scorer.py +0 -0
  45. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/dependency_links.txt +0 -0
  46. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/entry_points.txt +0 -0
  47. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/requires.txt +0 -0
  48. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/quantumsafe_scan.egg-info/top_level.txt +0 -0
  49. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_benchmark.py +0 -0
  50. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_pqc.py +0 -0
  51. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_quantum.py +0 -0
  52. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.3.0}/tests/test_schema.py +0 -0
  53. {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&ndash;100, and get the NIST-approved replacement for every finding &mdash; free &amp; open source.</strong>
54
+
55
+ <br><br>
56
+
57
+ <a href="https://quantumsafescan.com"><b>Live demo</b></a> &nbsp;&middot;&nbsp;
58
+ <a href="https://pypi.org/project/quantumsafe-scan/"><b>Install</b></a> &nbsp;&middot;&nbsp;
59
+ <a href="docs/WHITEPAPER.md"><b>Documentation</b></a> &nbsp;&middot;&nbsp;
60
+ <a href="#the-three-layers"><b>How it works</b></a> &nbsp;&middot;&nbsp;
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
+ ![QuantumSafe architecture](docs/architecture.png)
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
+ | ![by type](benchmark/graphs/vulnerabilities_by_type.png) | ![severity](benchmark/graphs/severity_distribution.png) | ![scan time](benchmark/graphs/scan_time_vs_size.png) |
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
+ | ![by family](benchmark/graphs/realworld_by_family.png) | ![top packages](benchmark/graphs/realworld_top_packages.png) |
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
+ | ![Overview](docs/screenshots/overview.png) | ![Findings](docs/screenshots/findings.png) | ![Migration plan](docs/screenshots/migration-plan.png) |
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
+ [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](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).