penthera 1.1.1 → 1.4.0

package/src/report/evidence.js

@@ -0,0 +1,253 @@
+/**
+ * Evidence bundle (--evidence <dir>): the reports for one scan, a manifest.json
+ * with the SHA-256 of every artifact, and optionally manifest.json.sig, an SSH
+ * signature (`ssh-keygen -Y sign -n penthera-evidence`) over the manifest.
+ *
+ * verifyEvidence() recomputes every hash, rejects files the manifest does not
+ * list, and checks the signature with ssh-keygen. No hosted service and no new
+ * dependency: an auditor needs Node (or sha256sum and jq) and OpenSSH 8+.
+ * See docs/evidence.md.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+  readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, lstatSync,
+} from "node:fs";
+import { join, resolve, relative, sep } from "node:path";
+
+export const SCHEMA = "penthera-evidence/1";
+export const NAMESPACE = "penthera-evidence";
+export const MANIFEST = "manifest.json";
+export const SIGNATURE = "manifest.json.sig";
+
+const SAFE_PATH = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+const SECRET_FLAG = /^--?(?:auth-cookie|auth-bearer|cookie|[\w-]*(?:token|secret|password|passwd|api-key|apikey)[\w-]*)$/i;
+const SECRET_PARAM = /^(?:[\w-]*(?:token|secret|password|passwd|key|sig|signature|auth|session|code)[\w-]*)$/i;
+
+export function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+/** Mask credentials in a URL: user:pass@ and secret-looking query values. */
+function redactUrl(s) {
+  let u;
+  try {
+    u = new URL(s);
+  } catch {
+    return s;
+  }
+  if (!/^https?:$/.test(u.protocol)) return s;
+  let changed = false;
+  if (u.username || u.password) { u.username = "REDACTED"; u.password = ""; changed = true; }
+  for (const k of [...u.searchParams.keys()]) {
+    if (SECRET_PARAM.test(k)) { u.searchParams.set(k, "REDACTED"); changed = true; }
+  }
+  return changed ? u.toString() : s;
+}
+
+/**
+ * Redact secrets from a command line: the value of --auth-cookie, --auth-bearer
+ * and any flag named like a token or password (both `--flag v` and
+ * `--flag=v`), plus credentials inside URLs.
+ */
+export function redactArgv(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    const eq = a.indexOf("=");
+    if (a.startsWith("-") && eq > 0 && SECRET_FLAG.test(a.slice(0, eq))) {
+      out.push(`${a.slice(0, eq)}=[REDACTED]`);
+    } else if (SECRET_FLAG.test(a) && i + 1 < argv.length) {
+      out.push(a, "[REDACTED]");
+      i++;
+    } else {
+      out.push(redactUrl(a));
+    }
+  }
+  return out;
+}
+
+function quote(a) {
+  return /^[\w@%+=:,./[\]-]+$/.test(a) ? a : `'${a.replace(/'/g, "'\\''")}'`;
+}
+
+/** { commit, dirty } for a git checkout, or null. */
+export function gitInfo(dir) {
+  if (!dir) return null;
+  try {
+    const commit = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const status = execFileSync("git", ["-C", dir, "status", "--porcelain"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    return /^[0-9a-f]{40,64}$/.test(commit) ? { commit, dirty: status.trim().length > 0 } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when ssh-keygen is on PATH. */
+export function hasSshKeygen() {
+  const r = spawnSync("ssh-keygen", ["-?"], { stdio: "ignore" });
+  return !r.error;
+}
+
+function publicKeyFor(keyPath) {
+  const pub = keyPath.endsWith(".pub") ? keyPath : `${keyPath}.pub`;
+  if (!existsSync(pub)) return null;
+  const line = readFileSync(pub, "utf-8").trim().split("\n")[0];
+  return /^(ssh-|ecdsa-|sk-)[\w@.-]+ [A-Za-z0-9+/=]+/.test(line) ? line.split(" ").slice(0, 2).join(" ") : null;
+}
+
+/** Throws unless `dir` is missing or empty, so a bundle never mixes runs. */
+export function assertEmptyDir(dir) {
+  if (!existsSync(dir)) return;
+  if (!lstatSync(dir).isDirectory()) throw new Error(`--evidence ${dir} exists and is not a directory`);
+  if (readdirSync(dir).length) throw new Error(`--evidence ${dir} is not empty; use a new directory per run`);
+}
+
+/**
+ * Write a bundle.
+ * @param {string} dir
+ * @param {{ path: string, content: string|Buffer, kind?: string }[]} artifacts
+ * @param {{ version: string, argv: string[], target: string, generatedAt: string,
+ *           scan?: object, repo?: string|null, signKey?: string|null }} meta
+ * @returns {{ manifest: object, signed: boolean, dir: string }}
+ */
+export function writeEvidenceBundle(dir, artifacts, meta) {
+  const root = resolve(dir);
+  assertEmptyDir(root);
+  mkdirSync(root, { recursive: true });
+
+  const entries = [];
+  for (const a of artifacts) {
+    if (!SAFE_PATH.test(a.path) || a.path === MANIFEST || a.path === SIGNATURE) throw new Error(`Bad artifact path ${a.path}`);
+    const buf = Buffer.isBuffer(a.content) ? a.content : Buffer.from(String(a.content), "utf-8");
+    const file = join(root, ...a.path.split("/"));
+    mkdirSync(resolve(file, ".."), { recursive: true });
+    writeFileSync(file, buf);
+    entries.push({ path: a.path, kind: a.kind || null, bytes: buf.length, sha256: sha256(buf) });
+  }
+  entries.sort((x, y) => x.path.localeCompare(y.path));
+
+  const argv = redactArgv(meta.argv || []);
+  const signKey = meta.signKey ? resolve(meta.signKey) : null;
+  const manifest = {
+    schema: SCHEMA,
+    tool: { name: "penthera", version: meta.version, node: process.version },
+    generated_at: meta.generatedAt,
+    command: ["penthera", ...argv].map(quote).join(" "),
+    argv,
+    target: meta.target,
+    scan: meta.scan || null,
+    git: gitInfo(meta.repo),
+    artifacts: entries,
+    signature: signKey ? { namespace: NAMESPACE, file: SIGNATURE, public_key: publicKeyFor(signKey) } : null,
+  };
+  const manifestPath = join(root, MANIFEST);
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  if (signKey) signManifest(manifestPath, signKey);
+  return { manifest, signed: Boolean(signKey), dir: root };
+}
+
+/** ssh-keygen -Y sign; writes <manifest>.sig. A passphrase prompt goes to the terminal. */
+export function signManifest(manifestPath, keyPath) {
+  if (!existsSync(keyPath)) throw new Error(`--sign-key ${keyPath} not found`);
+  const r = spawnSync("ssh-keygen", ["-Y", "sign", "-f", keyPath, "-n", NAMESPACE, manifestPath], {
+    stdio: ["inherit", "pipe", "pipe"], encoding: "utf-8",
+  });
+  if (r.error) throw new Error(`Signing needs ssh-keygen (OpenSSH 8.0+): ${r.error.message}`);
+  if (r.status !== 0) throw new Error(`ssh-keygen -Y sign failed: ${(r.stderr || "").trim()}`);
+}
+
+function listFiles(root, dir = root, out = []) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = lstatSync(p);
+    if (st.isDirectory()) listFiles(root, p, out);
+    else out.push(relative(root, p).split(sep).join("/"));
+  }
+  return out;
+}
+
+function sshVerify(args, manifestBuf) {
+  const r = spawnSync("ssh-keygen", ["-Y", ...args], { input: manifestBuf, encoding: "utf-8" });
+  if (r.error) return { ok: false, missing: true, out: r.error.message };
+  return { ok: r.status === 0, out: `${r.stdout || ""}${r.stderr || ""}`.trim() };
+}
+
+function checkSignature(root, manifestBuf, allowedSigners) {
+  const sigPath = join(root, SIGNATURE);
+  if (!existsSync(sigPath)) {
+    return allowedSigners
+      ? { status: "missing", ok: false, detail: `--allowed-signers was given but there is no ${SIGNATURE}` }
+      : { status: "unsigned", ok: true, detail: "bundle is not signed; hashes only prove it is internally consistent" };
+  }
+  if (!allowedSigners) {
+    const r = sshVerify(["check-novalidate", "-n", NAMESPACE, "-s", sigPath], manifestBuf);
+    if (r.missing) return { status: "unchecked", ok: true, detail: "ssh-keygen not found; signature not checked" };
+    return r.ok
+      ? { status: "valid-unknown-signer", ok: true, detail: "signature is valid, but the signer was not checked: pass --allowed-signers" }
+      : { status: "invalid", ok: false, detail: r.out };
+  }
+  const allowed = resolve(allowedSigners);
+  if (!existsSync(allowed)) return { status: "invalid", ok: false, detail: `allowed signers file ${allowedSigners} not found` };
+  const found = spawnSync("ssh-keygen", ["-Y", "find-principals", "-f", allowed, "-s", sigPath], { encoding: "utf-8" });
+  if (found.error) return { status: "invalid", ok: false, detail: "ssh-keygen not found; cannot check the signature" };
+  const principals = (found.stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
+  if (!principals.length) return { status: "invalid", ok: false, detail: "no key in the allowed signers file made this signature" };
+  for (const principal of principals) {
+    const r = sshVerify(["verify", "-f", allowed, "-I", principal, "-n", NAMESPACE, "-s", sigPath], manifestBuf);
+    if (r.ok) return { status: "valid", ok: true, principal, detail: `signed by ${principal}` };
+  }
+  return { status: "invalid", ok: false, detail: "signature does not verify against the allowed signers" };
+}
+
+/**
+ * Verify a bundle. Never throws on a bad bundle; returns { ok, ... }.
+ * @param {string} dir
+ * @param {{ allowedSigners?: string }} opts
+ */
+export function verifyEvidence(dir, { allowedSigners = null } = {}) {
+  const root = resolve(dir);
+  const problems = [];
+  const files = [];
+  const fail = (msg) => ({ ok: false, problems: [msg], files, unlisted: [], signature: null, manifest: null });
+
+  const manifestPath = join(root, MANIFEST);
+  if (!existsSync(manifestPath)) return fail(`${MANIFEST} not found in ${dir}`);
+  const manifestBuf = readFileSync(manifestPath);
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBuf.toString("utf-8"));
+  } catch (e) {
+    return fail(`${MANIFEST} is not valid JSON: ${e.message}`);
+  }
+  if (manifest?.schema !== SCHEMA || !Array.isArray(manifest.artifacts)) return fail(`${MANIFEST} is not a ${SCHEMA} manifest`);
+
+  const listed = new Set();
+  for (const a of manifest.artifacts) {
+    const path = a?.path;
+    if (typeof path !== "string" || !SAFE_PATH.test(path) || path === MANIFEST || path === SIGNATURE || listed.has(path)) {
+      problems.push(`unsafe or duplicate artifact path ${JSON.stringify(path)}`);
+      continue;
+    }
+    listed.add(path);
+    const file = join(root, ...path.split("/"));
+    const st = existsSync(file) ? lstatSync(file) : null;
+    if (!st) { files.push({ path, ok: false, reason: "missing" }); continue; }
+    if (!st.isFile()) { files.push({ path, ok: false, reason: "not a regular file" }); continue; }
+    const actual = sha256(readFileSync(file));
+    if (typeof a.sha256 !== "string" || actual !== a.sha256.toLowerCase()) {
+      files.push({ path, ok: false, reason: "hash mismatch", expected: a.sha256, actual });
+    } else {
+      files.push({ path, ok: true, sha256: actual });
+    }
+  }
+  const unlisted = listFiles(root).filter((p) => p !== MANIFEST && p !== SIGNATURE && !listed.has(p));
+  for (const p of unlisted) problems.push(`${p} is in the bundle but not in the manifest`);
+  for (const f of files) if (!f.ok) problems.push(`${f.path}: ${f.reason}`);
+
+  const signature = checkSignature(root, manifestBuf, allowedSigners);
+  if (!signature.ok) problems.push(`signature: ${signature.detail}`);
+
+  return { ok: problems.length === 0, problems, files, unlisted, signature, manifest };
+}

package/src/report/markdown.js

@@ -7,6 +7,8 @@ import { buildWstgCoverage, formatWstgMarkdown } from "../../lib/owasp-wstg.js";
 import { formatComplianceMarkdown } from "../../lib/compliance/index.js";
 import { buildActionPlan, formatActionPlanMarkdown } from "../../lib/remediation/index.js";
 import { formatAuditLoopMarkdown } from "../../lib/audit-loop.js";
+import { referencesFor, formatSourcesMarkdown } from "../../lib/references.js";
+import { formatDepsMarkdown } from "../../lib/deps/report.js";
 
 const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 const SEV_TAG = {
@@ -59,6 +61,12 @@ export function formatMarkdownReport(result, opts = {}) {
   lines.push(`| **Mode** | ${result.modes?.join(", ") || result.mode || "-"} |`);
   lines.push(`| **Reachable** | ${result.reachable ? "Yes" : "No"} |`);
   if (result.profile) lines.push(`| **Profile** | ${result.profile} |`);
+  if (result.agents) {
+    lines.push(`| **Agent config grade** | **${result.agents.grade}** (${result.agents.score}/100) |`);
+    const inv = result.agents.inventory || {};
+    lines.push(`| **Agent config found** | ${inv.skills || 0} skills, ${inv.mcpServers || 0} MCP servers, ${inv.hooks || 0} hooks, ${inv.plugins || 0} plugins |`);
+    if (result.agents.lock) lines.push(`| **penthera.lock** | ${result.agents.lock.status} |`);
+  }
   lines.push("");
 
   const total = findings.length;
@@ -98,6 +106,10 @@ export function formatMarkdownReport(result, opts = {}) {
     lines.push(formatComplianceMarkdown(result.compliance));
   }
 
+  if (result.deps) {
+    lines.push(formatDepsMarkdown(result.deps));
+  }
+
   if (result.fingerprint) {
     lines.push("## Technology fingerprint");
     lines.push("");
@@ -144,17 +156,68 @@ export function formatMarkdownReport(result, opts = {}) {
       lines.push("");
 
       for (const f of group) {
-        if (!f.description) continue;
+        const refs = referencesFor(f);
+        if (!f.description && refs.length === 0) continue;
         lines.push(`**${f.title}**`);
         lines.push("");
-        lines.push(f.description);
+        if (f.description) lines.push(f.description);
         if (f.url) lines.push(`\n- URL: ${f.url}`);
         if (f.status) lines.push(`- HTTP status: ${f.status}`);
+        if (refs.length) lines.push(`- Why this matters / Sources: ${formatSourcesMarkdown(refs)}`);
         lines.push("");
       }
     }
   }
 
+  if (result.suppressed?.length) {
+    lines.push("## Suppressed findings");
+    lines.push("");
+    lines.push("Hidden from the findings above by `--memory`. Review these: a suppression is a decision someone made, not a fix.");
+    lines.push("");
+    lines.push("| Finding | Severity | Suppressed by | Reason | Id |");
+    lines.push("|---------|----------|---------------|--------|----|");
+    for (const f of result.suppressed) {
+      const by = f.suppression?.source === "repo-file" ? "**suppressed by repo file** (`penthera.suppress.json`)" : "suppressed by local memory";
+      lines.push(`| ${mdEscape(f.title)} | ${f.severity || "-"} | ${by} | ${mdEscape(f.suppression?.reason)} | \`${f.fid}\` |`);
+    }
+    lines.push("");
+  }
+
+  const errors = result.errors || [];
+  if (errors.length > 0) {
+    const probes = new Set(errors.map((e) => e.probe));
+    lines.push("## Inconclusive probes");
+    lines.push("");
+    lines.push(`${probes.size} probe(s) could not complete. Their silence is not a clean result.`);
+    lines.push("");
+    lines.push("| Probe | URL | Error | Count |");
+    lines.push("|-------|-----|-------|-------|");
+    for (const e of errors) {
+      lines.push(`| ${mdEscape(e.probe)} | \`${mdEscape(e.url)}\` | ${mdEscape(e.message)} | ${e.count || 1} |`);
+    }
+    lines.push("");
+  }
+
+  if (result.egress) {
+    const e = result.egress;
+    lines.push("## Network egress");
+    lines.push("");
+    lines.push(`- **Mode:** ${e.offline ? "--offline (scan target only)" : "online"}`);
+    lines.push(`- **User-Agent:** \`${mdEscape(e.userAgent)}\``);
+    if (e.thirdPartyHosts.length === 0) {
+      lines.push(`- **Third-party hosts contacted:** none`);
+    } else {
+      lines.push(`- **Third-party hosts contacted:** ${e.thirdPartyHosts.map((h) => `\`${h.host}\` (${h.requests})`).join(", ")}`);
+    }
+    if (e.blocked.length > 0) {
+      lines.push(`- **Blocked by --offline:** ${e.blocked.map((h) => `\`${h.host}\` (${h.requests})`).join(", ")}`);
+    }
+    if (result.retireDb) {
+      lines.push(`- **Retire.js database:** ${result.retireDb.source === "snapshot" ? `vendored snapshot from ${result.retireDb.snapshotDate}` : "live"}`);
+    }
+    lines.push("");
+  }
+
   const actionPlan = result.actionPlan || buildActionPlan(findings);
   if (actionPlan.length > 0) {
     lines.push(formatActionPlanMarkdown(actionPlan));

package/src/report/model.js

@@ -0,0 +1,212 @@
+/**
+ * The report model: one plain-data view of a scan result that the audience
+ * reports (developer, owner, auditor) and user templates (--report-template)
+ * render from. Everything here is strings, numbers, booleans, arrays and plain
+ * objects, so a template can only print data, never reach code.
+ */
+import { referencesFor } from "../../lib/references.js";
+import { resolveWstgTags } from "../../lib/owasp-wstg.js";
+import { buildComplianceCoverage } from "../../lib/compliance/index.js";
+import { buildActionPlan } from "../../lib/remediation/index.js";
+import { confidenceFor } from "../../lib/provenance.js";
+import { RECIPES } from "../../lib/fix/index.js";
+import { OWASP_NAMES } from "../../lib/agents/owasp.js";
+import { findingId } from "../../lib/memory/views.js";
+import { buildTimeline, formatDuration } from "./timeline.js";
+
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+export const CONFIDENCE_LABELS = [
+  { label: "confirmed", meaning: "Deterministic evidence: a header is absent, a certificate has expired, a secret is in the file." },
+  { label: "likely", meaning: "A strong signal with a small chance of a false positive." },
+  { label: "potential", meaning: "A heuristic or timing signal. It needs a second source before anyone acts on it." },
+  { label: "needs-human-review", meaning: "A scanner cannot judge exploitability here (access control, IDOR). A person has to look." },
+];
+
+// OWASP Top 10 (2021) category per finding category. Categories without a
+// clean match (email DNS, fuzzing noise, machine audit) are left unmapped.
+export const OWASP_TOP10 = {
+  "A01:2021": "Broken Access Control",
+  "A02:2021": "Cryptographic Failures",
+  "A03:2021": "Injection",
+  "A05:2021": "Security Misconfiguration",
+  "A06:2021": "Vulnerable and Outdated Components",
+  "A07:2021": "Identification and Authentication Failures",
+  "A10:2021": "Server-Side Request Forgery",
+};
+const CATEGORY_TOP10 = {
+  "auth-bypass": "A01:2021", "open-redirect": "A01:2021", permissions: "A01:2021",
+  tls: "A02:2021", transport: "A02:2021",
+  sqli: "A03:2021", xss: "A03:2021", ssti: "A03:2021", cmdi: "A03:2021", injection: "A03:2021",
+  headers: "A05:2021", cors: "A05:2021", "cors-misconfiguration": "A05:2021", cookie: "A05:2021",
+  config: "A05:2021", exposure: "A05:2021", "info-leak": "A05:2021", disclosure: "A05:2021",
+  "method-confusion": "A05:2021", "content-type-confusion": "A05:2021",
+  cve: "A06:2021", "js-vulnerability": "A06:2021", "dependency-risk": "A06:2021",
+  auth: "A07:2021", secrets: "A07:2021", "rate-limiting": "A07:2021",
+  ssrf: "A10:2021",
+};
+
+const PLAIN = { critical: "serious", high: "serious", medium: "moderate", low: "minor", info: "note" };
+
+function isHttp(u) {
+  return typeof u === "string" && /^https?:\/\//i.test(u);
+}
+
+function locationOf(f) {
+  if (isHttp(f.url)) return { file: null, line: null, url: f.url, location: f.url };
+  const file = f.file || f.url || null;
+  const line = Number.isInteger(f.line) && f.line > 0 ? f.line : null;
+  return { file, line, url: null, location: file ? (line ? `${file}:${line}` : file) : null };
+}
+
+function recipeFor(f) {
+  for (const r of RECIPES) {
+    try {
+      if (r.matches(f)) return r.id;
+    } catch {
+      // a recipe that cannot judge this finding does not claim it
+    }
+  }
+  return null;
+}
+
+const keyOf = (f) => `${f.category || ""}|${f.title || ""}|${f.url || ""}`;
+
+/** Map each finding key to a fix plan (from result.fixPlans, e.g. an agent loop). */
+function plansByFinding(plans) {
+  const map = new Map();
+  for (const p of Array.isArray(plans) ? plans : []) {
+    for (const f of p?.findings || []) map.set(keyOf(f), p);
+  }
+  return map;
+}
+
+/** Build the report model for a scan result. */
+export function buildReportModel(result, { version = "0.0.0" } = {}) {
+  const raw = [...(result?.findings || [])].sort((a, b) => (SEV_ORDER[a.severity] ?? 5) - (SEV_ORDER[b.severity] ?? 5));
+  const actionPlan = result?.actionPlan || buildActionPlan(raw);
+  const plans = plansByFinding(result?.fixPlans);
+  const timeline = buildTimeline(result);
+  const loopRecipe = new Map((timeline?.entries || []).filter((e) => e.recipe).map((e) => [e.fid, e.recipe]));
+
+  const findings = raw.map((f, i) => {
+    const loc = locationOf(f);
+    const plan = plans.get(keyOf(f));
+    const action = actionPlan.find((a) => a.findings.some((x) => x.title === f.title && (x.url || null) === (f.url || null)));
+    const top10 = CATEGORY_TOP10[f.category] || null;
+    return {
+      n: i + 1,
+      fid: f.fid || findingId(f),
+      title: String(f.title || "Untitled finding"),
+      severity: f.severity || "info",
+      plainSeverity: PLAIN[f.severity] || "note",
+      category: f.category || null,
+      confidence: confidenceFor(f),
+      source: f.source || null,
+      method: f.method || f.source || null,
+      collectedAt: f.collected_at || result?.timestamp || null,
+      description: f.description || null,
+      ...loc,
+      recipe: plan?.recipe || loopRecipe.get(f.fid) || recipeFor(f),
+      diff: plan?.diff || null,
+      fixText: action?.fix || null,
+      sources: referencesFor(f).map((r) => ({ cite: r.cite, url: r.url })),
+      owasp: [
+        ...(top10 ? [`${top10} ${OWASP_TOP10[top10]}`] : []),
+        ...(Array.isArray(f.owasp) ? f.owasp.map((id) => OWASP_NAMES[id] || id) : []),
+      ],
+      wstg: resolveWstgTags(f),
+    };
+  });
+
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) if (counts[f.severity] != null) counts[f.severity]++;
+
+  const suppressed = (result?.suppressed || []).map((f) => ({
+    fid: f.fid || findingId(f),
+    title: String(f.title || ""),
+    severity: f.severity || "info",
+    reason: f.suppression?.reason || "",
+    actor: f.suppression?.actor || "unknown",
+    by: f.suppression?.source === "repo-file" ? "repo file (penthera.suppress.json)" : "local memory",
+    expires: f.suppression?.expires || null,
+  }));
+
+  const inconclusive = (result?.errors || []).map((e) => ({
+    probe: e.probe || "", url: e.url || "", message: e.message || "", count: e.count || 1,
+  }));
+
+  const e = result?.egress || null;
+  const egress = e ? {
+    mode: e.offline ? "offline (scan target only)" : "online",
+    userAgent: e.userAgent || "",
+    thirdPartyHosts: (e.thirdPartyHosts || []).map((h) => ({ host: h.host, requests: h.requests })),
+    blocked: (e.blocked || []).map((h) => ({ host: h.host, requests: h.requests })),
+  } : null;
+
+  const actions = actionPlan.map((a, i) => ({
+    n: i + 1, id: a.id, action: a.action, why: a.why, fix: a.fix, effort: a.effort,
+    severity: a.severity, ownerAction: Boolean(a.ownerAction), findingCount: a.findings.length,
+  }));
+  const ownerActions = actions.filter((a) => a.ownerAction);
+  for (const p of Array.isArray(result?.fixPlans) ? result.fixPlans : []) {
+    for (const text of p?.ownerActions || []) {
+      if (typeof text === "string") ownerActions.push({ n: ownerActions.length + 1, id: p.recipe, action: text, why: "", fix: "", effort: "", severity: "", ownerAction: true, findingCount: (p.findings || []).length });
+    }
+  }
+
+  const coverage = result?.compliance?.framework === "nis2" ? result.compliance : buildComplianceCoverage(result || {}, "nis2");
+  const nis2 = coverage.measures.map((m) => ({ id: m.id, title: m.title, status: m.status, findings: m.findings || 0, note: m.note || "" }));
+
+  const owaspMap = new Map();
+  for (const f of findings) {
+    for (const o of f.owasp) {
+      if (!owaspMap.has(o)) owaspMap.set(o, []);
+      owaspMap.get(o).push(f.fid || `#${f.n}`);
+    }
+  }
+  const owasp = [...owaspMap].sort(([a], [b]) => a.localeCompare(b)).map(([id, ids]) => ({ id, count: ids.length, findings: ids.join(", ") }));
+
+  const trend = (result?.memory?.history?.trend || []).map((t) => ({
+    date: String(t.ts).slice(0, 10), serious: t.critical + t.high, critical: t.critical, high: t.high,
+    medium: t.medium, low: t.low, total: t.total, suppressed: t.suppressed,
+  }));
+
+  return {
+    tool: { name: "penthera", version },
+    target: result?.target || "unknown",
+    timestamp: result?.timestamp || null,
+    duration: result?.duration ? formatDuration(result.duration) : null,
+    modes: (result?.modes || (result?.mode ? [result.mode] : [])).join(", "),
+    profile: result?.profile || null,
+    offline: Boolean(e?.offline),
+    probes: [...(result?.executedProbes || [])].sort(),
+    summary: {
+      ...counts,
+      serious: counts.critical + counts.high,
+      total: findings.length,
+      suppressed: suppressed.length,
+      inconclusive: new Set(inconclusive.map((x) => x.probe)).size,
+      target: result?.target || "unknown",
+      timestamp: result?.timestamp || null,
+    },
+    findings,
+    suppressed,
+    inconclusive,
+    egress,
+    actions,
+    topActions: actions.slice(0, 3),
+    ownerActions,
+    nis2,
+    owasp,
+    trend,
+    timeline: timeline ? {
+      source: timeline.source,
+      verified: timeline.verifiedCount,
+      failed: timeline.failedCount,
+      open: timeline.openCount,
+      medianTimeToFix: formatDuration(timeline.medianTimeToFixMs),
+      entries: timeline.entries.map((x) => ({ ...x, timeToFix: formatDuration(x.timeToFixMs) })),
+    } : null,
+  };
+}