pqcheck 0.1.1 → 0.3.0

package/README.md

@@ -14,12 +14,17 @@ That's it. No install. Works from any terminal with Node 18+.
 
 `pqcheck` scans any HTTPS domain and computes its **Decryption Blast Radius Score** — the first continuous metric for harvest-now-decrypt-later (HNDL) risk. Every other TLS scanner answers "is post-quantum cryptography enabled?" with a yes/no. `pqcheck` answers the question that actually matters: *if an adversary harvests this traffic today and decrypts it in 2035, how much past + future data unlocks?*
 
-The score combines:
+The score combines (Quantum / cert findings — our differentiator):
+- **Public-key reuse across rotations** — detects when the same private key has been live across multiple cert renewals (often 4+ years at large enterprises). **★ Unique to pqcheck — no other ASM/TLS scanner surfaces this.**
 - **Cipher-class probing** — does the server accept RSA fallback even if it prefers ECDHE?
 - **Certificate chain analysis** — including the intermediate cert (the chain's actual quantum failure point)
-- **Public-key reuse across rotations** — detects when the same private key has been live across multiple cert renewals (often 4+ years at large enterprises)
 - **Subject scale** — wildcard certs and subdomain count multiplying the blast radius
 
+Plus a full ASM check suite for credibility (so the report doesn't feel narrow):
+- **Email security** — SPF, DMARC, DKIM (15 selectors probed), BIMI
+- **HTTP header security** — HSTS (with preload + max-age), CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP, CORP
+- **Subdomain takeover detection** — fingerprint-based scan against AWS S3, GitHub Pages, Heroku, Shopify, Fastly, and 5+ other commonly-orphaned services
+
 ## Example
 
 ```
@@ -55,20 +60,54 @@ $ npx pqcheck chase.com
 ## Usage
 
 ```
-npx pqcheck <domain>           Scan and print human-readable report
-npx pqcheck <domain> --json    Output raw JSON for piping / scripting
-npx pqcheck --help             Show all options
-npx pqcheck --version          Show version
+npx pqcheck <domain>                      Scan and print human-readable report
+npx pqcheck <domain> --format json        Output raw JSON for piping / scripting
+npx pqcheck <domain> --threshold 7        Exit 2 if score ≥ 7 (CI gate)
+npx pqcheck <domain> --quiet              Print only the numeric score
+npx pqcheck --help                        Show all options
+npx pqcheck --version                     Show version
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success — score below threshold (or no threshold set) |
+| 1    | Usage / network / scan error |
+| 2    | Score met or exceeded `--threshold` |
+
+### CI integration
+
+The `--threshold` flag turns `pqcheck` into a quantum-risk gate for any pipeline:
+
+```yaml
+# .github/workflows/quantum-risk-gate.yml
+- name: Check public-surface quantum-decryption risk
+  run: npx pqcheck mycompany.com --threshold 7
+```
+
+If the score is 7.0 or higher, the step fails and the PR can't merge.
+
+For GitHub Actions specifically, there's also a [first-class action](https://github.com/mzon7/quantapact/tree/main/action) with `score` / `grade` / `report-url` outputs:
+
+```yaml
+- uses: mzon7/quantapact/action@main
+  with:
+    domain: mycompany.com
+    threshold: '7'
+```
+
+For finer control, combine `--quiet` with shell logic:
+
+```bash
+SCORE=$(npx pqcheck mybank.com --quiet)
+echo "Public surface blast radius: $SCORE / 10"
 ```
 
-The `--json` flag is useful for integrating into CI / monitoring tools:
+Or grab the full JSON for richer analysis:
 
 ```bash
-# In a GitHub Actions workflow:
-SCORE=$(npx pqcheck mybank.com --json | jq '.score')
-if (( $(echo "$SCORE > 7" | bc -l) )); then
-  echo "Score regressed above threshold"; exit 1
-fi
+npx pqcheck mybank.com --format json | jq '.findings[] | select(.severity=="high")'
 ```
 
 ## Web version

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.1.1";
+const VERSION = "0.3.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -41,16 +41,22 @@ async function main() {
     process.exit(1);
   }
 
-  const json = args.includes("--json");
+  const quiet = args.includes("--quiet") || args.includes("-q");
+  const format = parseFormat(args);
+  const threshold = parseThreshold(args);
+  if (threshold === "invalid") {
+    console.error(color("red", "error: --threshold requires a number 0-10"));
+    process.exit(1);
+  }
 
-  process.stderr.write(color("dim", `Scanning ${domain} ...`));
+  if (!quiet) process.stderr.write(color("dim", `Scanning ${domain} ...`));
   let report;
   try {
     const resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, {
       method: "GET",
       headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION}` },
     });
-    process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
+    if (!quiet) process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
       console.error(color("red", `error: ${resp.status} ${errBody?.error || resp.statusText}`));
@@ -59,17 +65,45 @@ async function main() {
     }
     report = await resp.json();
   } catch (err) {
-    process.stderr.write("\r\x1b[K");
+    if (!quiet) process.stderr.write("\r\x1b[K");
     console.error(color("red", `error: ${err.message}`));
     process.exit(1);
   }
 
-  if (json) {
+  if (quiet) {
+    // Numeric score on stdout, nothing else. Suitable for piping.
+    console.log(typeof report.score === "number" ? report.score : "");
+  } else if (format === "json") {
     console.log(JSON.stringify(report, null, 2));
-    process.exit(0);
+  } else {
+    printReport(report);
   }
 
-  printReport(report);
+  // Threshold gating: exit 2 if score >= threshold (distinct from exit 1 = error)
+  if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
+    if (!quiet) {
+      console.error(color("red", `threshold breach: score ${report.score} >= ${threshold}`));
+    }
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+function parseFormat(args) {
+  if (args.includes("--json")) return "json"; // back-compat alias
+  const i = args.indexOf("--format");
+  if (i === -1) return "text";
+  const v = (args[i + 1] || "").toLowerCase();
+  return v === "json" ? "json" : "text";
+}
+
+function parseThreshold(args) {
+  const i = args.indexOf("--threshold");
+  if (i === -1) return null;
+  const raw = args[i + 1];
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 10) return "invalid";
+  return n;
 }
 
 function printReport(r) {
@@ -97,16 +131,47 @@ function printReport(r) {
   console.log(`  • HSTS:          ${r.publicSurface.hsts ? color("green", "enabled") : color("dim", "not detected")}`);
   console.log(`  • Subdomains:    ${r.publicSurface.subdomainCount}${r.publicSurface.wildcardCert ? color("yellow", " (wildcard cert)") : ""}`);
   console.log("");
+  // Coverage line — communicates breadth of checks
+  const coverage = ["TLS", "Cert chain", "Cipher class", color("violet", "★ Key reuse (CT-log)"), "Subdomains"];
+  if (r.emailSecurity) coverage.push("SPF", "DMARC", "DKIM", "BIMI");
+  if (r.httpHeaders && r.httpHeaders.reachable) coverage.push("HSTS", "CSP", "X-Frame", "Referrer-Policy");
+  if (r.subdomainTakeover) coverage.push("Takeover");
+  console.log(color("dim", "  Checked: ") + coverage.join(color("dim", " · ")));
+  console.log("");
+
   if (r.findings && r.findings.length) {
-    console.log(color("dim", "  Findings:"));
+    // Group findings by category. Quantum/cert findings come first since
+    // they're the differentiator; ASM-completeness findings come after.
+    const groups = { quantum: [], takeover: [], email: [], headers: [], other: [] };
     for (const f of r.findings) {
-      const sev = f.severity.toUpperCase();
-      const sevColor =
-        f.severity === "critical" ? "red" :
-        f.severity === "high"     ? "yellow" :
-        f.severity === "medium"   ? "yellow" : "dim";
-      console.log(`  ${color(sevColor, `[${sev}]`)} ${f.title}`);
-      console.log(color("dim", `    ${f.detail}`));
+      const t = (f.title || "").toLowerCase();
+      if (/spf|dmarc|dkim|bimi/.test(t)) groups.email.push(f);
+      else if (/hsts|csp|x-frame|content-?type|referrer|clickjacking|server version|permissions-policy/.test(t)) groups.headers.push(f);
+      else if (/takeover/.test(t)) groups.takeover.push(f);
+      else if (/key reused?|key persist|reused for|cert rotation|chain weakest|rsa fallback|ecdhe|quantum/.test(t)) groups.quantum.push(f);
+      else groups.other.push(f);
+    }
+    const sections = [
+      ["quantum", "Quantum & cert exposure (our differentiator):", groups.quantum],
+      ["takeover", "Subdomain takeover:", groups.takeover],
+      ["email", "Email security (SPF / DMARC / DKIM / BIMI):", groups.email],
+      ["headers", "HTTP header security:", groups.headers],
+      ["other", "Other:", groups.other],
+    ];
+    for (const [key, label, arr] of sections) {
+      if (!arr || arr.length === 0) continue;
+      console.log(color("violet", `  ${label}`));
+      for (const f of arr) {
+        const sev = f.severity.toUpperCase();
+        const sevColor =
+          f.severity === "critical" ? "red" :
+          f.severity === "high"     ? "yellow" :
+          f.severity === "medium"   ? "yellow" : "dim";
+        const isUnique = key === "quantum" && /key reused?|reused for|key persist/.test((f.title || "").toLowerCase());
+        const star = isUnique ? color("violet", " ★ UNIQUE TO PQCHECK") : "";
+        console.log(`  ${color(sevColor, `[${sev}]`)} ${f.title}${star}`);
+        console.log(color("dim", `    ${f.detail}`));
+      }
     }
     console.log("");
   }
@@ -163,17 +228,29 @@ ${color("bold", "pqcheck")} ${color("dim", `v${VERSION}`)}
 Public Surface Blast Radius — quantum-decryption risk for any domain.
 
 ${color("bold", "Usage:")}
-  npx pqcheck <domain>           Scan and print human-readable report
-  npx pqcheck <domain> --json    Output raw JSON
+  npx pqcheck <domain>                       Scan and print human-readable report
+  npx pqcheck <domain> --format json         Output raw JSON
+  npx pqcheck <domain> --threshold 7         Exit 2 if score ≥ 7 (CI-friendly)
+  npx pqcheck <domain> --quiet               Print just the score, nothing else
 
 ${color("bold", "Options:")}
-  -h, --help        Show this help
-  -v, --version     Show version
-  --json            Print raw JSON output
+  -h, --help                Show this help
+  -v, --version             Show version
+  --format <text|json>      Output format (default: text)
+  --json                    Alias for --format json
+  --threshold <0-10>        Exit code 2 if score meets/exceeds this value
+  -q, --quiet               Print only the numeric score (pipe-friendly)
+
+${color("bold", "Exit codes:")}
+  0   success
+  1   usage / network / scan error
+  2   score met or exceeded --threshold
 
 ${color("bold", "Examples:")}
   npx pqcheck chase.com
-  npx pqcheck quantapact.com --json
+  npx pqcheck quantapact.com --format json
+  npx pqcheck mybank.com --threshold 7      ${color("dim", "# fail CI if exposed")}
+  echo "score: $(npx pqcheck mybank.com -q)"
 
 Backed by the patented Decryption Blast Radius methodology.
 ${color("violet", "https://quantapact.com")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Decryption Blast Radius scanner — find out how much of your data unlocks when quantum decryption arrives.",
   "keywords": [
     "post-quantum",