quantumsafe-scan 0.1.0__py3-none-any.whl

quantumsafe/__init__.py

@@ -0,0 +1,8 @@
+"""QuantumSafe — scan codebases for quantum-vulnerable cryptography.
+
+The importable package is ``quantumsafe`` (mapped to this ``cli/`` directory in
+pyproject.toml) so both the standalone CLI and the Flask backend share one copy
+of the detection logic.
+"""
+
+__version__ = "0.1.0"

quantumsafe/cli.py

@@ -0,0 +1,203 @@
+"""quantumsafe command-line interface.
+
+Commands:
+    quantumsafe scan --path ./project [--output report.json|report.html]
+    quantumsafe scan --repo https://github.com/org/app
+    quantumsafe version
+    quantumsafe auth --key <api-key>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from . import reporter
+from .scanner import scan_path, scan_repo
+
+CONFIG_DIR = os.path.join(os.path.expanduser("~"), ".quantumsafe")
+CONFIG_PATH = os.path.join(CONFIG_DIR, "config.json")
+
+
+# --------------------------------------------------------------------------- #
+# auth — store API key linking the CLI to a dashboard account
+# --------------------------------------------------------------------------- #
+
+
+def _save_config(data: dict) -> None:
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    with open(CONFIG_PATH, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+    try:
+        os.chmod(CONFIG_PATH, 0o600)  # best-effort; no-op on some platforms
+    except OSError:
+        pass
+
+
+def load_config() -> dict:
+    try:
+        with open(CONFIG_PATH, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return {}
+
+
+def cmd_auth(args: argparse.Namespace) -> int:
+    key = args.key.strip()
+    if not key:
+        print("Error: --key must not be empty.", file=sys.stderr)
+        return 2
+    cfg = load_config()
+    cfg["api_key"] = key
+    if args.api_url:
+        cfg["api_url"] = args.api_url.rstrip("/")
+    _save_config(cfg)
+    print(f"API key saved to {CONFIG_PATH}")
+    print("The CLI is now linked to your QuantumSafe dashboard account.")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# scan
+# --------------------------------------------------------------------------- #
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    if bool(args.path) == bool(args.repo):
+        print("Error: provide exactly one of --path or --repo.", file=sys.stderr)
+        return 2
+
+    exclude = args.exclude or None
+    try:
+        if args.repo:
+            target = args.repo
+            findings = scan_repo(args.repo, exclude=exclude)
+        else:
+            target = os.path.abspath(args.path)
+            findings = scan_path(args.path, exclude=exclude)
+    except (FileNotFoundError, ValueError, RuntimeError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    report = reporter.build_report(findings, target)
+
+    if args.output:
+        name = args.output.lower()
+        ext = os.path.splitext(name)[1]
+        if name.endswith(".cbom.json") or name.endswith(".cdx.json"):
+            content = reporter.to_cbom(report)
+        elif ext == ".json":
+            content = reporter.to_json(report)
+        elif ext in (".html", ".htm"):
+            content = reporter.to_html(report)
+        elif ext == ".sarif":
+            content = reporter.to_sarif(report)
+        elif ext == ".svg":
+            content = reporter.to_badge_svg(report)
+        else:
+            print("Error: --output must end in .json, .cbom.json, .html, .sarif, or .svg",
+                  file=sys.stderr)
+            return 2
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        print(f"Report written to {args.output}")
+        # Also show the summary in the terminal for convenience.
+        reporter.print_terminal(report)
+    else:
+        reporter.print_terminal(report)
+
+    _maybe_sync(report, args.no_sync)
+
+    # Non-zero exit on HIGH findings so the CLI is CI-friendly.
+    return 1 if report["summary"]["high"] > 0 and args.fail_on_high else 0
+
+
+def _maybe_sync(report: dict, no_sync: bool) -> None:
+    """Upload the report to the linked dashboard (if `auth` was run with an API URL)."""
+    if no_sync:
+        return
+    cfg = load_config()
+    key, url = cfg.get("api_key"), cfg.get("api_url")
+    if not key or not url:
+        return  # not linked to a dashboard — nothing to do
+
+    import json
+    import urllib.error
+    import urllib.request
+
+    body = json.dumps({"report": report}).encode("utf-8")
+    req = urllib.request.Request(
+        url.rstrip("/") + "/api/v1/scan/import",
+        data=body,
+        headers={"Content-Type": "application/json", "X-API-Key": key},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            res = json.load(resp)
+        print(f"Synced to dashboard: scan #{res.get('scan_id')} ({url})")
+    except urllib.error.HTTPError as exc:
+        print(f"Dashboard sync failed (HTTP {exc.code}). Re-run 'quantumsafe auth' "
+              f"to reconnect.", file=sys.stderr)
+    except Exception as exc:
+        print(f"Dashboard sync skipped ({exc}).", file=sys.stderr)
+
+
+# --------------------------------------------------------------------------- #
+# version
+# --------------------------------------------------------------------------- #
+
+
+def cmd_version(_args: argparse.Namespace) -> int:
+    print(f"quantumsafe {__version__}")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# parser
+# --------------------------------------------------------------------------- #
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="quantumsafe",
+        description="Scan codebases for quantum-vulnerable cryptography.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="Scan a local path or GitHub repo.")
+    p_scan.add_argument("--path", help="Local directory or file to scan.")
+    p_scan.add_argument("--repo", help="Public GitHub repository URL to scan.")
+    p_scan.add_argument("--output",
+                        help="Write report to this file: .json, .cbom.json (CycloneDX CBOM), "
+                             ".html, .sarif, or .svg (risk badge).")
+    p_scan.add_argument("--exclude", action="append", metavar="GLOB",
+                        help="Glob of paths to skip (repeatable), e.g. --exclude 'tests/*'.")
+    p_scan.add_argument("--fail-on-high", action="store_true",
+                        help="Exit with code 1 if any HIGH-risk finding is present (for CI).")
+    p_scan.add_argument("--no-sync", action="store_true",
+                        help="Don't upload results to your linked dashboard account.")
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_version = sub.add_parser("version", help="Print the version.")
+    p_version.set_defaults(func=cmd_version)
+
+    p_auth = sub.add_parser("auth", help="Link the CLI to a dashboard account.")
+    p_auth.add_argument("--key", required=True, help="API key from your dashboard Settings page.")
+    p_auth.add_argument("--api-url", help="Override the dashboard API base URL.")
+    p_auth.set_defaults(func=cmd_auth)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quantumsafe/recommender.py

@@ -0,0 +1,150 @@
+"""NIST post-quantum migration recommendations.
+
+Each cryptographic "family" detected by the scanner maps to a concrete,
+NIST-aligned replacement, the relevant FIPS standard, and an estimated
+migration complexity. This is referenced by both the CLI reporter and the
+backend's Migration Plan endpoint, so the advice stays consistent everywhere.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Recommendation:
+    replacement: str
+    nist_reference: str
+    complexity: str  # "Low" | "Medium" | "High"
+    detail: str
+
+
+# Keyed by the rule "family" used in scanner.py.
+RECOMMENDATIONS: dict[str, Recommendation] = {
+    "rsa": Recommendation(
+        replacement="CRYSTALS-Kyber (ML-KEM) for key exchange / CRYSTALS-Dilithium (ML-DSA) for signatures",
+        nist_reference="FIPS 203 (ML-KEM), FIPS 204 (ML-DSA)",
+        complexity="High",
+        detail=(
+            "RSA is broken by Shor's algorithm on a sufficiently large quantum "
+            "computer regardless of key size. Use ML-KEM (Kyber) where RSA is "
+            "used for key transport/encryption, and ML-DSA (Dilithium) where RSA "
+            "is used for digital signatures."
+        ),
+    ),
+    "ecc": Recommendation(
+        replacement="CRYSTALS-Kyber (ML-KEM) for ECDH / CRYSTALS-Dilithium (ML-DSA) for ECDSA",
+        nist_reference="FIPS 203 (ML-KEM), FIPS 204 (ML-DSA)",
+        complexity="High",
+        detail=(
+            "Elliptic-curve cryptography (ECDSA/ECDH/ECC) is broken by Shor's "
+            "algorithm. Replace ECDH key agreement with ML-KEM (Kyber) and ECDSA "
+            "signatures with ML-DSA (Dilithium)."
+        ),
+    ),
+    "dsa": Recommendation(
+        replacement="CRYSTALS-Dilithium (ML-DSA)",
+        nist_reference="FIPS 204 (ML-DSA), FIPS 205 (SLH-DSA / SPHINCS+)",
+        complexity="High",
+        detail=(
+            "DSA signatures are broken by Shor's algorithm. Migrate to ML-DSA "
+            "(Dilithium), or SLH-DSA (SPHINCS+) where a hash-based, "
+            "conservative-assumption signature is preferred."
+        ),
+    ),
+    "dh": Recommendation(
+        replacement="CRYSTALS-Kyber (ML-KEM)",
+        nist_reference="FIPS 203 (ML-KEM)",
+        complexity="High",
+        detail=(
+            "Classic Diffie-Hellman key exchange is broken by Shor's algorithm. "
+            "Replace with ML-KEM (Kyber), optionally in a hybrid construction "
+            "with an existing classical KEX during transition."
+        ),
+    ),
+    "md5": Recommendation(
+        replacement="SHA-3 (SHA3-256) or SHA-256",
+        nist_reference="FIPS 202 (SHA-3), FIPS 180-4 (SHA-2)",
+        complexity="Low",
+        detail=(
+            "MD5 is cryptographically broken (practical collisions) and is "
+            "further weakened by Grover's algorithm. Replace with SHA-3 or SHA-256."
+        ),
+    ),
+    "sha1": Recommendation(
+        replacement="SHA-3 (SHA3-256) or SHA-256",
+        nist_reference="FIPS 202 (SHA-3), FIPS 180-4 (SHA-2)",
+        complexity="Low",
+        detail=(
+            "SHA-1 is broken (practical collisions, e.g. SHAttered) and weakened "
+            "by Grover's algorithm. Replace with SHA-3 or SHA-256."
+        ),
+    ),
+    "tls_old": Recommendation(
+        replacement="TLS 1.3",
+        nist_reference="NIST SP 800-52 Rev. 2",
+        complexity="Low",
+        detail=(
+            "TLS 1.0/1.1 are deprecated and use quantum-vulnerable key exchange. "
+            "Upgrade to TLS 1.3 and plan for hybrid PQC key exchange."
+        ),
+    ),
+    "3des": Recommendation(
+        replacement="AES-256",
+        nist_reference="FIPS 197 (AES), NIST SP 800-131A Rev. 2",
+        complexity="Low",
+        detail=(
+            "3DES/Triple-DES is deprecated and its effective security is halved "
+            "by Grover's algorithm. Replace with AES-256."
+        ),
+    ),
+    "rc4": Recommendation(
+        replacement="AES-256 (GCM)",
+        nist_reference="FIPS 197 (AES), NIST SP 800-131A Rev. 2",
+        complexity="Low",
+        detail=(
+            "RC4 is insecure and prohibited for TLS. Replace with AES-256 in an "
+            "AEAD mode such as GCM."
+        ),
+    ),
+    "sha256": Recommendation(
+        replacement="SHA-256 (acceptable) - consider SHA-384/512 or SHA3 for long-term",
+        nist_reference="FIPS 180-4 (SHA-2), FIPS 202 (SHA-3)",
+        complexity="Low",
+        detail=(
+            "Grover's algorithm reduces SHA-256's preimage resistance to ~128 "
+            "bits, which remains secure. Monitor; for long-lived data consider "
+            "SHA-384/512 or SHA-3."
+        ),
+    ),
+    "aes128": Recommendation(
+        replacement="AES-256",
+        nist_reference="FIPS 197 (AES)",
+        complexity="Low",
+        detail=(
+            "Grover's algorithm halves AES-128's effective security to ~64 bits. "
+            "Move to AES-256 for quantum-resistant symmetric encryption."
+        ),
+    ),
+    "tls12": Recommendation(
+        replacement="TLS 1.3",
+        nist_reference="NIST SP 800-52 Rev. 2",
+        complexity="Low",
+        detail=(
+            "TLS 1.2 is acceptable today but still relies on classical key "
+            "exchange. Plan migration to TLS 1.3 with hybrid PQC key exchange."
+        ),
+    ),
+}
+
+_FALLBACK = Recommendation(
+    replacement="Review against NIST PQC guidance",
+    nist_reference="NIST IR 8547 (PQC transition)",
+    complexity="Medium",
+    detail="Manually review this usage against current NIST post-quantum guidance.",
+)
+
+
+def recommend(family: str) -> Recommendation:
+    """Return the migration recommendation for a detection family."""
+    return RECOMMENDATIONS.get(family, _FALLBACK)