quantumsafe-scan 0.1.0__tar.gz → 0.2.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 (36) hide show
  1. {quantumsafe_scan-0.1.0/quantumsafe_scan.egg-info → quantumsafe_scan-0.2.0}/PKG-INFO +679 -569
  2. quantumsafe_scan-0.1.0/PKG-INFO → quantumsafe_scan-0.2.0/README.md +647 -569
  3. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/__init__.py +1 -1
  4. quantumsafe_scan-0.2.0/cli/callgraph.py +306 -0
  5. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/cli.py +20 -2
  6. quantumsafe_scan-0.2.0/cli/dependencies.py +489 -0
  7. quantumsafe_scan-0.2.0/cli/reachability.py +154 -0
  8. quantumsafe_scan-0.2.0/cli/remediation.py +170 -0
  9. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/reporter.py +120 -17
  10. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/scanner.py +328 -13
  11. quantumsafe_scan-0.2.0/cli/taint.py +200 -0
  12. quantumsafe_scan-0.2.0/pyproject.toml +56 -0
  13. quantumsafe_scan-0.1.0/README.md → quantumsafe_scan-0.2.0/quantumsafe_scan.egg-info/PKG-INFO +160 -33
  14. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/quantumsafe_scan.egg-info/SOURCES.txt +9 -1
  15. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/setup.cfg +4 -4
  16. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_api.py +65 -0
  17. quantumsafe_scan-0.2.0/tests/test_callgraph.py +71 -0
  18. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_conformance.py +11 -3
  19. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_features.py +28 -0
  20. quantumsafe_scan-0.2.0/tests/test_scanner.py +284 -0
  21. quantumsafe_scan-0.2.0/tests/test_seeded.py +26 -0
  22. quantumsafe_scan-0.2.0/tests/test_taint.py +66 -0
  23. quantumsafe_scan-0.1.0/pyproject.toml +0 -37
  24. quantumsafe_scan-0.1.0/tests/test_scanner.py +0 -144
  25. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/LICENSE +0 -0
  26. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/recommender.py +0 -0
  27. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/cli/scorer.py +0 -0
  28. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/quantumsafe_scan.egg-info/dependency_links.txt +0 -0
  29. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/quantumsafe_scan.egg-info/entry_points.txt +0 -0
  30. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/quantumsafe_scan.egg-info/requires.txt +0 -0
  31. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/quantumsafe_scan.egg-info/top_level.txt +0 -0
  32. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_benchmark.py +0 -0
  33. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_pqc.py +0 -0
  34. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_quantum.py +0 -0
  35. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_schema.py +0 -0
  36. {quantumsafe_scan-0.1.0 → quantumsafe_scan-0.2.0}/tests/test_scorer.py +0 -0
