penthera 1.1.1 → 1.4.0

package/src/report/template.js

@@ -0,0 +1,175 @@
+/**
+ * A tiny report template language for `--report-template file.md`.
+ *
+ *   {{summary.critical}}               a value, HTML- and Markdown-escaped
+ *   {{#each findings}}…{{/each}}       loop over an array; inside, `this` is the
+ *                                      item, `@index` is 0-based, and names fall
+ *                                      back to the enclosing scopes
+ *   {{#if x}}…{{else}}…{{/if}}         truthy test (an empty array is false)
+ *
+ * That is the whole language. There are no helpers, no expressions, no raw
+ * output, no partials or file includes, and no way to reach a prototype: paths
+ * are dotted identifiers, `__proto__`, `constructor` and `prototype` are
+ * rejected when the template is parsed, and lookups only read own properties.
+ * Values are never parsed as template text, so a finding title that contains
+ * `{{…}}` prints as text.
+ */
+
+export class TemplateError extends Error {
+  constructor(message, line) {
+    super(line ? `${message} (line ${line})` : message);
+    this.name = "TemplateError";
+    this.line = line || null;
+  }
+}
+
+const MAX_TEMPLATE = 256 * 1024;
+const MAX_DEPTH = 32;
+const MAX_OUTPUT = 8 * 1024 * 1024;
+const FORBIDDEN = new Set(["__proto__", "constructor", "prototype"]);
+const SEGMENT = /^(?:[A-Za-z_][A-Za-z0-9_-]*|\d+)$/;
+
+function parsePath(raw, line) {
+  if (raw === "this" || raw === "@index") return [raw];
+  const parts = raw.split(".");
+  const start = parts[0] === "this" ? 1 : 0;
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i];
+    if (FORBIDDEN.has(p)) throw new TemplateError(`"${p}" is not allowed in a template path`, line);
+    if (i >= start && !SEGMENT.test(p)) throw new TemplateError(`Bad template path "${raw}"`, line);
+  }
+  return parts;
+}
+
+/** Parse a template into a tree. Throws TemplateError on any syntax it does not know. */
+export function parseTemplate(src) {
+  if (typeof src !== "string") throw new TemplateError("Template must be a string");
+  if (src.length > MAX_TEMPLATE) throw new TemplateError(`Template is larger than ${MAX_TEMPLATE} bytes`);
+  const root = { type: "root", body: [] };
+  const stack = [root];
+  let target = root.body;
+  let line = 1;
+  let last = 0;
+  const re = /\{\{([\s\S]*?)\}\}/g;
+  let m;
+  while ((m = re.exec(src))) {
+    if (m.index > last) target.push({ type: "text", value: src.slice(last, m.index) });
+    line += countLines(src.slice(last, m.index));
+    last = re.lastIndex;
+    const tag = m[1].trim();
+    const top = stack[stack.length - 1];
+    let mm;
+    if ((mm = /^#(each|if)\s+(\S+)$/.exec(tag))) {
+      if (stack.length > MAX_DEPTH) throw new TemplateError("Blocks are nested too deeply", line);
+      const node = { type: mm[1], path: parsePath(mm[2], line), body: [], alt: null, line };
+      target.push(node);
+      stack.push(node);
+      target = node.body;
+    } else if (tag === "else") {
+      if (top.type !== "if" || top.alt) throw new TemplateError("{{else}} outside {{#if}}", line);
+      top.alt = [];
+      target = top.alt;
+    } else if ((mm = /^\/(each|if)$/.exec(tag))) {
+      if (top.type !== mm[1]) throw new TemplateError(`Unexpected {{/${mm[1]}}}`, line);
+      stack.pop();
+      const parent = stack[stack.length - 1];
+      target = parent.alt ?? parent.body;
+    } else if (/^[A-Za-z_@][\w.@-]*$/.test(tag)) {
+      target.push({ type: "var", path: parsePath(tag, line), line });
+    } else {
+      throw new TemplateError(`Unsupported tag {{${tag.slice(0, 40)}}}`, line);
+    }
+    line += countLines(m[0]);
+  }
+  if (stack.length > 1) {
+    const open = stack[stack.length - 1];
+    throw new TemplateError(`Unclosed {{#${open.type}}}`, open.line);
+  }
+  if (last < src.length) target.push({ type: "text", value: src.slice(last) });
+  return root;
+}
+
+function countLines(s) {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+function own(obj, key) {
+  if (obj === null || typeof obj !== "object") return undefined;
+  if (Array.isArray(obj) && !/^\d+$/.test(key)) return key === "length" ? obj.length : undefined;
+  return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+
+function lookup(scopes, path) {
+  if (path[0] === "@index") return scopes[scopes.length - 1].index;
+  if (path[0] === "this") {
+    let v = scopes[scopes.length - 1].value;
+    for (let i = 1; i < path.length && v !== undefined; i++) v = own(v, path[i]);
+    return v;
+  }
+  for (let s = scopes.length - 1; s >= 0; s--) {
+    const first = own(scopes[s].value, path[0]);
+    if (first === undefined) continue;
+    let v = first;
+    for (let i = 1; i < path.length && v !== undefined; i++) v = own(v, path[i]);
+    return v;
+  }
+  return undefined;
+}
+
+const HTML = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+
+/**
+ * Escape a value for Markdown that may also be rendered as HTML: HTML entities
+ * for & < > " ', a backslash before Markdown punctuation, newlines folded to a
+ * space (so a value cannot start a heading, list or table row), and control
+ * characters dropped. Non-primitive values render as nothing.
+ */
+export function escapeValue(v) {
+  if (v === null || v === undefined) return "";
+  if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") return "";
+  return String(v)
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f\u2028\u2029]/g, "")
+    .replace(/\r?\n|\r/g, " ")
+    .replace(/[\\`*_[\]{}()#|!~]/g, "\\$&")
+    .replace(/[&<>"']/g, (c) => HTML[c])
+    .replace(/^([-+.=])/, "\\$1")
+    .replace(/^(\d+)\./, "$1\\.");
+}
+
+function truthy(v) {
+  if (Array.isArray(v)) return v.length > 0;
+  return Boolean(v);
+}
+
+function emit(out, s) {
+  out.size += s.length;
+  if (out.size > MAX_OUTPUT) throw new TemplateError(`Rendered report is larger than ${MAX_OUTPUT} bytes`);
+  out.parts.push(s);
+}
+
+function renderNodes(nodes, scopes, out) {
+  for (const n of nodes) {
+    if (n.type === "text") emit(out, n.value);
+    else if (n.type === "var") emit(out, escapeValue(lookup(scopes, n.path)));
+    else if (n.type === "if") renderNodes(truthy(lookup(scopes, n.path)) ? n.body : (n.alt || []), scopes, out);
+    else if (n.type === "each") {
+      const list = lookup(scopes, n.path);
+      if (!Array.isArray(list)) continue;
+      for (let i = 0; i < list.length; i++) {
+        scopes.push({ value: list[i], index: i });
+        renderNodes(n.body, scopes, out);
+        scopes.pop();
+      }
+    }
+  }
+}
+
+/** Render a template string (or a tree from parseTemplate) against a data object. */
+export function renderTemplate(template, data) {
+  const tree = typeof template === "string" ? parseTemplate(template) : template;
+  const out = { parts: [], size: 0 };
+  renderNodes(tree.body, [{ value: data, index: 0 }], out);
+  return out.parts.join("");
+}

package/src/report/timeline.js

@@ -0,0 +1,145 @@
+/**
+ * Loop timeline: found → fixed → verified per finding, with time-to-fix.
+ *
+ * Two sources, in this order:
+ *   result.loopRun          an agent loop run (`penthera agent`), either
+ *                           { iterations: [{ n, found:[fid], fixed:[{fid, recipe}],
+ *                             verified:[fid], failed:[fid], ms }] }
+ *                           or the penthera.loopRun/1 shape
+ *                           { iterations: [{ n, durationMs, fixes: [{ recipe,
+ *                             status, findings: [{ fid, title }] }] }] }
+ *   result.memory.history   fix events from the local learning store (--memory)
+ *
+ * Returns null when neither has anything to show.
+ */
+
+const fidOf = (x) => (typeof x === "string" ? x : typeof x?.fid === "string" ? x.fid : typeof x?.id === "string" ? x.id : null);
+const list = (x) => (Array.isArray(x) ? x : []);
+
+function median(nums) {
+  if (!nums.length) return null;
+  const s = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+function titles(result) {
+  const map = new Map();
+  for (const f of [...list(result?.findings), ...list(result?.suppressed)]) {
+    if (typeof f?.fid === "string" && !map.has(f.fid)) map.set(f.fid, f.title || "");
+  }
+  return map;
+}
+
+/** penthera.loopRun/1 iteration → the found/fixed/verified/failed lists. */
+function normalizeIteration(it, names) {
+  if (!Array.isArray(it?.fixes)) return it;
+  const found = [];
+  const fixed = [];
+  const verified = [];
+  const failed = [];
+  for (const fx of it.fixes) {
+    const applied = fx?.status === "verified" || fx?.status === "failed";
+    for (const f of list(fx?.findings)) {
+      const fid = fidOf(f);
+      if (!fid) continue;
+      if (typeof f.title === "string" && !names.has(fid)) names.set(fid, f.title);
+      found.push(fid);
+      if (applied) fixed.push({ fid, recipe: typeof fx.recipe === "string" ? fx.recipe : null });
+      if (fx.status === "verified") verified.push(fid);
+      if (fx.status === "failed") failed.push(fid);
+    }
+  }
+  return { n: it.n, ms: Number.isFinite(it.ms) ? it.ms : it.durationMs, found, fixed, verified, failed };
+}
+
+function fromLoop(loopRun, names) {
+  const its = list(loopRun?.iterations);
+  if (!its.length) return null;
+  const rows = new Map();
+  const row = (fid) => {
+    if (!rows.has(fid)) rows.set(fid, { fid, title: names.get(fid) || "", found: null, fixed: null, recipe: null, verified: null, failed: null, timeToFixMs: null, _start: null });
+    return rows.get(fid);
+  };
+  let elapsed = 0;
+  its.map((x) => normalizeIteration(x, names)).forEach((it, i) => {
+    const n = Number.isInteger(it?.n) ? it.n : i + 1;
+    const startMs = elapsed;
+    elapsed += Number.isFinite(it?.ms) && it.ms > 0 ? it.ms : 0;
+    for (const x of list(it?.found)) {
+      const fid = fidOf(x);
+      if (!fid) continue;
+      const r = row(fid);
+      if (r.found == null) { r.found = `iteration ${n}`; r._start = startMs; }
+    }
+    for (const x of list(it?.fixed)) {
+      const fid = fidOf(x);
+      if (!fid) continue;
+      const r = row(fid);
+      r.fixed = `iteration ${n}`;
+      r.recipe = typeof x?.recipe === "string" ? x.recipe : r.recipe;
+      if (r.found == null) { r.found = `iteration ${n}`; r._start = startMs; }
+    }
+    for (const x of list(it?.verified)) {
+      const fid = fidOf(x);
+      if (!fid) continue;
+      const r = row(fid);
+      r.verified = `iteration ${n}`;
+      r.failed = null;
+      r.timeToFixMs = elapsed - (r._start ?? startMs);
+    }
+    for (const x of list(it?.failed)) {
+      const fid = fidOf(x);
+      if (!fid) continue;
+      const r = row(fid);
+      if (!r.verified) r.failed = `iteration ${n}`;
+    }
+  });
+  const entries = [...rows.values()].map(({ _start, ...r }) => r);
+  return { source: "agent loop", iterations: its.length, totalMs: elapsed, entries };
+}
+
+function fromMemory(history, names) {
+  const fixes = list(history?.fixes);
+  if (!fixes.length) return null;
+  const entries = fixes.map((f) => {
+    const t0 = Date.parse(f.firstSeen);
+    const t1 = Date.parse(f.verified);
+    return {
+      fid: f.id,
+      title: names.get(f.id) || "",
+      found: f.firstSeen || null,
+      fixed: f.applied || null,
+      recipe: f.recipe || null,
+      verified: f.verified || null,
+      failed: f.verified ? null : (f.failed || null),
+      timeToFixMs: Number.isFinite(t0) && Number.isFinite(t1) ? Math.max(0, t1 - t0) : null,
+    };
+  });
+  return { source: "memory", iterations: null, totalMs: null, entries };
+}
+
+/** Build the timeline for a scan result, or null. */
+export function buildTimeline(result) {
+  const names = titles(result);
+  const t = fromLoop(result?.loopRun, names) || fromMemory(result?.memory?.history, names);
+  if (!t || !t.entries.length) return null;
+  const times = t.entries.map((e) => e.timeToFixMs).filter((x) => x != null);
+  return {
+    ...t,
+    verifiedCount: t.entries.filter((e) => e.verified).length,
+    failedCount: t.entries.filter((e) => e.failed).length,
+    openCount: t.entries.filter((e) => !e.verified && !e.failed).length,
+    medianTimeToFixMs: median(times),
+  };
+}
+
+/** "350 ms", "4.2 s", "12 min", "3.5 h", "2.1 days". */
+export function formatDuration(ms) {
+  if (ms == null || !Number.isFinite(ms)) return "-";
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)} min`;
+  if (ms < 86_400_000) return `${(ms / 3_600_000).toFixed(1)} h`;
+  return `${(ms / 86_400_000).toFixed(1)} days`;
+}

package/src/reporter.js

@@ -6,6 +6,8 @@
 import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { resolveWstgTags } from "../lib/owasp-wstg.js";
+import { referencesFor } from "../lib/references.js";
+import { formatDepsTerminal } from "../lib/deps/report.js";
 
 const PKG_VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
@@ -258,6 +260,15 @@ export function printReport(result, opts = {}) {
     w("");
   }
 
+  // Dependencies (penthera deps)
+  if (result.deps) {
+    w(`  ${c.dim(line())}`);
+    w(`  ${c.bold("Dependencies")}`);
+    w("");
+    for (const l of formatDepsTerminal(result.deps, c, opts)) w(l);
+    w("");
+  }
+
   // Cookies
   if (result.cookies && result.cookies.length > 0) {
     w(`  ${c.dim(line())}`);
@@ -305,6 +316,26 @@ export function printReport(result, opts = {}) {
     w("");
   }
 
+  // Agent configuration (penthera agents)
+  if (result.agents) {
+    const a = result.agents;
+    const inv = a.inventory || {};
+    const gradeColor = { A: c.green, B: c.green, C: c.yellow, D: c.red, F: c.bgRed }[a.grade] || ((s) => s);
+    w(`  ${c.dim(line())}`);
+    w(`  ${c.bold("Agent Config")}${a.home ? c.dim("  repo + home") : c.dim("  repo")}`);
+    w("");
+    w(`  Grade      ${gradeColor(` ${a.grade} `)} ${c.dim(`(${a.score}/100)`)}`);
+    w(`  Found      ${inv.skills || 0} skills · ${inv.mcpServers || 0} MCP servers · ${inv.hooks || 0} hooks · ${inv.plugins || 0} plugins · ${inv.instructionFiles || 0} rule files`);
+    if (a.lock) {
+      const l = a.lock;
+      const status = l.status === "pinned" ? c.green(`pinned ${l.entries} entries → ${l.path}`)
+        : l.status === "checked" ? (l.changed || l.added ? c.yellow(`${l.changed} changed · ${l.added} new · ${l.removed} removed`) : c.green(`all ${l.entries} entries match`))
+        : l.status === "corrupt" ? c.red("corrupt") : c.dim("none (run with --pin)");
+      w(`  Lock       ${status}`);
+    }
+    w("");
+  }
+
   // Findings
   if (result.findings && result.findings.length > 0) {
     w(`  ${c.dim(line())}`);
@@ -323,8 +354,8 @@ export function printReport(result, opts = {}) {
       // heuristic as a confirmed break. Certainties stay unannotated.
       const needsReview = f.confidence === "needs-human-review" || f.confidence === "potential";
       const tag = needsReview ? c.dim(` [${f.confidence}]`) : "";
-      w(`  ${colorFn(label)}  ${f.title}${tag}`);
-      if (f.url)  w(`  ${" ".repeat(6)} ${c.dim(f.url)}${f.status ? c.dim(` \u2192 ${f.status}`) : ""}`);
+      w(`  ${colorFn(label)}  ${f.title}${tag}${f.fid ? c.dim(`  ${f.fid}`) : ""}`);
+      if (f.url)  w(`  ${" ".repeat(6)} ${c.dim(f.url + (f.line ? `:${f.line}` : ""))}${f.status ? c.dim(` \u2192 ${f.status}`) : ""}`);
       if (f.description && opts.verbose) w(`  ${" ".repeat(6)} ${c.dim(f.description)}`);
     }
     w("");
@@ -334,6 +365,19 @@ export function printReport(result, opts = {}) {
     w("");
   }
 
+  // Suppressed by local memory or the repo's penthera.suppress.json (--memory).
+  // Always listed with who suppressed it and why, so nothing disappears silently.
+  if (result.suppressed?.length) {
+    w(`  ${c.dim(line())}`);
+    w(`  ${c.bold("Suppressed")} ${c.dim(`(${result.suppressed.length}, not counted above)`)}`);
+    w("");
+    for (const f of result.suppressed) {
+      w(`  ${c.dim(SEV_LABEL[f.severity] || "    ")}  ${f.title}${c.dim(`  ${f.fid}`)}`);
+      w(`  ${" ".repeat(6)} ${c.yellow(suppressionLabel(f.suppression))}: ${c.dim(stripControl(f.suppression?.reason))}`);
+    }
+    w("");
+  }
+
   // Compliance summary
   if (result.compliance) {
     const s = result.compliance.summary;
@@ -345,12 +389,55 @@ export function printReport(result, opts = {}) {
     w("");
   }
 
+  // Network egress: which hosts this scan talked to besides the target
+  if (result.egress) {
+    const e = result.egress;
+    w(`  ${c.dim(line())}`);
+    w(`  ${c.bold("Network")}${e.offline ? c.dim(" --offline") : ""}`);
+    w("");
+    if (e.thirdPartyHosts.length === 0) {
+      w(`  Contacted  ${c.green("scan target only")} ${c.dim(`(${e.target})`)}`);
+    } else {
+      w(`  Contacted  ${e.thirdPartyHosts.length} third-party host${e.thirdPartyHosts.length > 1 ? "s" : ""} besides the target`);
+      for (const h of e.thirdPartyHosts) w(`    ${c.dim(pad(h.host, 36))} ${h.requests} request${h.requests > 1 ? "s" : ""}`);
+    }
+    if (e.blocked.length > 0) {
+      w(`  Blocked    ${e.blocked.map((h) => h.host).join(", ")}`);
+    }
+    if (result.retireDb) {
+      w(`  Retire.js  ${result.retireDb.source === "snapshot" ? `vendored snapshot ${c.dim(`(${String(result.retireDb.snapshotDate).slice(0, 10)})`)}` : "live database"}`);
+    }
+    w("");
+  }
+
   // Summary
   w(`  ${c.dim(line())}`);
   printSummaryLine(result, w);
+  printInconclusiveLine(result, w, opts);
   w("");
 }
 
+export function suppressionLabel(s) {
+  return s?.source === "repo-file" ? "suppressed by repo file (penthera.suppress.json)" : "suppressed by local memory";
+}
+
+function stripControl(str) {
+  return String(str ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+}
+
+/** Probes whose requests failed: the scan could not decide, so say so. */
+function printInconclusiveLine(result, w, opts = {}) {
+  const errors = result.errors || [];
+  if (errors.length === 0) return;
+  const probes = [...new Set(errors.map((e) => e.probe))];
+  w(`  ${c.yellow(`${probes.length} probe${probes.length > 1 ? "s" : ""} inconclusive`)} ${c.dim(`(${probes.join(", ")})`)}`);
+  if (opts.verbose) {
+    for (const e of errors) {
+      w(`    ${c.dim(`${e.probe}: ${e.message}${e.count > 1 ? ` (x${e.count})` : ""}, ${e.url}`)}`);
+    }
+  }
+}
+
 function printSummaryLine(result, w) {
   const findings = result.findings || [];
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
@@ -424,24 +511,42 @@ function toSarifUri(location) {
  * Uploads to GitHub via: gh api repos/{owner}/{repo}/code-scanning/sarifs
  */
 export function writeSarifReport(result, filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(formatSarif(result), null, 2) + "\n");
+}
+
+/** The SARIF 2.1.0 object for a scan result. */
+export function formatSarif(result) {
   const rules = new Map();
   const results = [];
 
   for (const f of result.findings || []) {
     const ruleId = f.templateId || f.category || "unknown";
 
+    const refs = referencesFor(f);
+
     if (!rules.has(ruleId)) {
       rules.set(ruleId, {
         id: ruleId,
         name: f.title,
         shortDescription: { text: f.title },
         fullDescription: { text: f.description || f.title },
+        // Research and standards behind the rule (lib/references.json), so a
+        // reviewer in GitHub code scanning can see why it is reported.
+        ...(refs.length && {
+          helpUri: refs[0].url,
+          help: {
+            text: `Sources: ${refs.map((r) => `${r.cite}, ${r.title} (${r.url})`).join("; ")}`,
+            markdown: `**Sources:** ${refs.map((r) => `[${r.cite}](${r.url}), *${r.title}*`).join("; ")}`,
+          },
+        }),
         defaultConfiguration: {
           level: SARIF_SEV_MAP[f.severity] || "note",
         },
         properties: {
           "security-severity": sevToScore(f.severity),
           tags: ["security", f.category || "general", ...(f.wstg || resolveWstgTags(f))].filter(Boolean),
+          ...(refs.length && { references: refs.map((r) => r.key) }),
         },
       });
     }
@@ -457,6 +562,7 @@ export function writeSarifReport(result, filePath) {
           artifactLocation: {
             uri: toSarifUri(f.url),
           },
+          ...(Number.isInteger(f.line) && f.line > 0 ? { region: { startLine: f.line } } : {}),
         },
       }] : [],
       properties: {
@@ -494,9 +600,7 @@ export function writeSarifReport(result, filePath) {
       }],
     }],
   };
-
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, JSON.stringify(sarif, null, 2) + "\n");
+  return sarif;
 }
 
 function sevToScore(severity) {

package/src/scan-url.js

@@ -56,7 +56,8 @@ import { probeJwt } from "../lib/blackbox/jwt.js";
 import { probeEmailDns } from "../lib/blackbox/email-dns.js";
 import { resolveAuth } from "./utils/auth.js";
 import { normalizeBaseUrl, isPrivateHost, joinUrl } from "./utils/url.js";
-import { safeFetch } from "./utils/http.js";
+import { safeFetch, createEgressContext, runWithEgress, egressSummary, probeErrors } from "./utils/http.js";
+import { RECON_HOSTS } from "../lib/recon.js";
 import { dedupeFindings } from "./cli/merge-results.js";
 
 const SENSITIVE_RE = /private_key|SECRET|PASSWORD|API_KEY|FIREBASE_|STRIPE_|DATABASE_URL|client_email|\[core\]|\[remote/i;
@@ -70,6 +71,21 @@ const SENSITIVE_RE = /private_key|SECRET|PASSWORD|API_KEY|FIREBASE_|STRIPE_|DATA
  */
 export async function scanUrl(rawTarget, opts = {}) {
   const target = normalizeBaseUrl(rawTarget);
+  // Every request in this scan goes through one egress context: it enforces
+  // --offline, sets the User-Agent, and records hosts contacted and probe errors.
+  const ctx = createEgressContext({
+    target,
+    offline: opts.offline,
+    userAgent: opts.userAgent,
+    allowHosts: opts.allowHosts,
+  });
+  const result = await runWithEgress(ctx, () => scanUrlInContext(target, opts));
+  result.egress = egressSummary(ctx);
+  result.errors = probeErrors(ctx);
+  return result;
+}
+
+async function scanUrlInContext(target, opts) {
   const timeout = opts.timeout || 10_000;
   const concurrency = opts.concurrency || 15;
   const progress = opts.onPhase || (() => {});
@@ -104,7 +120,7 @@ export async function scanUrl(rawTarget, opts = {}) {
   // ── Phase 1: Reachability ──────────────────────────────────────────────
   progress("Checking target reachability...");
   try {
-    const res = await safeFetch(target, { timeout });
+    const res = await safeFetch(target, { timeout, probe: "reachability" });
     result.reachable = res != null && res.status < 500;
   } catch {
     result.reachable = false;
@@ -243,7 +259,7 @@ export async function scanUrl(rawTarget, opts = {}) {
 
   await Promise.allSettled(
     unchecked.map(async (file) => {
-      const res = await safeFetch(joinUrl(target, file.path), { timeout: 5_000 });
+      const res = await safeFetch(joinUrl(target, file.path), { timeout: 5_000, probe: "sensitive-files" });
       if (!res || res.status !== 200) return;
       const text = await res.text().catch(() => "");
 
@@ -281,6 +297,7 @@ export async function scanUrl(rawTarget, opts = {}) {
     const res = await safeFetch(joinUrl(target, corsEndpoint), {
       headers: { Origin: evilOrigin },
       timeout: 5_000,
+      probe: "cors",
     });
     if (!res) continue;
     const acao = res.headers.get("access-control-allow-origin");
@@ -308,6 +325,7 @@ export async function scanUrl(rawTarget, opts = {}) {
         "x-middleware-subrequest": "middleware:middleware:middleware:middleware:middleware",
       },
       timeout: 5_000,
+      probe: "framework-check",
     });
     if (res && res.status === 200) {
       const alreadyFound = result.findings.some(
@@ -330,7 +348,7 @@ export async function scanUrl(rawTarget, opts = {}) {
   // ── Phase 9: Cookie Security Audit ──────────────────────────────────────
   progress("Auditing cookie security...");
   try {
-    const cookieRes = await safeFetch(target, { timeout });
+    const cookieRes = await safeFetch(target, { timeout, probe: "cookie" });
     if (cookieRes) {
       const setCookies = cookieRes.headers.getSetCookie?.() || [];
       if (setCookies.length > 0) {
@@ -390,6 +408,9 @@ export async function scanUrl(rawTarget, opts = {}) {
       // Only count the probe as run when its database actually loaded, so the
       // WSTG and compliance coverage can't claim a check that was skipped.
       retireJsRan = jsResult.dbLoaded !== false;
+      if (jsResult.dbSource) {
+        result.retireDb = { source: jsResult.dbSource, snapshotDate: jsResult.dbSnapshotDate || null };
+      }
       if (jsResult.libraries.length > 0) {
         result.jsLibraries = jsResult.libraries;
       }
@@ -416,7 +437,10 @@ export async function scanUrl(rawTarget, opts = {}) {
   if (opts.recon && local) {
     progress("Skipping OSINT recon (localhost target)...");
   }
-  if (opts.recon && !local) {
+  if (opts.recon && !local && opts.offline) {
+    progress(`Skipping OSINT recon (--offline: no queries to ${RECON_HOSTS.join(", ")})...`);
+  }
+  if (opts.recon && !local && !opts.offline) {
     const domain = extractDomain(target);
     progress(`Running OSINT recon on ${domain}...`);
     try {
@@ -426,7 +450,7 @@ export async function scanUrl(rawTarget, opts = {}) {
       if (result.recon.endpoints.length > 0) {
         progress(`Probing ${result.recon.endpoints.length} historically known endpoints...`);
         for (const path of result.recon.endpoints.slice(0, 50)) {
-          const res = await safeFetch(`${target}${path}`, { timeout: 5_000 });
+          const res = await safeFetch(`${target}${path}`, { timeout: 5_000, probe: "recon" });
           if (res && res.status !== 404 && res.status < 500) {
             const alreadyKnown = filtered.some((ep) => ep.path === path);
             if (!alreadyKnown) {
@@ -570,7 +594,7 @@ export async function scanUrl(rawTarget, opts = {}) {
     ...(auth.bearer ? ["jwt"] : []),
     ...(!opts.skipRetireJs && retireJsRan ? ["retirejs"] : []),
     ...(!opts.skipParamDiscovery && hadEndpoints ? ["param-discovery"] : []),
-    ...(opts.recon && !local ? ["recon"] : []),
+    ...(opts.recon && !local && !opts.offline ? ["recon"] : []),
     ...(opts.deep && hadEndpoints ? ["sqli", "ssti", "ssrf", "xss", "cmdi", "open-redirect"] : []),
     ...(opts.fuzz && filtered.some((ep) => ep.path.includes("/api/") || ep.path.includes("/graphql")) ? ["api-fuzzing"] : []),
     ...(opts.adaptive ? ["adaptive"] : []),