penthera 1.1.0

package/lib/remediation/index.js

@@ -0,0 +1,219 @@
+/**
+ * Remediation knowledge base + action-plan builder.
+ *
+ * Turns raw findings into a prioritised, owner-actionable plan: what to do, why
+ * it matters, how to fix it, rough effort, and whether it's a code change or an
+ * owner action (rotate a secret, renew a cert, change DNS) that a tool must not
+ * do for you. This is the structured data the report renders and that the Agent
+ * Skill uses to draft questionnaire answers and remediation documents.
+ */
+
+// Each rule matches a finding and yields remediation guidance. First match wins,
+// so order specific rules (by title) before broad ones (by category).
+const RULES = [
+  {
+    id: "email-spf",
+    match: (f) => f.category === "email-auth" && /SPF/i.test(f.title),
+    action: "Publish (or tighten) an SPF record",
+    why: "Without a restrictive SPF record, anyone can send email that appears to come from your domain, a common phishing and business-email-compromise vector.",
+    fix: "Add a DNS TXT record at the root: `v=spf1 include:<your-mail-provider> -all`. End with `-all` (hard fail), not `~all` or `+all`.",
+    effort: "quick",
+    ownerAction: true, // DNS change
+  },
+  {
+    id: "email-dmarc",
+    match: (f) => f.category === "email-auth" && /DMARC/i.test(f.title),
+    action: "Publish and enforce a DMARC policy",
+    why: "DMARC tells receivers what to do with mail that fails SPF/DKIM and gives you reporting. `p=none` only monitors, it does not block spoofing.",
+    fix: "Add a TXT record at `_dmarc.<domain>`: start with `v=DMARC1; p=none; rua=mailto:you@domain` to gather reports, then move to `p=quarantine` and finally `p=reject` once your legitimate senders are aligned.",
+    effort: "moderate",
+    ownerAction: true,
+  },
+  {
+    id: "email-dkim",
+    match: (f) => f.category === "email-auth" && /DKIM/i.test(f.title),
+    action: "Confirm DKIM is signing outbound mail",
+    why: "DKIM cryptographically signs your mail so receivers can verify it wasn't forged or altered. It's the third leg of email authentication with SPF and DMARC.",
+    fix: "Enable DKIM in your email provider and publish the provider's public key at `<selector>._domainkey.<domain>`. Verify a signed test message passes DKIM.",
+    effort: "moderate",
+    ownerAction: true,
+  },
+  {
+    id: "header-csp",
+    match: (f) => /content-security-policy/i.test(f.title),
+    action: "Add a Content-Security-Policy header",
+    why: "CSP is the strongest defence-in-depth against cross-site scripting and data injection, it limits what scripts and resources the browser will load.",
+    fix: "Start in report-only mode to avoid breakage, then enforce. On Vercel/Next.js set it in `next.config.js` headers or `vercel.json`; on Express use `helmet`'s `contentSecurityPolicy`. Begin with `default-src 'self'` and add sources as needed.",
+    effort: "moderate",
+    ownerAction: false,
+  },
+  {
+    id: "header-generic",
+    match: (f) => f.category === "headers" || /x-frame-options|x-content-type-options|referrer-policy|permissions-policy|strict-transport-security|hsts/i.test(f.title),
+    action: "Add the missing security response headers",
+    why: "Headers like X-Frame-Options (clickjacking), X-Content-Type-Options (MIME sniffing), Referrer-Policy, Permissions-Policy, and HSTS are low-effort, high-value hardening.",
+    fix: "Set them once at the edge/framework layer: `helmet()` on Express, a `headers()` entry in `next.config.js`, or a `headers` block in `vercel.json`. Include `Strict-Transport-Security: max-age=63072000; includeSubDomains`.",
+    effort: "quick",
+    ownerAction: false,
+  },
+  {
+    id: "tls",
+    match: (f) => f.category === "tls" || /TLS|certificate|cipher|expir/i.test(f.title),
+    action: "Fix the TLS configuration",
+    why: "Weak protocols/ciphers or an expiring certificate undermine transport security and can break trust or enable downgrade attacks.",
+    fix: "Renew the certificate before expiry (automate with Let's Encrypt/ACME), disable TLS < 1.2, and prefer AEAD ciphers. Renewal is an operations action, not a code change.",
+    effort: "moderate",
+    ownerAction: true, // cert renewal
+  },
+  {
+    id: "secrets",
+    match: (f) => f.category === "secrets",
+    action: "Rotate the exposed secret and move it to a secret store",
+    why: "A hardcoded credential in source is compromised the moment the repo is shared or leaked; attackers scan public and private repos for exactly this.",
+    fix: "Treat the secret as burned: rotate/revoke it at the provider first, then remove it from source, load it from an environment variable or secret manager, and purge it from git history. Rotation is an owner action a tool must not perform for you.",
+    effort: "moderate",
+    ownerAction: true,
+  },
+  {
+    id: "injection",
+    match: (f) => ["sqli", "ssti", "ssrf", "xss", "cmdi", "injection", "open-redirect"].includes(f.category),
+    action: "Fix the injection / input-handling flaw",
+    why: "Injection flaws (SQLi, SSTI, SSRF, XSS, command injection, open redirect) let an attacker run code, read data, or redirect users. These are among the highest-impact web vulnerabilities.",
+    fix: "Never build queries/commands/markup from raw input: use parameterised queries, context-aware output encoding, an allow-list for redirect targets and outbound URLs (SSRF), and a sandboxed template engine. Validate and canonicalise all user input.",
+    effort: "involved",
+    ownerAction: false,
+  },
+  {
+    id: "auth",
+    match: (f) => f.category === "auth" || f.category === "auth-bypass",
+    action: "Harden authentication and access control",
+    why: "Broken auth or object-level access control (IDOR/BOLA, weak login, OAuth open redirect) lets attackers reach data or actions that aren't theirs.",
+    fix: "Enforce authorization server-side on every request (never trust the client), check that the authenticated user owns the object being accessed, validate OAuth `redirect_uri` against an allow-list, and add rate limiting and lockout on login.",
+    effort: "involved",
+    ownerAction: false,
+  },
+  {
+    id: "rate-limiting",
+    match: (f) => f.category === "rate-limiting" || /rate limit/i.test(f.title),
+    action: "Add rate limiting to sensitive endpoints",
+    why: "Without rate limiting, login and expensive endpoints are open to brute force, credential stuffing, and abuse/cost attacks.",
+    fix: "Apply per-IP and per-account rate limits on auth and costly routes (e.g. `express-rate-limit`, an edge/WAF rule, or your platform's built-in limiter). Return 429 with backoff.",
+    effort: "moderate",
+    ownerAction: false,
+  },
+  {
+    id: "cve",
+    match: (f) => f.category === "cve" || f.category === "js-vulnerability",
+    action: "Update the vulnerable dependency",
+    why: "A dependency with a known CVE is a documented, exploitable path in, attackers scan for exactly these versions.",
+    fix: "Upgrade to a patched version, run `npm audit fix` (or your ecosystem's equivalent), and add dependency scanning to CI so regressions are caught.",
+    effort: "quick",
+    ownerAction: false,
+  },
+  {
+    id: "cors",
+    match: (f) => f.category === "cors",
+    action: "Restrict CORS to explicit origins",
+    why: "A permissive CORS policy (reflecting arbitrary or `null` origins) can let malicious sites read authenticated responses.",
+    fix: "Replace origin reflection with an explicit allow-list of trusted origins, and never combine `Access-Control-Allow-Origin: *` with credentials.",
+    effort: "quick",
+    ownerAction: false,
+  },
+  {
+    id: "cookie",
+    match: (f) => f.category === "cookie",
+    action: "Set secure cookie flags",
+    why: "Session cookies without HttpOnly, Secure, and SameSite are exposed to theft via XSS and CSRF.",
+    fix: "Set `HttpOnly`, `Secure`, and `SameSite=Lax` (or `Strict`) on session/auth cookies. Most frameworks set these via the session middleware config.",
+    effort: "quick",
+    ownerAction: false,
+  },
+  {
+    id: "exposure",
+    match: (f) => f.category === "exposure" || f.category === "disclosure" || f.category === "config",
+    action: "Remove the exposed file or interface from production",
+    why: "Exposed configs, docs, admin interfaces, or backup files hand attackers a map of your system and sometimes credentials.",
+    fix: "Block or remove the path in production (API docs, `.env`, actuator/status endpoints, source maps). Serve them only in non-production or behind authentication.",
+    effort: "quick",
+    ownerAction: false,
+  },
+];
+
+const FALLBACK = {
+  id: "review",
+  action: "Review and remediate this finding",
+  why: "This finding needs a manual review to determine impact and the right fix.",
+  fix: "Confirm the finding, assess exploitability in your context, apply the appropriate fix, and re-scan to verify.",
+  effort: "moderate",
+  ownerAction: false,
+};
+
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+const EFFORT_ORDER = { quick: 0, moderate: 1, involved: 2 };
+
+function ruleFor(finding) {
+  return RULES.find((r) => r.match(finding)) || FALLBACK;
+}
+
+/**
+ * Build a prioritised action plan from findings. Groups findings by remediation,
+ * carries the highest severity in each group, and sorts by severity then effort.
+ */
+export function buildActionPlan(findings) {
+  const groups = new Map();
+  for (const f of findings || []) {
+    if (f.severity === "info") continue; // info items aren't action items
+    const rule = ruleFor(f);
+    if (!groups.has(rule.id)) {
+      groups.set(rule.id, {
+        id: rule.id,
+        action: rule.action,
+        why: rule.why,
+        fix: rule.fix,
+        effort: rule.effort,
+        ownerAction: rule.ownerAction,
+        severity: f.severity,
+        findings: [],
+      });
+    }
+    const g = groups.get(rule.id);
+    if ((SEV_ORDER[f.severity] ?? 5) < (SEV_ORDER[g.severity] ?? 5)) g.severity = f.severity;
+    g.findings.push({ title: f.title, url: f.url || null, severity: f.severity });
+  }
+
+  return [...groups.values()].sort((a, b) => {
+    const s = (SEV_ORDER[a.severity] ?? 5) - (SEV_ORDER[b.severity] ?? 5);
+    if (s !== 0) return s;
+    return (EFFORT_ORDER[a.effort] ?? 3) - (EFFORT_ORDER[b.effort] ?? 3);
+  });
+}
+
+const SEV_TAG = { critical: "CRITICAL", high: "HIGH", medium: "MEDIUM", low: "LOW", info: "INFO" };
+
+/** Render an action plan as a Markdown section. */
+export function formatActionPlanMarkdown(plan) {
+  if (!plan || plan.length === 0) return "";
+  const findingCount = plan.reduce((n, a) => n + a.findings.length, 0);
+  const L = [];
+  L.push("## Action plan");
+  L.push("");
+  L.push(`Prioritised fixes for the owner, **${plan.length}** action${plan.length > 1 ? "s" : ""} covering **${findingCount}** finding${findingCount > 1 ? "s" : ""}, highest severity first.`);
+  L.push("");
+  plan.forEach((a, i) => {
+    const tag = SEV_TAG[a.severity] || "";
+    const kind = a.ownerAction ? " · owner action" : "";
+    L.push(`### ${i + 1}. ${a.action}`);
+    L.push("");
+    L.push(`**${tag}** · ${a.effort}${kind} · resolves ${a.findings.length} finding${a.findings.length > 1 ? "s" : ""}`);
+    L.push("");
+    L.push(`**Why:** ${a.why}`);
+    L.push("");
+    L.push(`**Fix:** ${a.fix}`);
+    L.push("");
+    if (a.ownerAction) {
+      L.push("> This is an owner action (e.g. rotate a secret, renew a certificate, change DNS). Penthera flags it but will not do it for you.");
+      L.push("");
+    }
+  });
+  return L.join("\n");
+}

