<p align="center">
  <h1 align="center">PQC Posture Scanner</h1>
  <p align="center">
    <strong>Scan any codebase for quantum-vulnerable cryptography. Get a grade. Know your risk.</strong>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/pqc-posture/"><img src="https://img.shields.io/pypi/v/pqc-posture?color=blue" alt="PyPI version"></a>
    <img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+">
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License: MIT"></a>
    <img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests: passing">
    <img src="https://img.shields.io/badge/zero%20dependencies-yes-brightgreen.svg" alt="Zero dependencies">
    <a href="https://github.com/Miles0sage/quantum-mcp/actions"><img src="https://img.shields.io/badge/GitHub%20Action-ready-purple.svg" alt="GitHub Action"></a>
  </p>
</p>

---

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

```bash
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`](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

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

### JSON output

```bash
pqc-scan . --json
pqc-scan . --format json
```

### SARIF for GitHub Code Scanning

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

### CBOM export (CycloneDX 1.6)

```bash
pqc-scan . --cbom CBOM.json
```

### CI gate -- fail on risk level

```bash
# 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

```bash
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

```bash
# 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`:

```yaml
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`):

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

**VS Code** (`.vscode/mcp.json`):

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

Start the server:

```bash
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

```bash
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](https://github.com/Miles0sage/quantum-mcp/issues) and we'll add it to the State of Quantum Readiness report.
