pqcheck 0.2.0 → 0.4.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
 
 ```
@@ -83,6 +88,15 @@ The `--threshold` flag turns `pqcheck` into a quantum-risk gate for any pipeline
 
 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

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.2.0";
+const VERSION = "0.4.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -34,8 +34,13 @@ async function main() {
     process.exit(0);
   }
 
-  const domain = normalizeDomain(args.find((a) => !a.startsWith("-")) || "");
-  if (!domain) {
+  // Multi-domain support: any non-flag positional arg is a domain
+  const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
+  const domains = positional
+    .map((a) => normalizeDomain(a))
+    .filter((d) => !!d);
+
+  if (domains.length === 0) {
     console.error(color("red", "error: no domain provided"));
     printUsage();
     process.exit(1);
@@ -44,49 +49,178 @@ async function main() {
   const quiet = args.includes("--quiet") || args.includes("-q");
   const format = parseFormat(args);
   const threshold = parseThreshold(args);
+  const watchInterval = parseWatch(args);
+  const webhookUrl = parseWebhook(args);
+
   if (threshold === "invalid") {
     console.error(color("red", "error: --threshold requires a number 0-10"));
     process.exit(1);
   }
+  if (watchInterval === "invalid") {
+    console.error(color("red", "error: --watch requires a positive number of seconds (default 300 if no value given)"));
+    process.exit(1);
+  }
+  if (webhookUrl === "invalid") {
+    console.error(color("red", "error: --webhook requires a URL starting with http:// or https://"));
+    process.exit(1);
+  }
+
+  // Watch mode loop: scan, diff, optionally webhook, repeat.
+  if (watchInterval !== null) {
+    await runWatch({ domains, format, quiet, threshold, webhookUrl, intervalSec: watchInterval });
+    return; // runWatch handles its own exit; in practice it runs until killed.
+  }
 
-  if (!quiet) process.stderr.write(color("dim", `Scanning ${domain} ...`));
+  // One-shot scan(s)
+  let worstExit = 0;
+  for (const domain of domains) {
+    const exit = await runOneScan({ domain, format, quiet, threshold, webhookUrl, multi: domains.length > 1 });
+    if (exit > worstExit) worstExit = exit;
+  }
+  process.exit(worstExit);
+}
+
+async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi }) {
+  if (!quiet && format === "text") 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}` },
     });
-    if (!quiet) process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
+    if (!quiet && format === "text") process.stderr.write("\r\x1b[K");
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
-      console.error(color("red", `error: ${resp.status} ${errBody?.error || resp.statusText}`));
+      console.error(color("red", `error scanning ${domain}: ${resp.status} ${errBody?.error || resp.statusText}`));
       if (errBody?.detail) console.error(color("dim", errBody.detail));
-      process.exit(1);
+      return 1;
     }
     report = await resp.json();
   } catch (err) {
-    if (!quiet) process.stderr.write("\r\x1b[K");
-    console.error(color("red", `error: ${err.message}`));
-    process.exit(1);
+    if (!quiet && format === "text") process.stderr.write("\r\x1b[K");
+    console.error(color("red", `error scanning ${domain}: ${err.message}`));
+    return 1;
   }
 