package/lib/retirejs.js

@@ -0,0 +1,239 @@
+/**
+ * Retire.js Integration, Client-Side JS Library Vulnerability Detection
+ *
+ * Fetches the Retire.js vulnerability database (open JSON, maintained by
+ * the Retire.js community on GitHub) and checks discovered JS files.
+ *
+ * Detection cascade (same 4-layer approach as Retire.js itself):
+ *   1. Filename/URL pattern matching (jquery-3.5.1.min.js)
+ *   2. File content pattern matching (/*! jQuery v3.5.1 *​/)
+ *   3. Hash matching for minified files (sha1)
+ *   4. URI path matching (/3.5.1/jquery.min.js)
+ *
+ * Database source:
+ *   https://raw.githubusercontent.com/nickvergessen/retire.js/master/repository/jsrepository.json
+ */
+
+const DB_URL =
+  "https://raw.githubusercontent.com/nickvergessen/retire.js/master/repository/jsrepository.json";
+const DB_CACHE_MS = 3600_000; // 1 hour
+
+let cachedDb = null;
+let cachedAt = 0;
+
+async function safeFetch(url, timeout = 15_000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Database loading ─────────────────────────────────────────────────────
+
+async function loadDb() {
+  if (cachedDb && Date.now() - cachedAt < DB_CACHE_MS) return cachedDb;
+
+  const res = await safeFetch(DB_URL);
+  if (!res || !res.ok) return null;
+
+  try {
+    cachedDb = await res.json();
+    cachedAt = Date.now();
+    return cachedDb;
+  } catch {
+    return null;
+  }
+}
+
+// ── Version comparison ───────────────────────────────────────────────────
+
+function parseVersion(v) {
+  return String(v).split(/[.\-]/).map((p) => {
+    const n = parseInt(p, 10);
+    return isNaN(n) ? 0 : n;
+  });
+}
+
+function isBelow(detected, threshold) {
+  const a = parseVersion(detected);
+  const b = parseVersion(threshold);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const va = a[i] || 0;
+    const vb = b[i] || 0;
+    if (va < vb) return true;
+    if (va > vb) return false;
+  }
+  return false;
+}
+
+function isAtOrAbove(detected, threshold) {
+  return !isBelow(detected, threshold);
+}
+
+function isVulnerable(version, vuln) {
+  if (vuln.below && !isBelow(version, vuln.below)) return false;
+  if (vuln.atOrAbove && !isAtOrAbove(version, vuln.atOrAbove)) return false;
+  return true;
+}
+
+// ── Extractor engine ─────────────────────────────────────────────────────
+
+const VERSION_PLACEHOLDER = /§§version§§/g;
+
+function extractVersion(text, patterns) {
+  if (!patterns || !Array.isArray(patterns)) return null;
+  for (const pattern of patterns) {
+    const regexStr = pattern.replace(VERSION_PLACEHOLDER, "([\\d][\\d.a-z\\-]+)");
+    try {
+      const match = text.match(new RegExp(regexStr, "i"));
+      if (match && match[1]) return match[1];
+    } catch {
+      // Invalid regex in DB entry, skip
+    }
+  }
+  return null;
+}
+
+// ── Script discovery ─────────────────────────────────────────────────────
+
+/**
+ * Extract <script src="..."> URLs and inline script blocks from HTML.
+ */
+export function extractScripts(html, baseUrl) {
+  const scripts = { external: [], inline: [] };
+
+  // External scripts
+  const srcRe = /<script[^>]+src=["']([^"']+)["']/gi;
+  let match;
+  while ((match = srcRe.exec(html))) {
+    let src = match[1];
+    // Resolve relative URLs
+    if (src.startsWith("//")) src = "https:" + src;
+    else if (src.startsWith("/")) src = baseUrl + src;
+    else if (!src.startsWith("http")) src = baseUrl + "/" + src;
+    scripts.external.push(src);
+  }
+
+  // Inline scripts (for version detection)
+  const inlineRe = /<script(?:\s[^>]*)?>([\s\S]*?)<\/script>/gi;
+  while ((match = inlineRe.exec(html))) {
+    if (match[1].trim().length > 10) {
+      scripts.inline.push(match[1]);
+    }
+  }
+
+  return scripts;
+}
+
+// ── Main scanner ─────────────────────────────────────────────────────────
+
+/**
+ * Scan a target for vulnerable JavaScript libraries.
+ *
+ * @param {string} baseUrl - Target base URL
+ * @param {object} opts - { onPhase, timeout, maxScripts }
+ * @returns {{ libraries: object[], findings: object[] }}
+ */
+export async function scanJsLibraries(baseUrl, opts = {}) {
+  const progress = opts.onPhase || (() => {});
+  const maxScripts = opts.maxScripts || 20;
+  const timeout = opts.timeout || 8_000;
+  const result = { libraries: [], findings: [] };
+
+  // Load Retire.js database
+  progress("Fetching Retire.js vulnerability database...");
+  const db = await loadDb();
+  if (!db) {
+    return result; // Can't check without DB
+  }
+
+  // Fetch the target page HTML
+  const res = await safeFetch(baseUrl, timeout);
+  if (!res || !res.ok) return result;
+  const html = await res.text().catch(() => "");
+
+  // Extract script URLs and inline scripts
+  const scripts = extractScripts(html, baseUrl);
+
+  // Check each library in the DB
+  for (const [libName, libData] of Object.entries(db)) {
+    if (!libData.extractors) continue;
+    let detectedVersion = null;
+
+    // 1. Check against inline script content + HTML
+    if (libData.extractors.filecontent) {
+      detectedVersion = extractVersion(html, libData.extractors.filecontent);
+    }
+
+    // 2. Check against external script URLs (filename + uri patterns)
+    if (!detectedVersion) {
+      for (const scriptUrl of scripts.external) {
+        if (libData.extractors.filename) {
+          const filename = scriptUrl.split("/").pop().split("?")[0];
+          detectedVersion = extractVersion(filename, libData.extractors.filename);
+          if (detectedVersion) break;
+        }
+        if (libData.extractors.uri) {
+          detectedVersion = extractVersion(scriptUrl, libData.extractors.uri);
+          if (detectedVersion) break;
+        }
+      }
+    }
+
+    // 3. If found in URL but no version, try fetching the file content
+    if (!detectedVersion && libData.extractors.filecontent) {
+      for (const scriptUrl of scripts.external.slice(0, maxScripts)) {
+        // Only fetch if URL looks like it could be this library
+        const lower = scriptUrl.toLowerCase();
+        if (!lower.includes(libName.toLowerCase().replace(/\./g, ""))) continue;
+
+        const jsRes = await safeFetch(scriptUrl, 5_000);
+        if (!jsRes || !jsRes.ok) continue;
+        const jsContent = await jsRes.text().catch(() => "");
+        if (jsContent.length > 0) {
+          detectedVersion = extractVersion(jsContent, libData.extractors.filecontent);
+          if (detectedVersion) break;
+        }
+      }
+    }
+
+    if (!detectedVersion) continue;
+
+    // Record the detected library
+    const lib = { name: libName, version: detectedVersion, vulnerabilities: [] };
+
+    // Check against known vulnerabilities
+    for (const vuln of libData.vulnerabilities || []) {
+      if (isVulnerable(detectedVersion, vuln)) {
+        const cves = vuln.identifiers?.CVE || [];
+        const severity = vuln.severity || "medium";
+        lib.vulnerabilities.push({
+          severity,
+          below: vuln.below,
+          cves,
+          info: vuln.info || [],
+        });
+
+        result.findings.push({
+          severity,
+          title: `Vulnerable JS library: ${libName} ${detectedVersion}`,
+          description: cves.length > 0
+            ? `${cves.join(", ")}, upgrade to ${vuln.below || "latest"}`
+            : `Known vulnerability, upgrade to ${vuln.below || "latest"}`,
+          url: baseUrl,
+          category: "js-vulnerability",
+          source: "retirejs",
+        });
+      }
+    }
+
+    result.libraries.push(lib);
+  }
+
+  return result;
+}

