pqc-posture 0.3.0

Post-Quantum Cryptography Posture Scanner — find quantum-vulnerable crypto in your codebase

PQC Posture Scanner

Scan any codebase for quantum-vulnerable cryptography. Get a grade. Know your risk.

---

Static analysis tool that finds RSA, ECDSA, Diffie-Hellman, weak hashes, broken TLS, and 131 other quantum-vulnerable patterns across 18 algorithm categories. Context-aware: separates test code from production code. Outputs SARIF for GitHub Code Scanning, CycloneDX CBOM, and JSON. Zero external dependencies. One pip install. Works in CI.

Quick Demo

$ pqc-scan /path/to/django

======================================================================
  PQC POSTURE REPORT
======================================================================

  QUANTUM RISK GRADE: F (100/100)
  [##################################################]

  Files scanned:       2,982
  Files with crypto:   16
  Total findings:      24
  Scan time:           1,204ms

  QUANTUM EXPOSURE:
    BROKEN (quantum defeats):    1
    WEAKENED (quantum degrades): 23
    SAFE (quantum-resistant):    0

  PRODUCTION vs TEST:
    Production findings: 24 (ACTION REQUIRED)
    Test-only findings:  0

  MIGRATION PRIORITY (top 3):
  CRITICAL   operation  ECDSA              django/utils/crypto.py       ML-DSA 65 (CRYSTALS-Dili
  HIGH       reference  MD5                django/contrib/auth/hash...  SHA-256 or SHA-3-256 min
  HIGH       reference  SHA-1              django/utils/crypto.py       SHA-256 or SHA-3-256 min

======================================================================
  VERDICT: CRITICAL quantum exposure. Migration urgently recommended.
======================================================================

Install

pip install pqc-posture

No dependencies. Python 3.8+. That's it.

Why This Matters

NIST finalized post-quantum standards (FIPS 203 ML-KEM, FIPS 204 ML-DSA) in August 2024. Every RSA key, every ECDSA signature, every Diffie-Hellman exchange is now on a deprecation clock. Harvest-now-decrypt-later attacks mean data encrypted today with vulnerable algorithms is already at risk -- adversaries capture traffic now and decrypt it when quantum hardware matures. OMB M-23-02 mandates federal agencies submit annual cryptographic inventories. The migration deadline isn't "when quantum computers are ready." It's now.

Proven Results: 7 Major Projects Scanned

We scanned 385,000+ GitHub stars worth of production software. 86% need migration.

Project	Stars	Risk Score	Grade	Prod Findings	Quantum-BROKEN	Verdict
HashiCorp Vault	31K	100/100	F	536	701	MIGRATE NOW
Keycloak	25K	100/100	F	536	1,702	MIGRATE NOW
Nextcloud	28K	100/100	F	210	24	MIGRATE NOW
Django	82K	100/100	F	24	1	MIGRATE NOW
Requests	53K	60/100	D+	6	0	MIGRATE NOW
Flask	84K	30/100	B	3	0	PLAN
FastAPI	82K	0/100	A+	0	0	CLEAN

FastAPI's zero findings also validate scanner precision: zero false positives across 1,174 files.

Full methodology and per-project breakdowns: STATE_OF_QUANTUM_READINESS_2026.md

What It Detects

131 regex patterns across 18 algorithm groups in 5 categories.

Category	Algorithms	Risk	Quantum Status
Key Exchange	RSA (18 patterns), Diffie-Hellman (5), ECDH (4), SSH RSA/ECDSA keys (10)	CRITICAL	BROKEN
Signatures	ECDSA (9), RSA Signature (5), DSA (3), Ed25519 (4), X.509 Certs (11)	CRITICAL	BROKEN
Hashes	MD5 (10), SHA-1 (10)	HIGH	WEAKENED
Symmetric	DES/3DES (7), AES-128 (3), AES-256 (3)	HIGH-LOW	WEAKENED-SAFE
Protocols	TLS 1.0/1.1 (8), Weak TLS Config (7), JWT RS/ES (6)	CRITICAL-HIGH	BROKEN
Dependencies	Crypto library imports (8)	MEDIUM	WEAKENED

Languages supported: Python, JavaScript/TypeScript, Java, Go, Rust, Ruby, PHP, C/C++, Shell, plus YAML/TOML/HCL/Terraform configs.

Usage

Basic scan

pqc-scan .
pqc-scan /path/to/project

JSON output

pqc-scan . --json
pqc-scan . --format json

SARIF for GitHub Code Scanning

pqc-scan . --format sarif > results.sarif
pqc-scan . --sarif results.sarif

CBOM export (CycloneDX 1.6)

pqc-scan . --cbom CBOM.json

CI gate -- fail on risk level

# Fail if any CRITICAL findings exist
pqc-scan . --fail-on CRITICAL

# Fail if grade is C or worse
pqc-scan . --fail-on-grade C

TLS endpoint scan

pqc-scan --tls example.com
pqc-scan --tls example.com:8443
pqc-scan --tls example.com --json

Checks TLS version, cipher suite, certificate algorithm, key size, PQC key exchange support, and certificate expiry.

Context filtering

# Production code only (skip test files)
pqc-scan . --context prod

# Only HIGH and CRITICAL findings
pqc-scan . --min-risk HIGH

# Combined
pqc-scan . --context prod --min-risk HIGH --fail-on CRITICAL

GitHub Action

Drop this into .github/workflows/pqc-scan.yml:

name: PQC Posture Scan
on: [push, pull_request]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  pqc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: Miles0sage/quantum-mcp@main
        id: scan
        with:
          path: "."
          fail-on: "CRITICAL"
          format: "sarif"

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: pqc-results.sarif
          category: pqc-posture

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: crypto-bill-of-materials
          path: CBOM.json

Action outputs: risk-score, risk-level, findings-count, production-findings -- use them in downstream steps. PR comments are posted automatically with scan results.

MCP Server (AI Agent Integration)

PQC Posture Scanner also runs as an MCP server, giving AI agents (Claude, VS Code Copilot) direct access to crypto scanning.

Claude Desktop (~/.claude.json):

{
  "mcpServers": {
    "quantum": {
      "url": "http://localhost:8200",
      "tools": ["quantum_pqc_scan"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "quantum": {
      "url": "http://localhost:8200"
    }
  }
}

Start the server:

pip install fastapi uvicorn
python3 server.py
# MCP server running on http://localhost:8200

Additional MCP tools: quantum_random (true quantum RNG), quantum_backends (IBM/Origin QPU status), quantum_circuit (OpenQASM execution).

How It Works

Context-Aware Scanning

Not all crypto findings are equal. A hashlib.md5 in a test fixture is not the same as one in your auth module. The scanner classifies every finding:

Context	Description	Risk Adjustment
operation	Active crypto operations (generate, sign, encrypt)	Full risk
import	Library imports -- the dependency is real	Full risk
config	Config files (YAML, TOML, nginx.conf)	Full risk
reference	Code references to crypto algorithms	Full risk
test	Test/fixture/mock code	Demoted (CRITICAL->MEDIUM)
comment	Comments, TODOs, docs mentioning crypto	Demoted to LOW

Risk Scoring

Score = SUM(production findings * weight) + SUM(test findings * reduced weight)

Production weights: CRITICAL=25, HIGH=10, MEDIUM=3, LOW=1
Test weights:       CRITICAL=3,  HIGH=1,  MEDIUM=0, LOW=0

Score capped at 100.

Grading Scale

Grade	Score	Meaning
A+	0	Quantum-safe. Zero findings.
A	1-5	Minimal exposure.
B+	6-15	Low exposure.
B	16-25	Some quantum-vulnerable crypto.
C+	26-40	Moderate exposure. Plan migration.
C	41-50	Significant exposure.
D+	51-65	High exposure. Migration recommended.
D	66-80	Serious exposure. Migrate soon.
F+	81-90	Critical exposure.
F	91-100	Pervasive quantum-vulnerable crypto. Migrate now.

Comparison

Feature	PQC Posture	crypto-scanner	PostQuant	IBM QSE	SandboxAQ
Open source	Yes	Yes	No	No	No
Zero dependencies	Yes	No	No	No	No
Context-aware (test vs prod)	Yes	No	No	No	Partial
SARIF output	Yes	No	No	Yes	No
CycloneDX CBOM	Yes	No	No	Yes	Yes
GitHub Action	Yes	No	No	No	No
MCP server (AI agents)	Yes	No	No	No	No
TLS endpoint scanning	Yes	No	No	No	Yes
CI gate (--fail-on)	Yes	No	No	Yes	No
Letter grading	Yes	No	No	No	No
131+ patterns	Yes	~20	Unknown	~40	Unknown
Languages (8+)	Yes	Python only	Java only	Java/Python	Multi
Price	Free	Free	Paid	Paid	Paid

Roadmap

Version	Features	Status
v0.1	131 patterns, SARIF, CBOM, GitHub Action, CLI, MCP server	Shipped
v0.2	TLS scanning, letter grading, --fail-on-grade	Shipped
v0.3	AST-based analysis (not just regex), call-graph tracing	Planned
v0.4	Auto-fix engine: generate migration PRs	Planned
v1.0	Enterprise dashboard, team tracking, trend analysis	Planned

Contributing

Add a detection pattern

1. Add regex pattern(s) to CRYPTO_PATTERNS in pqc_posture.py
2. Add a test case to stress_test.py
3. Run: python3 stress_test.py && python3 stress_test_v2.py
4. Open a PR

Run tests

python3 stress_test.py      # Core pattern tests
python3 stress_test_v2.py   # Extended patterns (SSH, certs, TLS config)
python3 stress_test_v3.py   # Edge cases and regression tests

Project structure

pqc_posture.py      # Core scanner engine (131 patterns, scoring, CBOM)
pqc_scan_cli.py     # CLI entry point (pqc-scan command)
tls_scanner.py      # TLS endpoint analysis (zero deps, stdlib only)
server.py           # MCP server (FastAPI)
action.yml          # GitHub Action definition
setup.py            # Package config
pyproject.toml      # Build config

License

MIT -- use it, fork it, ship it. If you find quantum-vulnerable crypto in a major project, open an issue and we'll add it to the State of Quantum Readiness report.