Metadata-Version: 2.4
Name: pqc-sandbox
Version: 0.1.0
Summary: Simulate a post-quantum cryptography migration on your own system before committing to it
Author: pqc-sandbox contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/Deaksh/pqc-sandbox
Project-URL: Issues, https://github.com/Deaksh/pqc-sandbox/issues
Keywords: post-quantum,cryptography,pqc,ml-kem,ml-dsa,slh-dsa,security,migration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: jinja2>=3.1
Requires-Dist: psutil>=5.9
Requires-Dist: cryptography>=41.0
Requires-Dist: requests>=2.31
Provides-Extra: oqs
Requires-Dist: liboqs-python>=0.10.0; extra == "oqs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# pqc-sandbox

**See exactly what happens to your latency, payload size, CPU, and compatibility when you switch to ML-KEM / ML-DSA / SLH-DSA — in 60 seconds, without changing a line of production code.**

[![PQC Migration: MODERATE](https://img.shields.io/badge/PQC%20Migration-MODERATE-yellow?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiA3bDEwIDUgMTAtNS0xMC01ek0yIDE3bDEwIDUgMTAtNS0xMC01LTEwIDV6TTIgMTJsMTAgNSAxMC01LTEwLTUtMTAgNXoiIGZpbGw9IndoaXRlIi8+PC9zdmc+)](https://github.com/Deaksh/pqc-sandbox)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![Zero Telemetry](https://img.shields.io/badge/telemetry-zero-brightgreen)](https://github.com/Deaksh/pqc-sandbox)

```
🔒 Zero cloud. Zero telemetry. Runs entirely on your machine.
```

---

## The 60-second demo

```bash
pip install pqc-sandbox
pqc-sandbox demo
```

> **No NIST keys. No API calls. No account required.**
> All analysis is local. All benchmarks run on your hardware.

The demo simulates migrating a web API server from ECDSA-P256 → ML-DSA-44 (NIST FIPS 204) and ECDH-P256 → ML-KEM-768 (NIST FIPS 203), showing you the real cost before you touch a single config file.

---

## What it does

pqc-sandbox is **the missing second half of the PQC migration toolchain**. Crypto discovery tools (Semgrep, CodeQL, Cryptosense) tell you _what_ to change. pqc-sandbox tells you **what happens when you do**.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Discovery tools (CBOM/SARIF)        pqc-sandbox                    │
│  ─────────────────────────  ──────────────────────────────────────  │
│  "You use ECDSA-P256 here"  → "Here's what ML-DSA-44 costs you:   │
│                                  +33× signature size                │
│                                  +1.8× signing time                 │
│                                  CAUTION: cert spans 2 MTU packets  │
│                                  Score: MODERATE (38/100)"          │
└─────────────────────────────────────────────────────────────────────┘
```

### Core output per migration

| Output | Description |
|--------|-------------|
| **Benchmark table** | Side-by-side latency, key sizes, artifact sizes: classical vs. PQC |
| **Hybrid simulation** | Classical + PQC in tandem — the recommended transitional approach |
| **Compatibility oracle** | Flags what will break: MTU limits, TLS version, RAM, DNSSEC, JWTs, HSMs |
| **Migration Difficulty Score** | 0–100, badge-ready: `EASY / MODERATE / HARD / CRITICAL` |
| **Config diff** | Copy-paste ready: OpenSSL, nginx, sshd, Go TLS, Python |
| **HTML report** | Self-contained, screenshot-friendly, shareable |
| **JSON output** | CI/CD pipeline integration with exit codes |

---

## Installation

```bash
# Basic (simulation mode — no native deps)
pip install pqc-sandbox

# With real benchmarks via liboqs
pip install pqc-sandbox[oqs]
# Requires liboqs to be installed: https://github.com/open-quantum-safe/liboqs
```

### liboqs (optional but recommended)

When `liboqs-python` is installed, pqc-sandbox runs **real NIST reference implementations** instead of simulated timings. In simulation mode, timings are derived from published NIST benchmarks with ±5% jitter — accurate for planning, but not a substitute for hardware measurement.

```bash
# macOS
brew install liboqs
pip install liboqs-python

# Ubuntu/Debian
sudo apt-get install liboqs-dev
pip install liboqs-python
```

---

## Usage

### `pqc-sandbox demo` — Start here

```bash
# Default: web API server scenario (ECDH-P256 → ML-KEM-768, ECDSA-P256 → ML-DSA-44)
pqc-sandbox demo

# IoT device with 256 KB RAM
pqc-sandbox demo --scenario 1

# Legacy TLS 1.2 endpoint
pqc-sandbox demo --scenario 2

# Save reports
pqc-sandbox demo --html report.html --json report.json
```

### `pqc-sandbox compare` — Compare any two algorithms

```bash
# Auto-select PQC replacement
pqc-sandbox compare --classical "ECDH-P256"

# Explicit pairing
pqc-sandbox compare --classical "ECDSA-P256" --pqc "ML-DSA-65"

# With system constraints
pqc-sandbox compare \
  --classical "ECDSA-P256" --pqc "ML-DSA-44" \
  --mtu 1500 \
  --tls-version 1.3 \
  --protocol tls \
  --ram-kb 256 \
  --tag embedded --tag iot

# Generate all outputs
pqc-sandbox compare \
  --classical "ECDH-P256" --pqc "ML-KEM-768" \
  --html report.html \
  --json report.json \
  --diff openssl.conf.patch \
  --diff-format openssl

# CI/CD mode (exit code: 0=GO, 1=CAUTION, 2=BLOCKED)
pqc-sandbox compare --classical "ECDH-P256" --ci
```

### `pqc-sandbox scan tls` — Probe a live endpoint

```bash
# Detect current algorithms and simulate migration
pqc-sandbox scan tls example.com
pqc-sandbox scan tls api.mycompany.com --port 8443 --html tls_report.html
```

### `pqc-sandbox scan cbom` — Integrate with CBOM scanners

```bash
# Accept CycloneDX CBOM JSON (from Dependency-Track, Cryptosense, etc.)
pqc-sandbox scan cbom cryptographic-bill-of-materials.json

# Sample CBOM included
pqc-sandbox scan cbom assets/sample.cbom.json
```

### `pqc-sandbox scan sarif` — Integrate with SARIF crypto scanners

```bash
# Accept SARIF 2.1.0 output (from Semgrep, CodeQL, etc.)
pqc-sandbox scan sarif crypto-findings.sarif

# Sample SARIF included
pqc-sandbox scan sarif assets/sample.sarif.json
```

### `pqc-sandbox diff` — Config diff only

```bash
pqc-sandbox diff --classical "ECDH-P256" --format nginx
pqc-sandbox diff --classical "ECDSA-P256" --pqc "ML-DSA-65" --format go-tls
pqc-sandbox diff --classical "ECDH-P256" --format sshd --output sshd_config.patch
```

Supported formats: `openssl`, `nginx`, `sshd`, `go-tls`, `python`

### `pqc-sandbox badge` — Generate README badge

```bash
pqc-sandbox badge --classical "ECDSA-P256"
# Output:
#   Score: 38/100 — MODERATE
#   ![PQC Migration: MODERATE](https://img.shields.io/...)
```

### `pqc-sandbox list` — Show all algorithms

```bash
pqc-sandbox list
pqc-sandbox list --pqc-only
pqc-sandbox list --classical-only --category kem
```

---

## Supported algorithms

### PQC (NIST standards)

| Algorithm | Standard | Category | Security Level |
|-----------|----------|----------|----------------|
| ML-KEM-512 | NIST FIPS 203 | KEM | 1 |
| **ML-KEM-768** ⭐ | NIST FIPS 203 | KEM | 3 |
| ML-KEM-1024 | NIST FIPS 203 | KEM | 5 |
| ML-DSA-44 | NIST FIPS 204 | Signature | 2 |
| **ML-DSA-65** ⭐ | NIST FIPS 204 | Signature | 3 |
| ML-DSA-87 | NIST FIPS 204 | Signature | 5 |
| SLH-DSA-SHA2-128s | NIST FIPS 205 | Signature | 1 |
| SLH-DSA-SHA2-128f | NIST FIPS 205 | Signature | 1 |
| SLH-DSA-SHA2-256s | NIST FIPS 205 | Signature | 5 |

⭐ = recommended for most deployments

### Classical (for comparison)

ECDH-P256, ECDH-P384, RSA-2048, ECDSA-P256, ECDSA-P384, RSA-2048 PKCS#1 v1.5, RSA-4096 PKCS#1 v1.5, Ed25519

---

## The size problem (why this tool exists)

The PQC migration is not like past algorithm transitions. The size increases are **structural**:

```
                  Public key    Signature/Ciphertext
ECDSA-P256        65 B          72 B
ML-DSA-44         1,312 B       2,420 B       ← 33× larger
ML-DSA-65         1,952 B       3,293 B       ← 45× larger
SLH-DSA-SHA2-128s 32 B          7,856 B       ← 109× larger
SLH-DSA-SHA2-256s 64 B          29,792 B      ← 413× larger

ECDH-P256 ciphertext:  65 B
ML-KEM-768 ciphertext: 1,088 B                ← 17× larger
```

A TLS handshake that fit in a single 1500-byte MTU packet will **fragment**. DNSSEC records that fit in a single UDP packet will **require TCP fallback**. JWT tokens will **overflow HTTP header limits**. pqc-sandbox finds these issues before they find you in production.

---

## Compatibility oracle checks

| Category | What's checked |
|----------|---------------|
| **MTU / fragmentation** | Does the ML-KEM ClientHello + TLS overhead exceed your MTU? |
| **TLS version** | TLS 1.0/1.1 cannot support hybrid PQC key exchange |
| **Memory (embedded)** | Does your RAM support SLH-DSA's ~256 KB stack requirement? |
| **DNSSEC** | ML-DSA signatures exceed DNS UDP limits — TCP fallback required |
| **JWT / HTTP** | Large PQC signatures overflow default header size limits |
| **CMS / S/MIME** | Parser buffer limits for large PQC-signed content |
| **HSM support** | HSMs typically lag 12-24 months — flags if vendor support is unclear |
| **Legacy TLS stacks** | OpenSSL < 3.x has no PQC support |

---

## CI/CD integration

```yaml
# GitHub Actions example
- name: PQC Migration Check
  run: |
    pip install pqc-sandbox
    pqc-sandbox compare \
      --classical "ECDH-P256" \
      --pqc "ML-KEM-768" \
      --json pqc-report.json \
      --ci   # exit 1 on CAUTION, exit 2 on BLOCKED

- name: Upload PQC Report
  uses: actions/upload-artifact@v3
  with:
    name: pqc-migration-report
    path: pqc-report.json
```

The JSON output includes a `ci.exit_code` field:
- `0` = GO (migration looks clean)
- `1` = CAUTION (issues to review, but not blocking)
- `2` = BLOCKED (hard blockers detected)

---

## Using as a library

```python
from pqc_sandbox.benchmarks import run_comparison
from pqc_sandbox.compat import run_compat_check, SystemConstraints
from pqc_sandbox.hybrid import simulate_hybrid
from pqc_sandbox.scoring import compute_score
from pqc_sandbox.algorithms import ALL_ALGORITHMS
from pqc_sandbox.report import print_report, generate_html, generate_json

# Benchmark comparison
cmp = run_comparison("ECDH-P256", "ML-KEM-768", iterations=100)
print(f"Ciphertext size ratio: {cmp.artifact_ratio:.1f}×")
print(f"KeyGen slowdown: {cmp.keygen_slowdown:.1f}×")

# Compatibility check
constraints = SystemConstraints(
    mtu_bytes=1500,
    tls_version="1.3",
    ram_kb=None,         # unconstrained
    protocol="tls",
    tags=["hsm"],
)
compat = run_compat_check(ALL_ALGORITHMS["ML-KEM-768"], constraints)
print(f"Verdict: {compat.verdict}")
for issue in compat.issues:
    print(f"  {issue.severity.value}: {issue.title}")

# Hybrid simulation
hybrid = simulate_hybrid("ECDH-P256", "ML-KEM-768")
print(f"Hybrid wire overhead: +{hybrid.wire_overhead_bytes:,} bytes")

# Migration difficulty score
score = compute_score(comparison=cmp, compat=compat, hybrid=hybrid)
print(f"Migration difficulty: {score.score}/100 ({score.label})")
print(f"Badge: {score.badge_markdown}")

# Generate reports
generate_html(cmp, compat, hybrid, score, output_path="report.html")
generate_json(cmp, compat, hybrid, score, output_path="report.json")
```

---

## Architecture

```
pqc_sandbox/
├── algorithms.py          # Algorithm catalogue: sizes, perf baselines, migration map
├── cli.py                 # Click CLI (demo, compare, scan, list, diff, badge)
├── scoring.py             # Migration Difficulty Score (0-100) + badge generator
├── benchmarks/
│   └── runner.py          # liboqs runner + NIST-baseline simulation fallback
├── compat/
│   └── oracle.py          # Compatibility checks: MTU, TLS version, RAM, protocol
├── hybrid/
│   └── simulator.py       # Hybrid (classical+PQC) key exchange simulation
├── inputs/
│   ├── tls_probe.py       # Live TLS endpoint probing via stdlib ssl
│   ├── cbom.py            # CycloneDX CBOM parser
│   └── sarif.py           # SARIF 2.1.0 parser
├── report/
│   ├── terminal.py        # Rich terminal renderer
│   ├── html_gen.py        # Self-contained HTML report (no CDN)
│   ├── json_out.py        # JSON output for CI/CD
│   └── config_diff.py     # Copy-paste config diffs (OpenSSL, nginx, sshd, Go, Python)
└── demo/
    └── runner.py          # 60-second bundled demo scenarios
```

**Dependencies:** `click`, `rich`, `psutil`, `cryptography`, `jinja2`, `requests`
**Optional:** `liboqs-python` (for real NIST reference implementation benchmarks)

---

## Out of scope (by design)

pqc-sandbox does **not** scan your codebase for crypto usage — excellent tools already do that:

- [Semgrep crypto rules](https://semgrep.dev/p/cryptography)
- [CodeQL crypto queries](https://codeql.github.com/)
- [Cryptosense Analyzer](https://cryptosense.com/)
- [IBM CBOM tools](https://github.com/IBM/cbomkit)

Feed their CBOM or SARIF output directly to `pqc-sandbox scan cbom` / `pqc-sandbox scan sarif`.

---

## Privacy & trust

```
🔒 ZERO CLOUD  —  All benchmarks run on your hardware.
🔒 ZERO TELEMETRY  —  No data leaves your machine. Ever.
🔒 ZERO ACCOUNTS  —  No sign-up, no API keys.
🔒 OPEN SOURCE  —  Apache 2.0. Audit everything.
```

Enterprise security teams: every byte this tool processes stays on your machine. The HTML report is generated locally from an embedded template — no external stylesheets, no CDN, no fonts loaded from the internet.

---

## Contributing

```bash
git clone https://github.com/Deaksh/pqc-sandbox
cd pqc-sandbox
pip install -e ".[dev]"
python -m pytest tests/ -v
```

Pull requests welcome. Priority areas:
- Real liboqs integration tests (need liboqs installed in CI)
- Additional protocol compat checks (WireGuard, Signal Protocol, S/MIME)
- More config diff formats (HAProxy, Apache, Kubernetes TLS secrets)
- Hardware benchmark profiles (ARM Cortex-M, RISC-V, Apple Silicon)

---

## References

- [NIST FIPS 203 — ML-KEM](https://csrc.nist.gov/pubs/fips/203/final)
- [NIST FIPS 204 — ML-DSA](https://csrc.nist.gov/pubs/fips/204/final)
- [NIST FIPS 205 — SLH-DSA](https://csrc.nist.gov/pubs/fips/205/final)
- [Open Quantum Safe (liboqs)](https://openquantumsafe.org/)
- [IETF TLS Hybrid Key Exchange (draft-ietf-tls-hybrid-design)](https://datatracker.ietf.org/doc/draft-ietf-tls-hybrid-design/)
- [CNSA 2.0 — NSA Commercial National Security Algorithm Suite 2.0](https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF)
- [CycloneDX CBOM specification](https://cyclonedx.org/capabilities/cbom/)

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