package/lib/supply-chain.js

@@ -0,0 +1,131 @@
+/**
+ * Supplier passive rating (NIS2 measure d, supply-chain security).
+ *
+ * NIS2 pulls smaller suppliers into scope through supply-chain risk assessment.
+ * This lets a company point Penthera's PASSIVE checks at their own suppliers'
+ * public domains and get a red/amber/green posture per supplier.
+ *
+ * STRICTLY PASSIVE and public-data-only, equivalent to visiting the public
+ * website and looking up public DNS. It performs exactly three non-intrusive
+ * actions per domain:
+ *   1. one HTTPS GET of the homepage (security headers),
+ *   2. a TLS handshake to read the certificate (protocol/expiry),
+ *   3. public DNS lookups for SPF/DMARC/MX (email authentication).
+ * No endpoint discovery, no auth probes, no injection, no fuzzing. This is the
+ * only third-party-facing feature, and it is deliberately kept passive.
+ */
+import { checkTls } from "./tls.js";
+import { auditSecurityHeaders } from "./blackbox/headers.js";
+import { probeEmailDns } from "./blackbox/email-dns.js";
+import { safeFetch } from "../src/utils/http.js";
+
+/** Parse a domain from a line/entry: strip scheme, path, and whitespace. */
+export function parseDomain(entry) {
+  const s = String(entry).trim();
+  if (!s || s.startsWith("#")) return null;
+  return s.replace(/^https?:\/\//i, "").replace(/\/.*$/, "").replace(/:\d+$/, "").trim() || null;
+}
+
+/** Parse a supplier list: newline- or comma-separated domains, # comments ok. */
+export function parseSupplierList(text) {
+  return [...new Set(
+    String(text).split(/[\n,]+/).map(parseDomain).filter(Boolean),
+  )];
+}
+
+const PENALTY = { critical: 40, high: 25, medium: 12, low: 5, info: 1 };
+
+/** Score and RAG-rate a supplier from its passive findings. */
+export function scoreSupplier(result) {
+  if (!result.reachable) return { score: null, rating: "unknown" };
+  let penalty = 0;
+  for (const f of result.findings) penalty += PENALTY[f.severity] || 0;
+  const score = Math.max(0, Math.min(100, 100 - penalty));
+  const rating = score >= 80 ? "green" : score >= 50 ? "amber" : "red";
+  return { score, rating };
+}
+
+/**
+ * Rate one supplier domain with passive checks only.
+ */
+export async function rateSupplier(domain, opts = {}) {
+  const timeout = opts.timeout || 8000;
+  const httpsUrl = `https://${domain}`;
+  const result = { domain, reachable: false, tls: null, email: null, findings: [] };
+
+  // 1. Passive homepage GET (follow redirects to reach the real homepage headers)
+  let res = null;
+  try {
+    res = await safeFetch(httpsUrl, { timeout, redirect: "follow" });
+  } catch { /* unreachable */ }
+  result.reachable = !!res;
+
+  // 2. Security headers from the homepage response
+  if (res) {
+    const headerMap = Object.fromEntries(res.headers.entries());
+    result.findings.push(...auditSecurityHeaders(headerMap, httpsUrl, { local: false }));
+  }
+
+  // 3. TLS certificate / protocol (passive handshake)
+  try {
+    const tls = await checkTls(domain, 443);
+    result.tls = { protocol: tls.protocol, valid: tls.valid, daysUntilExpiry: tls.daysUntilExpiry };
+    for (const f of tls.findings || []) {
+      result.findings.push({ ...f, category: "tls", source: "supplier-tls" });
+    }
+  } catch { /* no TLS */ }
+
+  // 4. Email authentication (public DNS)
+  try {
+    const email = await probeEmailDns(domain);
+    result.email = { spf: !!email.spf, dmarc: !!email.dmarc, dmarcPolicy: email.dmarcPolicy, mxCount: email.mxCount };
+    result.findings.push(...email.findings);
+  } catch { /* no DNS */ }
+
+  Object.assign(result, scoreSupplier(result));
+  result.keyIssues = result.findings
+    .filter((f) => f.severity === "critical" || f.severity === "high" || f.severity === "medium")
+    .map((f) => f.title);
+  return result;
+}
+
+/** Rate a list of supplier domains (small concurrency, passive). */
+export async function rateSuppliers(domains, opts = {}) {
+  const concurrency = opts.concurrency || 5;
+  const results = [];
+  for (let i = 0; i < domains.length; i += concurrency) {
+    const batch = domains.slice(i, i + concurrency);
+    const settled = await Promise.all(batch.map((d) => rateSupplier(d, opts).catch(() => ({
+      domain: d, reachable: false, findings: [], score: null, rating: "unknown", keyIssues: [],
+    }))));
+    results.push(...settled);
+  }
+  const summary = { green: 0, amber: 0, red: 0, unknown: 0 };
+  for (const r of results) summary[r.rating] = (summary[r.rating] || 0) + 1;
+  return { generated_at: opts.generatedAt || null, count: results.length, summary, suppliers: results };
+}
+
+const RATING_LABEL = { green: "🟢 Green", amber: "🟡 Amber", red: "🔴 Red", unknown: "⚪ Unknown" };
+
+/** Render supplier ratings as Markdown. */
+export function formatSuppliersMarkdown(report) {
+  if (!report) return "";
+  const L = [];
+  L.push("# Supplier security ratings");
+  L.push("");
+  L.push("> **Passive, public-data-only assessment**, equivalent to visiting each supplier's public website and looking up public DNS. No intrusive testing was performed. This is a screening aid for supply-chain risk (NIS2 measure d), **not** an authorised penetration test of the supplier and **not** a certification of them.");
+  L.push("");
+  const s = report.summary;
+  L.push(`**${report.count}** suppliers: ${s.green} green · ${s.amber} amber · ${s.red} red · ${s.unknown} unknown.`);
+  L.push("");
+  L.push("| Supplier | Rating | Score | Key issues |");
+  L.push("|----------|--------|-------|-----------|");
+  for (const r of report.suppliers) {
+    const issues = r.keyIssues?.length ? r.keyIssues.slice(0, 4).join("; ") : (r.rating === "unknown" ? "unreachable" : "none found (passive)");
+    L.push(`| ${r.domain} | ${RATING_LABEL[r.rating] || r.rating} | ${r.score ?? "-"} | ${issues} |`);
+  }
+  L.push("");
+  L.push("Methodology: one HTTPS homepage GET (security headers), a TLS handshake (certificate/protocol), and public DNS lookups (SPF/DMARC/MX). Ratings: green ≥ 80, amber 50-79, red < 50; unknown = unreachable.");
+  L.push("");
+  return L.join("\n");
+}