@@ -1,569 +1,679 @@
1
- Metadata-Version: 2.4
2
- Name: quantumsafe-scan
3
- Version: 0.1.0
4
- Summary: Scan codebases for quantum-vulnerable cryptography and generate a NIST-aligned migration plan.
5
- Author: QuantumSafe
6
- License: MIT
7
- Project-URL: Homepage, https://github.com/Danny-397/Quantamn-Safe
8
- Keywords: quantum,cryptography,pqc,nist,security,kyber,dilithium
9
- Classifier: Programming Language :: Python :: 3
10
- Classifier: License :: OSI Approved :: MIT License
11
- Classifier: Topic :: Security :: Cryptography
12
- Requires-Python: >=3.9
13
- Description-Content-Type: text/markdown
14
- License-File: LICENSE
15
- Requires-Dist: rich>=13.0
16
- Dynamic: license-file
17
-
18
- # QuantumSafe
19
-
20
- [![CI](https://github.com/Danny-397/Quantamn-Safe/actions/workflows/ci.yml/badge.svg)](https://github.com/Danny-397/Quantamn-Safe/actions/workflows/ci.yml)
21
- ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
22
- ![License: MIT](https://img.shields.io/badge/license-MIT-green)
23
- ![Standards](https://img.shields.io/badge/NIST-FIPS%20203%2F204%2F205-9d7bff)
24
-
25
- **A post-quantum security platform that demonstrates the quantum attack, detects
26
- the vulnerable cryptography in your code, and implements the quantum-safe fix.**
27
-
28
- QuantumSafe scans code across 11 languages for the cryptography that quantum
29
- computers will break (RSA, ECC, Diffie-Hellman) or weaken (AES-128, SHA-256),
30
- scores the risk 0–100, and maps every finding to its NIST FIPS 203/204/205
31
- replacement — backed by a real Qiskit implementation of Shor's and Grover's
32
- algorithms and a from-scratch lattice (LWE) key-encapsulation mechanism.
33
-
34
- > ⚠️ **Disclaimer.** QuantumSafe is a security-awareness and triage tool. It uses
35
- > static pattern + AST analysis and is **not** a substitute for a professional
36
- > cryptographic audit. Findings are heuristic and may include false
37
- > positives/negatives.
38
-
39
- ---
40
-
41
- ## The three layers
42
-
43
- QuantumSafe covers the full arc of the post-quantum problem — not just naming it,
44
- but **executing** the attack, **finding** the vulnerable code, and **running** the
45
- solution:
46
-
47
- | Layer | Module | What it does |
48
- |-------|--------|--------------|
49
- | **1. Attack** | [`quantum/`](quantum/) | Shor's and Grover's algorithms in **Qiskit**, run on a quantum simulator. Shor factors a number and reconstructs an RSA key — the concrete reason RSA/ECC are rated HIGH. |
50
- | **2. Detection** | [`cli/`](cli/) | A hybrid **AST + regex** static-analysis engine over 11 languages that scores risk and produces a NIST-aligned migration plan. **100% precision/recall** on a labeled [benchmark](benchmark/). |
51
- | **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. |
52
-
53
- The detection layer ships through three surfaces that share **one** engine:
54
-
55
- - A **free CLI** (`pip install quantumsafe-scan`) — scan local dirs or public GitHub
56
- repos; export JSON / HTML / SARIF / CBOM / SVG badge.
57
- - A **Flask REST API** — powers the dashboard, ingests scans, handles auth.
58
- - A **dark, terminal-style web dashboard** — scan history, findings, migration
59
- plans, and exports. **Free, no paywall.**
60
-
61
- ---
62
-
63
- ## Why it matters
64
-
65
- RSA-2048 and elliptic-curve crypto secure almost everything — HTTPS/TLS,
66
- certificates, SSH, code signing, VPNs. **Shor's algorithm breaks all of it.** The
67
- math is settled; only the hardware is missing (RSA-2048 needs millions of
68
- error-corrected qubits, and today's machines have a few hundred noisy ones).
69
-
70
- That gap is the reason to act now, not later:
71
-
72
- - **"Harvest now, decrypt later":** an adversary can record encrypted traffic
73
- today and decrypt it once the hardware exists. Anything that must stay secret
74
- for 5–15 years is effectively at risk *now*.
75
- - **Migration is slow:** swapping cryptography across a large codebase takes years
76
- — which is why NIST finalized the post-quantum standards (FIPS 203/204/205) in
77
- 2024.
78
-
79
- QuantumSafe makes that migration tractable: **find** the vulnerable crypto,
80
- **understand** why it's vulnerable, and **adopt** the quantum-safe replacement.
81
-
82
- ---
83
-
84
- ## Architecture
85
-
86
- ![QuantumSafe architecture](docs/architecture.png)
87
-
88
- One shared detection engine (`cli/`) sits behind three surfaces — the CLI, the
89
- REST API, and the web dashboard — and is flanked by two runnable companions: the
90
- `quantum/` attack module (which *justifies* the risk ratings) and the `pqc/`
91
- defense module (which *implements* the recommended fix). Full write-up in
92
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md); the diagram is regenerated by
93
- `python docs/make_architecture.py` (vector source: [docs/architecture.svg](docs/architecture.svg)).
94
-
95
- ## Documentation
96
-
97
- | Document | What's in it |
98
- |----------|--------------|
99
- | [docs/WHITEPAPER.md](docs/WHITEPAPER.md) | Full technical whitepaper: threat model, design, scoring, evaluation, limitations, future work |
100
- | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Components, the CLI→API→Scanner→Risk→Export pipeline, data flow, deployment topology |
101
- | [docs/architecture_diagram.txt](docs/architecture_diagram.txt) | One-screen ASCII system diagram |
102
- | [docs/EXAMPLES.md](docs/EXAMPLES.md) | **Real** scan output — terminal table, JSON, SARIF, HTML, badge |
103
- | [docs/NIST_MAPPING.md](docs/NIST_MAPPING.md) | Every detected family → its NIST PQC replacement, with the reasoning |
104
- | [docs/CVE_MAPPING.md](docs/CVE_MAPPING.md) | Findings mapped to general vulnerability classes (no invented CVEs) |
105
- | [benchmark/RESULTS.md](benchmark/RESULTS.md) | Precision/recall/F1, risk distribution, reproducible charts |
106
- | [TECHNICAL_OVERVIEW.md](TECHNICAL_OVERVIEW.md) | Design decisions, quantum-threat background, honest limitations |
107
-
108
- ---
109
-
110
- ## Key features
111
-
112
- - **11-language detection** — Python (AST-aware), JavaScript/TypeScript, Java, Go,
113
- Ruby, C#, PHP, Rust, C/C++, Kotlin, Swift.
114
- - **0–100 Quantum Risk Score** computed from real findings (never hardcoded), with
115
- Low/Medium/High/Critical bands.
116
- - **NIST-aligned migration plan** — each finding mapped to ML-KEM/ML-DSA/SHA-3/
117
- AES-256 with the relevant FIPS standard and a complexity estimate.
118
- - **Six export formats** — terminal, JSON, HTML, **SARIF** (GitHub code scanning),
119
- **CycloneDX CBOM**, and an embeddable **SVG risk badge**. The SARIF output is
120
- validated against the official OASIS 2.1.0 JSON Schema and the CBOM against the
121
- CycloneDX 1.6 crypto structure in the test suite, so they interoperate for real.
122
- - **Real quantum demos** — Shor + Grover in Qiskit, plus circuit resource
123
- estimates.
124
- - **Real post-quantum crypto** — an LWE KEM verified over 200+ key exchanges with
125
- zero failures.
126
- - **Measured, not asserted** — a labeled benchmark with adversarial decoys, plus an
127
- empirical study (88% of real repos affected).
128
- - **Production practice** — one shared engine for CLI + API, **74 automated
129
- tests**, CI, Docker, a reusable GitHub Action, and multi-service deploy configs.
130
-
131
- ---
132
-
133
- ## What it detects
134
-
135
- | Risk | Algorithms |
136
- |------|------------|
137
- | **HIGH** — migrate immediately | RSA (any size, incl. RSA-2048/4096), ECDSA / ECDH / ECC, DSA, Diffie-Hellman, MD5, SHA-1 |
138
- | **MEDIUM** — plan migration | TLS 1.0 / 1.1, 3DES / Triple DES, RC4, RSA key sizes under 2048 |
139
- | **LOW** — monitor | SHA-256, AES-128, TLS 1.2 |
140
-
141
- Each finding includes the file, line number, algorithm, risk level, *why* it is
142
- vulnerable, and a NIST-approved replacement:
143
-
144
- - RSA/ECC key exchange → **CRYSTALS-Kyber (ML-KEM, FIPS 203)**
145
- - RSA/ECDSA/DSA signatures → **CRYSTALS-Dilithium (ML-DSA, FIPS 204)** / SPHINCS+ (FIPS 205)
146
- - Hash functions → **SHA-3** or SHA-256
147
- - Symmetric encryption → **AES-256**
148
-
149
- ## Quantum Risk Score
150
-
151
- A 0–100 score computed **from real findings**:
152
-
153
- ```
154
- score = min(100, 15*HIGH + 5*MEDIUM + 1*LOW)
155
- ```
156
-
157
- | Score | Band | Meaning |
158
- |-------|------|---------|
159
- | 0–30 | Low | Good quantum hygiene |
160
- | 31–60 | Medium | Plan migration |
161
- | 61–80 | High | Prioritize migration |
162
- | 81–100 | Critical | Immediate action required |
163
-
164
- ---
165
-
166
- ## Evaluation (does the detector actually work?)
167
-
168
- The scanner is measured against a labeled [benchmark](benchmark/) of 15 files
169
- across 9 languages, including adversarial decoys (crypto names in comments,
170
- docstrings, log strings, and word-boundary traps like `md5sumLabel`) designed to
171
- trip a naive matcher. `evaluate.py` runs the scanner twice — a naive line-regex
172
- baseline vs. the string/comment-aware engine — so the improvement is measured:
173
-
174
- ```bash
175
- python benchmark/evaluate.py
176
- ```
177
-
178
- | Configuration | FP | Precision | Recall | F1 |
179
- |---|--:|--:|--:|--:|
180
- | Naive line-regex baseline | 14 | 65.0% | 100% | 78.8% |
181
- | **QuantumSafe (usage-aware)** | **0** | **100%** | **100%** | **100%** |
182
-
183
- Usage-awareness removes 14 false positives (keywords inside docstrings/log strings)
184
- without losing a true positive. `evaluate.py` prints the exact false
185
- positives/negatives so the numbers are auditable, and the thresholds are enforced
186
- by `tests/test_benchmark.py`. Honest
187
- limits are documented in [benchmark/README.md](benchmark/README.md) and
188
- [benchmark/RESULTS.md](benchmark/RESULTS.md) — this is a regression benchmark, not
189
- a claim of perfection on arbitrary code.
190
-
191
- These charts are generated from **live scanner output** by
192
- `python benchmark/graphs/generate_graphs.py` (not hardcoded):
193
-
194
- | Vulnerabilities by family | Severity split | Scan time vs. files |
195
- |---|---|---|
196
- | ![by type](benchmark/graphs/vulnerabilities_by_type.png) | ![severity](benchmark/graphs/severity_distribution.png) | ![scan time](benchmark/graphs/scan_time_vs_size.png) |
197
-
198
- **See real scan output** — terminal table, JSON, SARIF, HTML, and an SVG risk
199
- badge from an actual scan — in [docs/EXAMPLES.md](docs/EXAMPLES.md).
200
-
201
- ### Real-world scan: paramiko (the SSH library)
202
-
203
- Run against a shallow clone of [`paramiko/paramiko`](https://github.com/paramiko/paramiko)
204
- — the SSH implementation behind Ansible, Fabric, and much of the Python ecosystem.
205
- SSH key exchange leans on RSA, ECDSA, and Diffie-Hellman, all broken by Shor's
206
- algorithm, which makes it a textbook "harvest now, decrypt later" target:
207
-
208
- ```bash
209
- quantumsafe scan --repo https://github.com/paramiko/paramiko
210
- ```
211
-
212
- | Metric | Result |
213
- |---|---|
214
- | Quantum Risk Score | **100 / 100 (Critical)** |
215
- | Findings (usage-aware) | **110** — 89 HIGH, 6 MEDIUM, 15 LOW |
216
- | Top algorithms | ECDSA ×23, ECC ×21, SHA-1 ×18, RSA ×15, MD5 ×10, 3DES ×6 |
217
- | Most-affected files | `paramiko/pkey.py`, `rsakey.py`, `transport.py`, `ecdsakey.py` |
218
-
219
- The usage-aware engine matters here: a naive line-regex reports **451 raw
220
- matches**, but most are the same algorithms repeated in docstrings, comments, and
221
- SSH protocol-name strings (`"ssh-rsa"`, `"ecdsa-sha2-nistp256"`). Focusing on real
222
- code brings that to **110** findings — a ~4× noise reduction. *Honest caveat: on a
223
- protocol library, a few of those suppressed string constants are arguably real
224
- signals, so 110 is a deliberately conservative, code-focused count — not a claim
225
- that the other 341 were all false positives.*
226
-
227
- ### Empirical study — how widespread is the problem?
228
-
229
- Scanning 8 widely-used open-source projects ([`study/`](study/), reproducible via
230
- `python study/run_study.py`):
231
-
232
- - **88%** contained at least one **HIGH-risk** (Shor-breakable) cryptographic usage.
233
- - Average Quantum Risk Score: **72.9 / 100**.
234
-
235
- Full results and caveats: [study/REPORT.md](study/REPORT.md).
236
-
237
- ---
238
-
239
- ## Quantum demonstrations (Shor & Grover)
240
-
241
- ```bash
242
- pip install -r quantum/requirements.txt
243
- python quantum/shor.py # quantum order-finding factors N=15, then breaks a toy RSA key
244
- python quantum/grover.py # recovers a hidden k-bit key in ~sqrt(2^k) steps
245
- python quantum/resources.py # qubit count, circuit depth, gate counts vs. RSA-2048 estimates
246
- ```
247
-
248
- - **`shor.py`** uses quantum phase estimation over modular exponentiation to find
249
- the order of `a mod N`, factors `N`, and reconstructs an RSA private key — the
250
- concrete reason RSA/ECC are rated **HIGH**.
251
- - **`grover.py`** uses amplitude amplification to search a key space in ~√N
252
- queries, halving effective key strength — the reason AES-128/SHA-256 are **LOW**.
253
-
254
- Honest scope: these run at small scale (factoring 15), the genuine state of the art
255
- for end-to-end Shor. See [quantum/README.md](quantum/README.md).
256
-
257
- ## Post-quantum solution ([`pqc/`](pqc/))
258
-
259
- ```bash
260
- pip install -r pqc/requirements.txt
261
- python pqc/lwe_kem.py # Alice & Bob agree on a shared secret; an eavesdropper can't
262
- python pqc/benchmark.py # measured latency + key/ciphertext sizes vs RSA & ML-KEM
263
- ```
264
-
265
- Why a quantum computer can't break it: LWE has **no periodic structure** for Shor
266
- to exploit. See [pqc/README.md](pqc/README.md).
267
-
268
- ---
269
-
270
- ## CLI: install & usage
271
-
272
- ```bash
273
- pip install quantumsafe-scan # from PyPI once published
274
- # or, from this repo:
275
- pip install -e .
276
- ```
277
-
278
- ### Commands
279
-
280
- ```bash
281
- # Scan a local directory (colored terminal table)
282
- quantumsafe scan --path ./myproject
283
-
284
- # Scan a public GitHub repo (shallow-cloned to a temp dir, then cleaned up)
285
- quantumsafe scan --repo https://github.com/org/app
286
-
287
- # Write a report: JSON, HTML, SARIF, CycloneDX CBOM, or an SVG risk badge
288
- quantumsafe scan --path ./myproject --output report.json
289
- quantumsafe scan --path ./myproject --output report.html
290
- quantumsafe scan --path ./myproject --output report.sarif # GitHub code scanning
291
- quantumsafe scan --path ./myproject --output report.cbom.json # CycloneDX CBOM
292
- quantumsafe scan --path ./myproject --output badge.svg # embeddable risk badge
293
-
294
- # Skip paths with glob patterns (repeatable)
295
- quantumsafe scan --path . --exclude 'tests/*' --exclude 'vendor/*'
296
-
297
- # Fail the process (exit 1) if any HIGH finding exists — handy in CI
298
- quantumsafe scan --path . --fail-on-high
299
-
300
- # Try it on the bundled examples
301
- quantumsafe scan --path examples
302
-
303
- # Link the CLI to your dashboard, then scans auto-upload to your history
304
- quantumsafe auth --key qs_live_xxxxxxxx --api-url https://quantumsafe-api.onrender.com
305
- quantumsafe scan --path ./myproject # prints results AND syncs to dashboard
306
- quantumsafe scan --path ./myproject --no-sync # local only, don't upload
307
-
308
- # Version
309
- quantumsafe version
310
- ```
311
-
312
- | Flag | Description |
313
- |------|-------------|
314
- | `--path` | Local directory or file to scan |
315
- | `--repo` | Public `https://github.com/<org>/<repo>` URL |
316
- | `--output` | Write to `.json`, `.cbom.json` (CycloneDX CBOM), `.html`, `.sarif`, or `.svg` (risk badge); terminal summary still printed |
317
- | `--exclude` | Glob of paths to skip (repeatable) |
318
- | `--fail-on-high` | Exit non-zero on any HIGH finding (CI gate) |
319
- | `--no-sync` | Don't upload the result to your linked dashboard |
320
-
321
- After `quantumsafe auth --key <key> --api-url <your-api>`, every `quantumsafe scan`
322
- also uploads its report to your dashboard (`POST /api/v1/scan/import`). Use
323
- `--no-sync` to keep a scan local.
324
-
325
- **Suppressing a finding:** add `# quantumsafe: ignore` (any comment style) to the
326
- line.
327
-
328
- ### Use in CI (GitHub Action)
329
-
330
- ```yaml
331
- - uses: Danny-397/Quantamn-Safe@main
332
- with:
333
- path: .
334
- exclude: tests/*,vendor/*
335
- fail-on-high: "true"
336
- - uses: github/codeql-action/upload-sarif@v3
337
- with:
338
- sarif_file: quantumsafe.sarif
339
- ```
340
-
341
- ---
342
-
343
- ## API documentation
344
-
345
- Base URL (dev): `http://localhost:5000` · all endpoints under `/api/v1`.
346
- Authentication: **JWT** (`Authorization: Bearer <token>`) for the dashboard, or a
347
- **CLI API key** (`X-API-Key: qs_live_...`) for the scan endpoint.
348
-
349
- ### Auth
350
-
351
- ```http
352
- POST /api/v1/auth/register { "email", "password" } -> { token, user }
353
- POST /api/v1/auth/login { "email", "password" } -> { token, user }
354
- GET /api/v1/auth/verify?token=... -> { message }
355
- POST /api/v1/auth/forgot { "email" } -> { message }
356
- POST /api/v1/auth/reset { "token", "password" } -> { message }
357
- GET /api/v1/auth/me (JWT) -> { user }
358
- ```
359
-
360
- ### Scanning
361
-
362
- ```http
363
- POST /api/v1/scan (JWT or X-API-Key)
364
- { "repo_url": "https://github.com/org/app" } # or multipart file=<.zip>
365
- -> { scan_id, report }
366
-
367
- POST /api/v1/scan/import (X-API-Key) # used by the CLI to upload results
368
- { "report": { ...quantumsafe report... } } -> { scan_id }
369
-
370
- POST /api/v1/demo-scan (public, rate-limited) # landing-page live demo
371
- { "code": "..." } -> { report } # runs the real engine, stores nothing
372
-
373
- GET /api/v1/scans?page=1&per_page=20 (JWT) -> paginated list
374
- GET /api/v1/scans/{id} (JWT) -> scan + findings
375
- GET /api/v1/scans/{id}/export?format=json|html|csv|sarif|cbom|svg (JWT)
376
- GET /api/v1/scans/{id}/migration (JWT) -> grouped migration plan
377
- GET /api/v1/overview (JWT) -> dashboard stats + trend
378
- ```
379
-
380
- ### API key management
381
-
382
- ```http
383
- GET /api/v1/user/apikey (JWT) -> { has_api_key, api_key_prefix }
384
- POST /api/v1/user/apikey (JWT) -> { api_key } # full key shown ONCE
385
- ```
386
-
387
- All endpoints are rate-limited; CORS is restricted to `FRONTEND_ORIGIN`. GDPR-style
388
- endpoints (`/user/data` export, `/user/account` delete) let a user export or erase
389
- all of their data.
390
-
391
- ---
392
-
393
- ## Dashboard
394
-
395
- | Overview | Findings | Migration plan |
396
- |---|---|---|
397
- | ![Overview](docs/screenshots/overview.png) | ![Findings](docs/screenshots/findings.png) | ![Migration plan](docs/screenshots/migration-plan.png) |
398
-
399
- A static site (`frontend/`) — no build step. Pages:
400
-
401
- - **Landing** — hero, in-browser live scanner, feature pillars (free, no paywall).
402
- - **Auth** — login, register, forgot/reset password.
403
- - **Dashboard** — Overview (risk score, totals, trend chart, recent scans),
404
- Scans (paginated), Findings (filterable), Settings (API key + account).
405
- - **Scan detail** — full findings table, filter by risk, export JSON/HTML/CSV/SARIF/CBOM/SVG.
406
- - **Migration plan** — findings grouped by risk with NIST replacement, standard
407
- reference, and estimated complexity.
408
- - **Research** — a public explainer of Shor/Grover/LWE/Kyber and the NIST standards.
409
-
410
- Point the dashboard at your API by editing one line in `frontend/config.js`:
411
-
412
- ```js
413
- window.QUANTUMSAFE_API = "https://quantumsafe-api.onrender.com";
414
- ```
415
-
416
- (Leave it `""` for local development — it falls back to `http://localhost:5000`.)
417
-
418
- ---
419
-
420
- ## Local development setup
421
-
422
- Requires Python 3.9+.
423
-
424
- ```bash
425
- git clone https://github.com/Danny-397/Quantamn-Safe
426
- cd Quantamn-Safe
427
-
428
- # 1) Install the shared scanner package (CLI) in editable mode
429
- pip install -e .
430
-
431
- # 2) Install backend dependencies
432
- pip install -r backend/requirements.txt
433
-
434
- # 3) Configure environment
435
- cp .env.example .env # fill in SECRET_KEY / JWT_SECRET_KEY at minimum
436
-
437
- # 4) Run the API (creates SQLite tables automatically)
438
- cd backend
439
- python app.py # http://localhost:5000 (health: /health)
440
-
441
- # 5) Serve the dashboard (any static server)
442
- cd ../frontend
443
- python -m http.server 3000 # http://localhost:3000
444
- ```
445
-
446
- ### Run the whole stack with Docker
447
-
448
- ```bash
449
- docker compose up --build
450
- # Dashboard -> http://localhost:3000 API -> http://localhost:5000
451
- ```
452
-
453
- ### Tests
454
-
455
- ```bash
456
- pip install -r requirements-dev.txt
457
- pytest -q # 65 tests; in-memory DB, no setup
458
- ```
459
-
460
- Seed a demo account so the dashboard is populated:
461
-
462
- ```bash
463
- cd backend && python seed_demo.py # demo@quantumsafe.dev / demodemo123
464
- ```
465
-
466
- Without `MAIL_SERVER` configured, verification/reset emails are printed to the
467
- server log instead of being sent — so you can develop without SMTP.
468
-
469
- ---
470
-
471
- ## Environment variables
472
-
473
- See [`.env.example`](.env.example).
474
-
475
- | Variable | Required | Where to get it |
476
- |----------|----------|-----------------|
477
- | `SECRET_KEY` | ✅ | Generate: `python -c "import secrets;print(secrets.token_hex(32))"` |
478
- | `JWT_SECRET_KEY` | ✅ | Generate the same way (use a different value) |
479
- | `DATABASE_URL` | prod | Render Postgres dashboard → *Connections* (SQLite used if unset) |
480
- | `FRONTEND_ORIGIN` | ✅ | Your dashboard URL, e.g. `https://quantumsafe.vercel.app` |
481
- | `DASHBOARD_URL` | ✅ | Same as above (used in emails) |
482
- | `API_URL` | ✅ | The deployed API URL (used for email verify links) |
483
- | `MAIL_SERVER` / `MAIL_PORT` / `MAIL_USE_TLS` | email | Your SMTP provider (e.g. `smtp.gmail.com` / 587 / true) |
484
- | `MAIL_USERNAME` / `MAIL_PASSWORD` | email | SMTP credentials (Gmail: an App Password) |
485
- | `MAIL_DEFAULT_SENDER` | email | The "from" address |
486
- | `RATELIMIT_STORAGE_URI` | optional | `memory://` (dev) or a Redis URL (prod) |
487
-
488
- ---
489
-
490
- ## Deployment
491
-
492
- [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Danny-397/Quantamn-Safe)
493
-
494
- See **[DEPLOYMENT.md](DEPLOYMENT.md)** for the full walkthrough. In short:
495
-
496
- - **CLI → PyPI:** `python -m build && twine upload dist/*`
497
- - **Backend → Render:** push the repo; Render reads [`render.yaml`](render.yaml)
498
- (web service + Postgres). Set the `sync: false` env vars in the dashboard.
499
- - **Frontend → Vercel:** set Root Directory to `frontend/`; point
500
- `frontend/config.js` at your Render API URL.
501
-
502
- ---
503
-
504
- ## Project structure
505
-
506
- ```
507
- Quantamn-Safe/
508
- ├── quantum/ # REAL quantum computing (Qiskit): the attacks themselves
509
- │ ├── shor.py # Shor's algorithm — factors N, breaks RSA
510
- │ ├── grover.py # Grover's algorithm — key-search speedup
511
- │ ├── resources.py # qubit / depth / gate-count estimation
512
- │ └── README.md
513
- ├── pqc/ # Post-quantum SOLUTION: lattice (LWE) crypto from scratch
514
- │ ├── lwe_kem.py # quantum-safe key encapsulation (the math behind Kyber)
515
- │ ├── benchmark.py # latency & sizes vs RSA / ML-KEM
516
- │ └── README.md
517
- ├── cli/ # the `quantumsafe` package (CLI + shared engine)
518
- │ ├── scanner.py # AST + regex detection
519
- │ ├── scorer.py # risk score
520
- │ ├── recommender.py # NIST recommendations
521
- │ ├── reporter.py # terminal / JSON / HTML / SARIF / CBOM / SVG output
522
- │ └── cli.py # argparse entry point
523
- ├── backend/ # Flask REST API
524
- │ ├── app.py config.py extensions.py models.py
525
- │ ├── auth.py api.py scanner_service.py
526
- │ └── requirements.txt
527
- ├── frontend/ # static dashboard (no build step)
528
- │ ├── index.html login.html dashboard.html scan.html migration.html
529
- │ ├── research.html privacy.html terms.html
530
- │ └── style.css app.js config.js
531
- ├── benchmark/ # labeled precision/recall evaluation (+ graphs/)
532
- ├── study/ # empirical scan over real open-source repos
533
- ├── docs/ # whitepaper, architecture, NIST & vuln-class mappings
534
- ├── pyproject.toml # packages cli/ as `quantumsafe`
535
- └── render.yaml .env.example README.md
536
- ```
537
-
538
- ---
539
-
540
- ## NIST PQC references
541
-
542
- - **FIPS 203** — Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM / Kyber)
543
- - **FIPS 204** — Module-Lattice-Based Digital Signature Algorithm (ML-DSA / Dilithium)
544
- - **FIPS 205** — Stateless Hash-Based Digital Signature Algorithm (SLH-DSA / SPHINCS+)
545
- - **NIST SP 800-52 Rev. 2** — TLS guidance
546
- - **NIST SP 800-131A Rev. 2** — transitioning cryptographic algorithms/key lengths
547
- - **NIST IR 8547** — transition to post-quantum cryptography standards
548
-
549
- Full reasoning per algorithm: [docs/NIST_MAPPING.md](docs/NIST_MAPPING.md).
550
-
551
- ---
552
-
553
- ## If this were a product
554
-
555
- QuantumSafe is intentionally **free and open source** — the core scan needs no
556
- account, and the CLI / GitHub Action are the primary way it's meant to be used.
557
- That's a deliberate choice, not a missing feature: a login wall would only add
558
- friction to a tool whose value is instant.
559
-
560
- For the record, the productization thinking exists even though it isn't built:
561
- the free tier would stay everything shown here (scan, score, migration plan, all
562
- exports); a paid tier would be the things that only make sense for an
563
- organization — scheduled re-scans with drift alerts, multi-repo/org dashboards,
564
- SSO, and audit-ready CBOM history for compliance. Those are operational features,
565
- not gates on the core detection, which is the part that should always be open.
566
-
567
- ## License
568
-
569
- MIT — see [LICENSE](LICENSE).
1
+ Metadata-Version: 2.4
2
+ Name: quantumsafe-scan
3
+ Version: 0.2.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/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Danny-397/Quantum-Safe/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/tags"><img src="https://img.shields.io/github/v/tag/Danny-397/Quantum-Safe?style=flat-square&logo=github&label=version&color=5b73e8" alt="Latest version"></a>
42
+ <a href="https://github.com/Danny-397/Quantum-Safe/stargazers"><img src="https://img.shields.io/github/stars/Danny-397/Quantum-Safe?style=flat-square&logo=github" alt="Stars"></a>
43
+ <img src="https://img.shields.io/github/last-commit/Danny-397/Quantum-Safe?style=flat-square&color=555" alt="Last commit">
44
+ <img src="https://img.shields.io/github/license/Danny-397/Quantum-Safe?style=flat-square&color=3fb950" alt="License: MIT">
45
+ <br>
46
+ <img src="https://img.shields.io/badge/tests-80%20passing-3fb950?style=flat-square&logo=pytest&logoColor=white" alt="80 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/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
+ ## Evaluation (does the detector actually work?)
214
+
215
+ The scanner is measured against a labeled [benchmark](benchmark/) of 18 files
216
+ across 9 languages, including adversarial decoys (crypto names in comments,
217
+ docstrings, log strings, trailing/block comments, and word-boundary traps like
218
+ `md5sumLabel`) designed to trip a naive matcher. `evaluate.py` runs the scanner
219
+ twice — a naive line-regex baseline vs. the usage-aware engine — so the
220
+ improvement is measured:
221
+
222
+ ```bash
223
+ python benchmark/evaluate.py
224
+ ```
225
+
226
+ | Configuration | FP | Precision | Recall | F1 |
227
+ |---|--:|--:|--:|--:|
228
+ | Naive line-regex baseline | 27 | 49.1% | 100% | 65.8% |
229
+ | **QuantumSafe (usage-aware)** | **0** | **100%** | **100%** | **100%** |
230
+
231
+ Usage-awareness removes 27 false positives (crypto keywords inside comments,
232
+ docstrings, and log/exception strings) without losing a true positive — and now
233
+ across **all** supported languages, not just Python: genuine string-argument
234
+ usages such as Java's `getInstance("SHA-1")` are preserved by a dedicated
235
+ recovery pass. `evaluate.py` prints the exact false
236
+ positives/negatives so the numbers are auditable, and the thresholds are enforced
237
+ by `tests/test_benchmark.py`.
238
+
239
+ **Recall is measured too.** Because a small labeled corpus can't prove recall,
240
+ `benchmark/seeded.py` runs a **mutation benchmark** with ground truth by
241
+ construction — 50 real quantum-vulnerable API calls (many idiomatic variants
242
+ per family, 7 languages) that must be detected, plus 50 comment/string decoys
243
+ that must not be. Latest run: **100% recall, 100% mutation precision**
244
+ ([RESULTS-seeded.md](benchmark/RESULTS-seeded.md)), enforced by
245
+ `tests/test_seeded.py`. Honest limits are documented in
246
+ [benchmark/README.md](benchmark/README.md) — these are regression benchmarks, not
247
+ a claim of perfection on arbitrary code.
248
+
249
+ These charts are generated from **live scanner output** by
250
+ `python benchmark/graphs/generate_graphs.py` (not hardcoded):
251
+
252
+ | Vulnerabilities by family | Severity split | Scan time vs. files |
253
+ |---|---|---|
254
+ | ![by type](benchmark/graphs/vulnerabilities_by_type.png) | ![severity](benchmark/graphs/severity_distribution.png) | ![scan time](benchmark/graphs/scan_time_vs_size.png) |
255
+
256
+ **See real scan output** — terminal table, JSON, SARIF, HTML, and an SVG risk
257
+ badge from an actual scan — in [docs/EXAMPLES.md](docs/EXAMPLES.md).
258
+
259
+ ### Real-world scan: paramiko (the SSH library)
260
+
261
+ Run against a shallow clone of [`paramiko/paramiko`](https://github.com/paramiko/paramiko)
262
+ — the SSH implementation behind Ansible, Fabric, and much of the Python ecosystem.
263
+ SSH key exchange leans on RSA, ECDSA, and Diffie-Hellman, all broken by Shor's
264
+ algorithm, which makes it a textbook "harvest now, decrypt later" target:
265
+
266
+ ```bash
267
+ quantumsafe scan --repo https://github.com/paramiko/paramiko
268
+ ```
269
+
270
+ | Metric | Result |
271
+ |---|---|
272
+ | Quantum Risk Score | **100 / 100 (Critical)** |
273
+ | Findings (usage-aware) | **110** — 89 HIGH, 6 MEDIUM, 15 LOW |
274
+ | Top algorithms | ECDSA ×23, ECC ×21, SHA-1 ×18, RSA ×15, MD5 ×10, 3DES ×6 |
275
+ | Most-affected files | `paramiko/pkey.py`, `rsakey.py`, `transport.py`, `ecdsakey.py` |
276
+
277
+ The usage-aware engine matters here: a naive line-regex reports **451 raw
278
+ matches**, but most are the same algorithms repeated in docstrings, comments, and
279
+ SSH protocol-name strings (`"ssh-rsa"`, `"ecdsa-sha2-nistp256"`). Focusing on real
280
+ code brings that to **110** findings — a ~4× noise reduction. *Honest caveat: on a
281
+ protocol library, a few of those suppressed string constants are arguably real
282
+ signals, so 110 is a deliberately conservative, code-focused count — not a claim
283
+ that the other 341 were all false positives.*
284
+
285
+ ### Real-world benchmark — 37 of the most-downloaded PyPI packages
286
+
287
+ `benchmark/realworld.py` scales the paramiko example up: it pulls the latest
288
+ sdist of 37 widely-used packages straight from the PyPI JSON API, extracts each
289
+ (nothing is built or executed), and runs the real scanner. Fully reproducible:
290
+
291
+ ```bash
292
+ python benchmark/realworld.py
293
+ ```
294
+
295
+ | Metric | Result |
296
+ |---|---|
297
+ | Packages scanned | **37** |
298
+ | Packages with ≥1 finding | **32 (86%)** |
299
+ | Python files analyzed | **10,938** |
300
+ | Total findings | **5,512** — **4,083 HIGH-risk** |
301
+ | Most common families | `ecc` ×1,709, `sha256` ×956, `rsa` ×770, `sha1` ×576, `dsa` ×355, `md5` ×351 |
302
+
303
+ Every finding is a concrete `file:line` an auditor can open — e.g. Diffie-Hellman
304
+ in `twisted/conch/ssh/transport.py`, MD5 in `requests/auth.py` (HTTP Digest), and
305
+ ECDSA throughout `paramiko`. Full per-package table and examples:
306
+ [benchmark/RESULTS-realworld.md](benchmark/RESULTS-realworld.md).
307
+
308
+ | Findings by family (colored by risk tier) | Packages with the most HIGH-risk findings |
309
+ |---|---|
310
+ | ![by family](benchmark/graphs/realworld_by_family.png) | ![top packages](benchmark/graphs/realworld_top_packages.png) |
311
+
312
+ _Charts are generated from `benchmark/realworld.json` by
313
+ `python benchmark/graphs/generate_realworld_graphs.py` — not hand-drawn._
314
+
315
+ > *Honest caveat: some of these packages **are** cryptography libraries
316
+ > (`cryptography`, `pycryptodome`, `ecdsa`, `rsa`, `pyopenssl`), so their large
317
+ > counts are expected — they implement RSA/ECC on purpose. The more telling signal
318
+ > is the *application* and *infrastructure* code that still reaches for
319
+ > quantum-vulnerable primitives: `django`, `botocore`, `pymongo`, `scrapy`,
320
+ > `celery`, `requests`, `aiohttp`. That's exactly the "harvest now, decrypt later"
321
+ > surface the tool is built to inventory.*
322
+
323
+ ### Empirical study — how widespread is the problem?
324
+
325
+ Scanning 8 widely-used open-source projects ([`study/`](study/), reproducible via
326
+ `python study/run_study.py`):
327
+
328
+ - **88%** contained at least one **HIGH-risk** (Shor-breakable) cryptographic usage.
329
+ - Average Quantum Risk Score: **61.4 / 100**.
330
+
331
+ Full results and caveats: [study/REPORT.md](study/REPORT.md).
332
+
333
+ ---
334
+
335
+ ## Quantum demonstrations (Shor & Grover)
336
+
337
+ ```bash
338
+ pip install -r quantum/requirements.txt
339
+ python quantum/shor.py # quantum order-finding factors N=15, then breaks a toy RSA key
340
+ python quantum/grover.py # recovers a hidden k-bit key in ~sqrt(2^k) steps
341
+ python quantum/resources.py # qubit count, circuit depth, gate counts vs. RSA-2048 estimates
342
+ ```
343
+
344
+ - **`shor.py`** uses quantum phase estimation over modular exponentiation to find
345
+ the order of `a mod N`, factors `N`, and reconstructs an RSA private key — the
346
+ concrete reason RSA/ECC are rated **HIGH**.
347
+ - **`grover.py`** uses amplitude amplification to search a key space in ~√N
348
+ queries, halving effective key strength — the reason AES-128/SHA-256 are **LOW**.
349
+
350
+ Honest scope: these run at small scale (factoring 15), the genuine state of the art
351
+ for end-to-end Shor. See [quantum/README.md](quantum/README.md).
352
+
353
+ ## Post-quantum solution ([`pqc/`](pqc/))
354
+
355
+ ```bash
356
+ pip install -r pqc/requirements.txt
357
+ python pqc/lwe_kem.py # Alice & Bob agree on a shared secret; an eavesdropper can't
358
+ python pqc/benchmark.py # measured latency + key/ciphertext sizes vs RSA & ML-KEM
359
+ ```
360
+
361
+ Why a quantum computer can't break it: LWE has **no periodic structure** for Shor
362
+ to exploit. See [pqc/README.md](pqc/README.md).
363
+
364
+ ---
365
+
366
+ ## CLI: install & usage
367
+
368
+ ```bash
369
+ pip install quantumsafe-scan # from PyPI once published
370
+ # or, from this repo:
371
+ pip install -e .
372
+ ```
373
+
374
+ ### Commands
375
+
376
+ ```bash
377
+ # Scan a local directory (colored terminal table)
378
+ quantumsafe scan --path ./myproject
379
+
380
+ # Scan a public GitHub repo (shallow-cloned to a temp dir, then cleaned up)
381
+ quantumsafe scan --repo https://github.com/org/app
382
+
383
+ # Write a report: JSON, HTML, SARIF, CycloneDX CBOM, or an SVG risk badge
384
+ quantumsafe scan --path ./myproject --output report.json
385
+ quantumsafe scan --path ./myproject --output report.html
386
+ quantumsafe scan --path ./myproject --output report.sarif # GitHub code scanning
387
+ quantumsafe scan --path ./myproject --output report.cbom.json # CycloneDX CBOM
388
+ quantumsafe scan --path ./myproject --output badge.svg # embeddable risk badge
389
+
390
+ # Also flag crypto reached through Python wrapper functions (data-flow analysis)
391
+ quantumsafe scan --path ./myproject --taint
392
+
393
+ # Skip paths with glob patterns (repeatable)
394
+ quantumsafe scan --path . --exclude 'tests/*' --exclude 'vendor/*'
395
+
396
+ # Fail the process (exit 1) if any HIGH finding exists — handy in CI
397
+ quantumsafe scan --path . --fail-on-high
398
+
399
+ # Try it on the bundled examples
400
+ quantumsafe scan --path examples
401
+
402
+ # Link the CLI to your dashboard, then scans auto-upload to your history
403
+ quantumsafe auth --key qs_live_xxxxxxxx --api-url https://quantumsafe-api.onrender.com
404
+ quantumsafe scan --path ./myproject # prints results AND syncs to dashboard
405
+ quantumsafe scan --path ./myproject --no-sync # local only, don't upload
406
+
407
+ # Version
408
+ quantumsafe version
409
+ ```
410
+
411
+ | Flag | Description |
412
+ |------|-------------|
413
+ | `--path` | Local directory or file to scan |
414
+ | `--repo` | Public `https://github.com/<org>/<repo>` URL |
415
+ | `--output` | Write to `.json`, `.cbom.json` (CycloneDX CBOM), `.html`, `.sarif`, or `.svg` (risk badge); terminal summary still printed |
416
+ | `--exclude` | Glob of paths to skip (repeatable) |
417
+ | `--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 |
418
+ | `--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 |
419
+ | `--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 |
420
+ | `--fail-on-high` | Exit non-zero on any HIGH finding (CI gate) |
421
+ | `--no-sync` | Don't upload the result to your linked dashboard |
422
+
423
+ After `quantumsafe auth --key <key> --api-url <your-api>`, every `quantumsafe scan`
424
+ also uploads its report to your dashboard (`POST /api/v1/scan/import`). Use
425
+ `--no-sync` to keep a scan local.
426
+
427
+ **Suppressing a finding:** add `# quantumsafe: ignore` (any comment style) to the
428
+ line.
429
+
430
+ ### Use in CI (GitHub Action)
431
+
432
+ ```yaml
433
+ - uses: Danny-397/Quantum-Safe@main
434
+ with:
435
+ path: .
436
+ exclude: tests/*,vendor/*
437
+ fail-on-high: "true"
438
+ - uses: github/codeql-action/upload-sarif@v3
439
+ with:
440
+ sarif_file: quantumsafe.sarif
441
+ ```
442
+
443
+ ---
444
+
445
+ ## API documentation
446
+
447
+ Base URL (dev): `http://localhost:5000` · all endpoints under `/api/v1`.
448
+ Authentication: **JWT** (`Authorization: Bearer <token>`) for the dashboard, or a
449
+ **CLI API key** (`X-API-Key: qs_live_...`) for the scan endpoint.
450
+
451
+ ### Auth
452
+
453
+ ```http
454
+ POST /api/v1/auth/register { "email", "password" } -> { token, user }
455
+ POST /api/v1/auth/login { "email", "password" } -> { token, user }
456
+ GET /api/v1/auth/verify?token=... -> { message }
457
+ POST /api/v1/auth/forgot { "email" } -> { message }
458
+ POST /api/v1/auth/reset { "token", "password" } -> { message }
459
+ GET /api/v1/auth/me (JWT) -> { user }
460
+ ```
461
+
462
+ ### Scanning
463
+
464
+ ```http
465
+ POST /api/v1/scan (JWT or X-API-Key)
466
+ { "repo_url": "https://github.com/org/app" } # or multipart file=<.zip>
467
+ -> { scan_id, report }
468
+
469
+ POST /api/v1/scan/import (X-API-Key) # used by the CLI to upload results
470
+ { "report": { ...quantumsafe report... } } -> { scan_id }
471
+
472
+ POST /api/v1/demo-scan (public, rate-limited) # landing-page live demo
473
+ { "code": "..." } -> { report } # runs the real engine, stores nothing
474
+
475
+ GET /api/v1/scans?page=1&per_page=20 (JWT) -> paginated list
476
+ GET /api/v1/scans/{id} (JWT) -> scan + findings
477
+ GET /api/v1/scans/{id}/export?format=json|html|csv|sarif|cbom|svg (JWT)
478
+ GET /api/v1/scans/{id}/migration (JWT) -> grouped migration plan
479
+ GET /api/v1/overview (JWT) -> dashboard stats + trend
480
+ ```
481
+
482
+ ### API key management
483
+
484
+ ```http
485
+ GET /api/v1/user/apikey (JWT) -> { has_api_key, api_key_prefix }
486
+ POST /api/v1/user/apikey (JWT) -> { api_key } # full key shown ONCE
487
+ ```
488
+
489
+ All endpoints are rate-limited; CORS is restricted to `FRONTEND_ORIGIN`. GDPR-style
490
+ endpoints (`/user/data` export, `/user/account` delete) let a user export or erase
491
+ all of their data.
492
+
493
+ ---
494
+
495
+ ## Dashboard
496
+
497
+ The dashboard, showing a **real scan of [paramiko](https://github.com/paramiko/paramiko)**
498
+ (100/100 Critical, 110 findings):
499
+
500
+ | Overview | Findings | Migration plan |
501
+ |---|---|---|
502
+ | ![Overview](docs/screenshots/overview.png) | ![Findings](docs/screenshots/findings.png) | ![Migration plan](docs/screenshots/migration-plan.png) |
503
+
504
+ A static site (`frontend/`) — no build step. Pages:
505
+
506
+ - **Landing** — hero, in-browser live scanner, feature pillars (free, no paywall).
507
+ - **Auth** — login, register, forgot/reset password.
508
+ - **Dashboard** — Overview (risk score, totals, trend chart, recent scans),
509
+ Scans (paginated), Findings (filterable), Settings (API key + account).
510
+ - **Scan detail** — full findings table, filter by risk, export JSON/HTML/CSV/SARIF/CBOM/SVG.
511
+ - **Migration plan** — findings grouped by risk with NIST replacement, standard
512
+ reference, and estimated complexity.
513
+ - **Research** — a public explainer of Shor/Grover/LWE/Kyber and the NIST standards.
514
+
515
+ Point the dashboard at your API by editing one line in `frontend/config.js`:
516
+
517
+ ```js
518
+ window.QUANTUMSAFE_API = "https://quantumsafe-api.onrender.com";
519
+ ```
520
+
521
+ (Leave it `""` for local development — it falls back to `http://localhost:5000`.)
522
+
523
+ ---
524
+
525
+ ## Local development setup
526
+
527
+ Requires Python 3.9+.
528
+
529
+ ```bash
530
+ git clone https://github.com/Danny-397/Quantum-Safe
531
+ cd Quantum-Safe
532
+
533
+ # 1) Install the shared scanner package (CLI) in editable mode
534
+ pip install -e .
535
+
536
+ # 2) Install backend dependencies
537
+ pip install -r backend/requirements.txt
538
+
539
+ # 3) Configure environment
540
+ cp .env.example .env # fill in SECRET_KEY / JWT_SECRET_KEY at minimum
541
+
542
+ # 4) Run the API (creates SQLite tables automatically)
543
+ cd backend
544
+ python app.py # http://localhost:5000 (health: /health)
545
+
546
+ # 5) Serve the dashboard (any static server)
547
+ cd ../frontend
548
+ python -m http.server 3000 # http://localhost:3000
549
+ ```
550
+
551
+ ### Run the whole stack with Docker
552
+
553
+ ```bash
554
+ docker compose up --build
555
+ # Dashboard -> http://localhost:3000 API -> http://localhost:5000
556
+ ```
557
+
558
+ ### Tests
559
+
560
+ ```bash
561
+ pip install -r requirements-dev.txt
562
+ pytest -q # 80 tests; in-memory DB, no setup
563
+ ```
564
+
565
+ Seed a demo account so the dashboard is populated:
566
+
567
+ ```bash
568
+ cd backend && python seed_demo.py # demo@quantumsafe.dev / demodemo123
569
+ ```
570
+
571
+ Without `MAIL_SERVER` configured, verification/reset emails are printed to the
572
+ server log instead of being sent — so you can develop without SMTP.
573
+
574
+ ---
575
+
576
+ ## Environment variables
577
+
578
+ See [`.env.example`](.env.example).
579
+
580
+ | Variable | Required | Where to get it |
581
+ |----------|----------|-----------------|
582
+ | `SECRET_KEY` | ✅ | Generate: `python -c "import secrets;print(secrets.token_hex(32))"` |
583
+ | `JWT_SECRET_KEY` | ✅ | Generate the same way (use a different value) |
584
+ | `DATABASE_URL` | prod | Render Postgres dashboard → *Connections* (SQLite used if unset) |
585
+ | `FRONTEND_ORIGIN` | ✅ | Your dashboard URL, e.g. `https://quantumsafescan.com` |
586
+ | `DASHBOARD_URL` | ✅ | Same as above (used in emails) |
587
+ | `API_URL` | ✅ | The deployed API URL (used for email verify links) |
588
+ | `MAIL_SERVER` / `MAIL_PORT` / `MAIL_USE_TLS` | email | Your SMTP provider (e.g. `smtp.gmail.com` / 587 / true) |
589
+ | `MAIL_USERNAME` / `MAIL_PASSWORD` | email | SMTP credentials (Gmail: an App Password) |
590
+ | `MAIL_DEFAULT_SENDER` | email | The "from" address |
591
+ | `RATELIMIT_STORAGE_URI` | optional | `memory://` (dev) or a Redis URL (prod) |
592
+
593
+ ---
594
+
595
+ ## Deployment
596
+
597
+ [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Danny-397/Quantum-Safe)
598
+
599
+ See **[DEPLOYMENT.md](DEPLOYMENT.md)** for the full walkthrough. In short:
600
+
601
+ - **CLI → PyPI:** `python -m build && twine upload dist/*`
602
+ - **Backend → Render:** push the repo; Render reads [`render.yaml`](render.yaml)
603
+ (web service + Postgres). Set the `sync: false` env vars in the dashboard.
604
+ - **Frontend → Vercel:** set Root Directory to `frontend/`; point
605
+ `frontend/config.js` at your Render API URL.
606
+
607
+ ---
608
+
609
+ ## Project structure
610
+
611
+ ```
612
+ Quantum-Safe/
613
+ ├── quantum/ # REAL quantum computing (Qiskit): the attacks themselves
614
+ │ ├── shor.py # Shor's algorithm — factors N, breaks RSA
615
+ │ ├── grover.py # Grover's algorithm — key-search speedup
616
+ │ ├── resources.py # qubit / depth / gate-count estimation
617
+ │ └── README.md
618
+ ├── pqc/ # Post-quantum SOLUTION: lattice (LWE) crypto from scratch
619
+ │ ├── lwe_kem.py # quantum-safe key encapsulation (the math behind Kyber)
620
+ │ ├── benchmark.py # latency & sizes vs RSA / ML-KEM
621
+ │ └── README.md
622
+ ├── cli/ # the `quantumsafe` package (CLI + shared engine)
623
+ │ ├── scanner.py # AST + regex detection, cross-language usage-awareness
624
+ │ ├── dependencies.py # dependency + lockfile crypto scanning (purl + CBOM)
625
+ │ ├── reachability.py # reachability ranking (reachable/test/unreferenced)
626
+ │ ├── taint.py # intra-module data-flow (wrapper) analysis
627
+ │ ├── callgraph.py # whole-program cross-file taint (import resolution)
628
+ │ ├── scorer.py # risk score
629
+ │ ├── recommender.py # NIST family-level recommendations
630
+ │ ├── remediation.py # call-site-specific fixes (before/after)
631
+ │ ├── reporter.py # terminal / JSON / HTML / SARIF / CBOM / SVG output
632
+ │ └── cli.py # argparse entry point
633
+ ├── backend/ # Flask REST API
634
+ │ ├── app.py config.py extensions.py models.py
635
+ │ ├── auth.py api.py scanner_service.py
636
+ │ └── requirements.txt
637
+ ├── frontend/ # static dashboard (no build step)
638
+ │ ├── index.html login.html dashboard.html scan.html migration.html
639
+ │ ├── research.html privacy.html terms.html
640
+ │ └── style.css app.js config.js
641
+ ├── benchmark/ # labeled precision/recall evaluation (+ graphs/)
642
+ ├── study/ # empirical scan over real open-source repos
643
+ ├── docs/ # whitepaper, architecture, NIST & vuln-class mappings
644
+ ├── pyproject.toml # packages cli/ as `quantumsafe`
645
+ └── render.yaml .env.example README.md
646
+ ```
647
+
648
+ ---
649
+
650
+ ## NIST PQC references
651
+
652
+ - **FIPS 203** — Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM / Kyber)
653
+ - **FIPS 204** — Module-Lattice-Based Digital Signature Algorithm (ML-DSA / Dilithium)
654
+ - **FIPS 205** — Stateless Hash-Based Digital Signature Algorithm (SLH-DSA / SPHINCS+)
655
+ - **NIST SP 800-52 Rev. 2** — TLS guidance
656
+ - **NIST SP 800-131A Rev. 2** — transitioning cryptographic algorithms/key lengths
657
+ - **NIST IR 8547** — transition to post-quantum cryptography standards
658
+
659
+ Full reasoning per algorithm: [docs/NIST_MAPPING.md](docs/NIST_MAPPING.md).
660
+
661
+ ---
662
+
663
+ ## If this were a product
664
+
665
+ QuantumSafe is intentionally **free and open source** — the core scan needs no
666
+ account, and the CLI / GitHub Action are the primary way it's meant to be used.
667
+ That's a deliberate choice, not a missing feature: a login wall would only add
668
+ friction to a tool whose value is instant.
669
+
670
+ For the record, the productization thinking exists even though it isn't built:
671
+ the free tier would stay everything shown here (scan, score, migration plan, all
672
+ exports); a paid tier would be the things that only make sense for an
673
+ organization — scheduled re-scans with drift alerts, multi-repo/org dashboards,
674
+ SSO, and audit-ready CBOM history for compliance. Those are operational features,
675
+ not gates on the core detection, which is the part that should always be open.
676
+
677
+ ## License
678
+
679
+ MIT — see [LICENSE](LICENSE).