+  // Webhook delivery — fire-and-forget POST with JSON body
+  if (webhookUrl) {
+    fetch(webhookUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", "user-agent": `pqcheck-cli/${VERSION}` },
+      body: JSON.stringify({ domain, report, source: "pqcheck-cli", at: new Date().toISOString() }),
+    }).catch(() => { /* best-effort — never fail the scan on webhook delivery */ });
+  }
+
+  // Output dispatch
   if (quiet) {
-    // Numeric score on stdout, nothing else. Suitable for piping.
-    console.log(typeof report.score === "number" ? report.score : "");
+    if (multi) {
+      console.log(`${domain}\t${typeof report.score === "number" ? report.score : ""}`);
+    } else {
+      console.log(typeof report.score === "number" ? report.score : "");
+    }
   } else if (format === "json") {
-    console.log(JSON.stringify(report, null, 2));
+    if (multi) {
+      // Per-line NDJSON when scanning multiple domains so output is pipe-friendly
+      console.log(JSON.stringify(report));
+    } else {
+      console.log(JSON.stringify(report, null, 2));
+    }
+  } else if (format === "csv") {
+    if (multi && this && !this.csvHeaderPrinted) {
+      // Header only once, before first row
+    }
+    printCsvRow(report);
+  } else if (format === "markdown") {
+    printMarkdown(report, multi);
   } else {
+    if (multi) console.log(color("dim", `\n──── ${domain} ────`));
     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}`));
+    if (!quiet && format === "text") {
+      console.error(color("red", `threshold breach: ${domain} score ${report.score} >= ${threshold}`));
+    }
+    return 2;
+  }
+  return 0;
+}
+
+async function runWatch({ domains, format, quiet, threshold, webhookUrl, intervalSec }) {
+  const previous = new Map(); // domain → previous score
+  if (!quiet && format === "text") {
+    console.error(color("dim", `Watching ${domains.length} domain(s), polling every ${intervalSec}s. Ctrl-C to stop.`));
+  }
+
+  // Print CSV header once if csv mode
+  if (format === "csv") printCsvHeader();
+
+  // Trap SIGINT so we exit cleanly
+  let stopped = false;
+  process.on("SIGINT", () => {
+    stopped = true;
+    if (!quiet && format === "text") console.error(color("dim", "\nStopped."));
+    process.exit(0);
+  });
+
+  while (!stopped) {
+    for (const domain of domains) {
+      try {
+        const resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, {
+          method: "GET",
+          headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION}` },
+        });
+        if (!resp.ok) continue;
+        const report = await resp.json();
+        const prev = previous.get(domain);
+        const changed = prev !== undefined && typeof report.score === "number" && report.score !== prev;
+        previous.set(domain, report.score);
+
+        if (changed && webhookUrl) {
+          fetch(webhookUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": `pqcheck-cli/${VERSION}` },
+            body: JSON.stringify({
+              type: "score_changed",
+              domain,
+              previousScore: prev,
+              newScore: report.score,
+              report,
+              at: new Date().toISOString(),
+            }),
+          }).catch(() => {});
+        }
+
+        if (format === "csv") {
+          printCsvRow(report);
+        } else if (format === "json") {
+          console.log(JSON.stringify({ ...report, _watchPreviousScore: prev ?? null, _watchChanged: changed }));
+        } else if (format === "markdown") {
+          printMarkdown(report, true);
+        } else {
+          const stamp = new Date().toISOString().slice(11, 19);
+          if (changed) {
+            console.log(color("yellow", `[${stamp}] ${domain}: ${prev} → ${report.score}  (${report.scoreLabel}) ${color("yellow", "★ changed")}`));
+          } else if (!quiet) {
+            console.log(color("dim", `[${stamp}] ${domain}: ${report.score}  (${report.scoreLabel})`));
+          }
+        }
+      } catch (err) {
+        if (!quiet && format === "text") console.error(color("red", `[watch] ${domain}: ${err.message}`));
+      }
     }
-    process.exit(2);
+    await sleep(intervalSec * 1000);
   }
-  process.exit(0);
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+function isFlagValue(args, val) {
+  // True when this arg is the value following a flag like --threshold 7 or --format json
+  const idx = args.indexOf(val);
+  if (idx <= 0) return false;
+  const prev = args[idx - 1];
+  return prev === "--threshold" || prev === "--format" || prev === "--watch" || prev === "--webhook";
 }
 
 function parseFormat(args) {
@@ -94,7 +228,8 @@ function parseFormat(args) {
   const i = args.indexOf("--format");
   if (i === -1) return "text";
   const v = (args[i + 1] || "").toLowerCase();
-  return v === "json" ? "json" : "text";
+  if (v === "json" || v === "csv" || v === "markdown" || v === "md") return v === "md" ? "markdown" : v;
+  return "text";
 }
 
 function parseThreshold(args) {
@@ -106,6 +241,94 @@ function parseThreshold(args) {
   return n;
 }
 
+function parseWatch(args) {
+  const i = args.indexOf("--watch");
+  if (i === -1) return null;
+  const raw = args[i + 1];
+  // --watch with no value defaults to 300s (5 min)
+  if (raw === undefined || raw.startsWith("-")) return 300;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 10) return "invalid";
+  return n;
+}
+
+function parseWebhook(args) {
+  const i = args.indexOf("--webhook");
+  if (i === -1) return null;
+  const raw = args[i + 1];
+  if (!raw || !/^https?:\/\//.test(raw)) return "invalid";
+  return raw;
+}
+
+// ---------- format renderers (CSV + markdown) ----------
+
+let _csvHeaderPrinted = false;
+function printCsvHeader() {
+  console.log("domain,score,grade,score_label,reachable,tls_version,hybrid_pqc,days_until_cert_expiry,subdomains,wildcard_cert,findings_high,findings_medium,findings_low");
+  _csvHeaderPrinted = true;
+}
+function printCsvRow(r) {
+  if (!_csvHeaderPrinted) printCsvHeader();
+  const ps = r.publicSurface || {};
+  const sevCount = (sev) => (r.findings || []).filter((f) => f.severity === sev).length;
+  const cells = [
+    csvEscape(r.domain),
+    r.score ?? "",
+    r.grade ?? "",
+    r.scoreLabel ?? "",
+    r.reachable ? "true" : "false",
+    csvEscape(ps.tlsVersion ?? ""),
+    ps.hybridPQC ? "true" : "false",
+    ps.daysUntilCertExpiry ?? "",
+    ps.subdomainCount ?? 0,
+    ps.wildcardCert ? "true" : "false",
+    sevCount("high") + sevCount("critical"),
+    sevCount("medium"),
+    sevCount("low"),
+  ];
+  console.log(cells.join(","));
+}
+function csvEscape(s) {
+  const v = String(s ?? "");
+  if (v.includes(",") || v.includes('"') || v.includes("\n")) {
+    return '"' + v.replace(/"/g, '""') + '"';
+  }
+  return v;
+}
+
+function printMarkdown(r, multi) {
+  if (!r.reachable) {
+    console.log(`### ${r.domain} — unreachable\n${r.errorMessage ? `> ${r.errorMessage}` : ""}\n`);
+    return;
+  }
+  const ps = r.publicSurface || {};
+  const lines = [];
+  lines.push(`### ${r.domain} — Decryption Blast Radius **${r.score} / 10** (${r.scoreLabel}, grade ${r.grade ?? "—"})`);
+  lines.push("");
+  lines.push("| Signal | Value |");
+  lines.push("|---|---|");
+  lines.push(`| TLS | ${ps.tlsVersion ?? "?"}${ps.cipher ? ` (${ps.cipher})` : ""} |`);
+  lines.push(`| Hybrid PQC | ${ps.hybridPQC ? "yes" : "no"} |`);
+  lines.push(`| Cert expires | ${ps.daysUntilCertExpiry !== null && ps.daysUntilCertExpiry !== undefined ? `in ${ps.daysUntilCertExpiry} days` : "?"} |`);
+  lines.push(`| HSTS | ${ps.hsts ? "enabled" : "not detected"} |`);
+  lines.push(`| Subdomains | ${ps.subdomainCount ?? 0}${ps.wildcardCert ? " (wildcard cert)" : ""} |`);
+  lines.push("");
+  if (r.findings && r.findings.length) {
+    lines.push("**Findings:**");
+    lines.push("");
+    for (const f of r.findings) {
+      lines.push(`- **[${f.severity.toUpperCase()}]** ${f.title}`);
+      lines.push(`  ${f.detail}`);
+    }
+    lines.push("");
+  }
+  lines.push(`> ⚠ Public surface only. Internal Blast Radius is typically 12–40× this score.`);
+  lines.push("");
+  lines.push(`Full report: ${API_BASE}/?check=${encodeURIComponent(r.domain)} · Share: ${API_BASE}/r/${encodeURIComponent(r.domain)}`);
+  if (multi) lines.push("\n---\n");
+  console.log(lines.join("\n"));
+}
+
 function printReport(r) {
   if (!r.reachable) {
     console.log(color("red", `\n  ${r.domain} — unreachable`));
@@ -131,16 +354,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("");
   }
@@ -197,18 +451,25 @@ ${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> --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
+  npx pqcheck <domain>                          Scan + print human-readable report
+  npx pqcheck a.com b.com c.com                 Multi-domain scan
+  npx pqcheck <domain> --format json            Raw JSON
+  npx pqcheck <domain> --format markdown        GitHub-issue / Slack-ready Markdown
+  npx pqcheck <domain> --format csv             Spreadsheet-friendly CSV row
+  npx pqcheck <domain> --threshold 7            Exit 2 if score ≥ 7 (CI gate)
+  npx pqcheck <domain> --quiet                  Print just the score number
+  npx pqcheck <domain> --watch [seconds]        Continuously poll and report changes
+  npx pqcheck <domain> --webhook <url>          POST report JSON to URL on each scan
 
 ${color("bold", "Options:")}
-  -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)
+  -h, --help                       Show this help
+  -v, --version                    Show version
+  --format <text|json|markdown|csv>  Output format (default: text)
+  --json                           Alias for --format json
+  --threshold <0-10>               Exit 2 if score meets or exceeds this
+  -q, --quiet                      Print only the numeric score
+  --watch [seconds]                Poll every N seconds (default 300) and report changes
+  --webhook <url>                  POST scan results to a URL (one-shot or each watch tick)
 
 ${color("bold", "Exit codes:")}
   0   success
@@ -217,8 +478,10 @@ ${color("bold", "Exit codes:")}
 
 ${color("bold", "Examples:")}
   npx pqcheck chase.com
-  npx pqcheck quantapact.com --format json
-  npx pqcheck mybank.com --threshold 7      ${color("dim", "# fail CI if exposed")}
+  npx pqcheck mycompany.com mythirdparty.com --format csv > posture.csv
+  npx pqcheck mybank.com --threshold 7      ${color("dim", "# fail CI if score ≥ 7")}
+  npx pqcheck mybank.com --format markdown >> issue.md
+  npx pqcheck mybank.com --watch 600 --webhook https://hooks.slack.com/services/...
   echo "score: $(npx pqcheck mybank.com -q)"
 
 Backed by the patented Decryption Blast Radius methodology.

package/package.json

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