penthera 1.2.0 → 1.4.0

package/src/cli.js

@@ -5,7 +5,7 @@
  */
 import { parseArgs } from "node:util";
 import { resolve, dirname } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { scanUrl } from "./scan-url.js";
 import { scanRepo } from "./scan-repo.js";
@@ -15,6 +15,7 @@ import { compareWithBaseline } from "./cli/baseline.js";
 import { normalizeBaseUrl } from "./utils/url.js";
 import { printReport, printFindings, writeJsonReport, writeSarifReport, createProgress, printError } from "./reporter.js";
 import { writeMarkdownReport, markdownPathFromJson } from "./report/markdown.js";
+import { prepareReportOptions, customReport, writeEvidence } from "./cli/report-outputs.js";
 import { parseTemplatePaths } from "../lib/plugins.js";
 import { buildComplianceCoverage, listFrameworks } from "../lib/compliance/index.js";
 import { buildActionPlan } from "../lib/remediation/index.js";
@@ -55,6 +56,13 @@ const HELP = `
     $ penthera <url>                 Scan a live URL (black-box)
     $ penthera --repo <path>         Scan a local repo (white-box)
     $ penthera <url> --repo <path>   Full scan (both)
+    $ penthera agents [path]         Audit AI agent config: skills, MCP, hooks (offline)
+    $ penthera deps [path]           What your npm dependencies can do (offline)
+    $ penthera install <pkg...>      Check what an npm install adds before anything runs
+    $ penthera memory show|verify|forget  Local learning store (never leaves the machine)
+    $ penthera fix --plan            Plan local fix recipes (penthera fix --help)
+    $ penthera evidence verify <dir> Check an evidence bundle's hashes and signature
+    $ penthera agent --loop          Scan, fix, verify, learn; local commits only (--help)
 
   ${dim("Scan modes")}
         --profile <name>        quick | standard | deep (default: standard)
@@ -68,6 +76,22 @@ const HELP = `
         --adaptive              Knowledge-graph adaptive probes on discovered routes
         --all                   Enable all modes (recon + deep + fuzz)
         --machine               macOS machine audit (keyloggers, trojans, rootkits)
+        --offline               Contact only the scan target: no recon sources, no
+                               Retire.js download (uses the vendored snapshot)
+
+  ${dim("Agents mode")}  ${dim("(penthera agents [path], offline, read-only)")}
+        --home                  Also audit ~/.claude, ~/.cursor and Claude Desktop config
+        --pin                   Write penthera.lock (SHA-256 of skills, MCP servers, hooks)
+
+  ${dim("Deps mode")}  ${dim("(penthera deps [path], reads package-lock.json + node_modules, offline)")}
+        --diff <lock|dir>       Capability diff against an old lockfile or installed tree
+        --base <git-ref>        Capability diff against the lockfile at a git ref
+        --online                Also check npm registry metadata (the only network use)
+        --prod                  Skip devDependencies
+        --pr-comment <file>     Write a short Markdown capability diff for a PR comment
+
+  ${dim("Install mode")}  ${dim("(penthera install [pkg...]; penthera install --help for all options)")}
+        --yes / --dry-run       Install only if nothing breaches the policy / report only
 
   ${dim("Options")}
     -r, --repo <path>       Path to repo for source analysis
@@ -75,6 +99,10 @@ const HELP = `
     -o, --output <file>     Write JSON report (+ companion .md if .json)
         --markdown <file>   Write Markdown report (human-readable)
         --sarif <file>      Write SARIF report (GitHub Security tab)
+        --audience <who>    developer | owner | auditor report (for --markdown or stdout)
+        --report-template <file.md>  Your own Markdown template ({{summary.critical}}, {{#each findings}})
+        --evidence <dir>    Evidence bundle: all reports + manifest.json with SHA-256s
+        --sign-key <key>    Sign the bundle's manifest with an SSH key (ssh-keygen -Y sign)
         --baseline <file>   Compare against previous JSON report
         --framework <name>  Add a compliance mapping to reports (nis2)
         --readiness         NIS2 readiness report (scan + self-assessment)
@@ -87,12 +115,14 @@ const HELP = `
         --incident-init <file>  Write a blank incident template and exit
         --sbom <file>       Write a CycloneDX software bill of materials (from --repo)
         --history <file>    Track findings over time (time-to-fix, ageing, drift)
+        --memory            Learn from this scan locally; apply suppressions + ranking
         --suppliers <file>  Passively rate suppliers' public domains (RAG, measure d)
         --auth-cookie <v>   Cookie header for authenticated scans
         --auth-bearer <v>   Bearer token for authenticated scans
         --json              Output JSON to stdout
         --timeout <ms>      Request timeout (default: 10000)
         --concurrency <n>   Concurrent requests (default: 15)
+        --user-agent <ua>   User-Agent header (default: penthera/${pkg.version} (+https://github.com/danoszz/penthera))
     -v, --verbose           Detailed output
     -q, --quiet             Findings only (for piping)
     -h, --help              Show this help
@@ -101,6 +131,7 @@ const HELP = `
   ${dim("Examples")}
     $ penthera https://myapp.com
     $ penthera https://myapp.com --recon --deep
+    $ penthera http://localhost:3000 --offline
     $ penthera https://myapp.com --profile quick -o report.json
     $ penthera https://myapp.com --profile deep -o report.json --markdown report.md
     $ penthera https://myapp.com --baseline reports/previous.json
@@ -109,6 +140,10 @@ const HELP = `
     $ penthera https://myapp.com --adaptive -o report.json
     $ penthera https://myapp.com --templates ./my-templates -o report.json
     $ penthera https://myapp.com --sarif results.sarif --json | jq '.findings[]'
+    $ penthera agents . --home
+    $ penthera agents --pin
+    $ penthera deps --base origin/main
+    $ penthera deps --diff ../base-checkout --pr-comment deps.md
 
   ${dim("Exit codes")}
     0  No critical or high findings
@@ -120,6 +155,32 @@ function bold(s) { return `\x1b[1m${s}\x1b[0m`; }
 function dim(s) { return `\x1b[2m${s}\x1b[0m`; }
 
 export async function run() {
+  if (process.argv[2] === "memory") {
+    const { runMemoryCommand } = await import("./cli/memory.js");
+    process.exit(await runMemoryCommand(process.argv.slice(3)));
+  }
+
+  if (process.argv[2] === "install") {
+    const { runInstall } = await import("./cli/install.js");
+    process.exitCode = await runInstall(process.argv.slice(3));
+    return;
+  }
+
+  if (process.argv[2] === "evidence") {
+    const { runEvidence } = await import("./cli/evidence.js");
+    process.exit(runEvidence(process.argv.slice(3)));
+  }
+
+  if (process.argv[2] === "fix") {
+    const { runFix } = await import("./cli/fix.js");
+    return runFix(process.argv.slice(3));
+  }
+
+  if (process.argv[2] === "agent") {
+    const { runAgent } = await import("./cli/agent.js");
+    process.exit(await runAgent(process.argv.slice(3)));
+  }
+
   let parsed;
   try {
     parsed = parseArgs({
@@ -130,6 +191,10 @@ export async function run() {
         output:      { type: "string",  short: "o" },
         markdown:    { type: "string" },
         sarif:       { type: "string" },
+        audience:    { type: "string" },
+        "report-template": { type: "string" },
+        evidence:    { type: "string" },
+        "sign-key":  { type: "string" },
         baseline:    { type: "string" },
         framework:   { type: "string" },
         readiness:   { type: "boolean", default: false },
@@ -142,7 +207,13 @@ export async function run() {
         "incident-init": { type: "string" },
         sbom:        { type: "string" },
         history:     { type: "string" },
+        memory:      { type: "boolean", default: false },
         suppliers:   { type: "string" },
+        diff:        { type: "string" },
+        base:        { type: "string" },
+        online:      { type: "boolean", default: false },
+        "pr-comment": { type: "string" },
+        prod:        { type: "boolean", default: false },
         profile:     { type: "string" },
         "auth-cookie": { type: "string" },
         "auth-bearer": { type: "string" },
@@ -155,6 +226,10 @@ export async function run() {
         adaptive:    { type: "boolean", default: false },
         all:         { type: "boolean", default: false },
         machine:     { type: "boolean", default: false },
+        home:        { type: "boolean", default: false },
+        pin:         { type: "boolean", default: false },
+        offline:     { type: "boolean", default: false },
+        "user-agent": { type: "string" },
         timeout:     { type: "string",  default: "10000" },
         concurrency: { type: "string",  default: "15" },
         verbose:     { type: "boolean", short: "v", default: false },
@@ -217,6 +292,11 @@ export async function run() {
     process.exit(0);
   }
 
+  if (opts.suppliers && opts.offline) {
+    printError("--suppliers rates third-party domains, which --offline forbids.");
+    process.exit(2);
+  }
+
   if (opts.suppliers) {
     let text;
     try {
@@ -240,21 +320,52 @@ export async function run() {
     process.exit(0);
   }
 
+  // `penthera deps [path]`: offline dependency capability scan and diff.
+  if (positionals[0] === "deps") {
+    const { runDeps } = await import("./cli/deps.js");
+    await runDeps(positionals.slice(1), opts, { version: pkg.version });
+    return;
+  }
+  if (opts.diff || opts.base || opts.online || opts["pr-comment"] || opts.prod) {
+    printError("--diff, --base, --online, --prod and --pr-comment only apply to `penthera deps`.");
+    process.exit(2);
+  }
+
   if (shouldRunOnboarding(positionals, opts)) {
     const { runOnboarding } = await import("./cli/onboarding.js");
     await runOnboarding();
     return;
   }
 
-  const url = positionals[0] ? normalizeBaseUrl(positionals[0]) : null;
+  // `penthera agents [path]`: offline audit of skills, MCP servers, hooks, plugins.
+  const agentsMode = positionals[0] === "agents";
+  const agentsRoot = agentsMode ? resolve(positionals[1] || ".") : null;
+  if (agentsMode && positionals.length > 2) {
+    printError(`agents takes one path, got: ${positionals.slice(1).join(" ")}`);
+    process.exit(2);
+  }
+  if ((opts.home || opts.pin) && !agentsMode) {
+    printError("--home and --pin only apply to `penthera agents`.");
+    process.exit(2);
+  }
+
+  const url = positionals[0] && !agentsMode ? normalizeBaseUrl(positionals[0]) : null;
   const repo = opts.repo || null;
 
-  if (!url && !repo && !opts.machine && !opts.readiness && !opts["policy-pack"] && !opts.sbom && !opts.questionnaire) {
+  if (!agentsMode && !url && !repo && !opts.machine && !opts.readiness && !opts["policy-pack"] && !opts.sbom && !opts.questionnaire) {
     printError("No target specified. Provide a URL, --repo, --machine, --readiness, --policy-pack, --sbom, --questionnaire, or combine them.");
     console.log(HELP);
     process.exit(2);
   }
 
+  let reportCtx;
+  try {
+    reportCtx = prepareReportOptions(opts);
+  } catch (e) {
+    printError(e.message);
+    process.exit(2);
+  }
+
   // Resolve scan profile
   let profileOpts;
   try {
@@ -297,6 +408,8 @@ export async function run() {
     verbose: opts.verbose,
     authCookie: opts["auth-cookie"] || null,
     authBearer: opts["auth-bearer"] || null,
+    offline: opts.offline,
+    userAgent: opts["user-agent"] || null,
     onPhase: createProgress(opts.quiet || opts.json),
   };
 
@@ -321,6 +434,15 @@ export async function run() {
       results.push(repoResult);
     }
 
+    if (agentsMode) {
+      if (!existsSync(agentsRoot)) {
+        printError(`Path not found: ${agentsRoot}`);
+        process.exit(2);
+      }
+      const { scanAgents } = await import("../lib/agents/index.js");
+      results.push(await scanAgents(agentsRoot, { home: opts.home, pin: opts.pin, onPhase: scanOpts.onPhase }));
+    }
+
     if (opts.machine) {
       const { auditMachine } = await import("../lib/machine.js");
       const machineResult = await auditMachine({ onPhase: scanOpts.onPhase });
@@ -342,6 +464,13 @@ export async function run() {
   const merged = mergeResults(results);
   merged.profile = profileOpts.profile;
 
+  // Local learning store (opt-in): suppress + rank from ~/.penthera/memory, then record this scan.
+  if (opts.memory && (url || repo)) {
+    const { applyMemoryToScan } = await import("../lib/memory/index.js");
+    const { warnings } = applyMemoryToScan(merged, { repo: repo ? resolve(repo) : null, url });
+    for (const w of warnings) process.stderr.write(`  \x1b[33mWARN\x1b[0m ${w}\n`);
+  }
+
   // Compliance framework mapping (e.g. --framework nis2)
   if (opts.framework) {
     const coverage = buildComplianceCoverage(merged, opts.framework);
@@ -409,10 +538,13 @@ export async function run() {
   }
 
   const mdOpts = { version: pkg.version, baseline: baselineStats };
+  const custom = customReport(merged, opts, { version: pkg.version, template: reportCtx.template });
 
   // Output
   if (opts.json) {
     console.log(JSON.stringify(merged, null, 2));
+  } else if (custom && !opts.markdown) {
+    process.stdout.write(custom);
   } else if (opts.quiet) {
     printFindings(merged.findings);
   } else {
@@ -430,7 +562,8 @@ export async function run() {
   }
 
   if (opts.markdown) {
-    writeMarkdownReport(merged, opts.markdown, mdOpts);
+    if (custom) writeFileSync(resolve(opts.markdown), custom);
+    else writeMarkdownReport(merged, opts.markdown, mdOpts);
     if (!opts.quiet && !opts.json) {
       process.stderr.write(`  Markdown report ${opts.markdown}\n`);
     }
@@ -459,9 +592,10 @@ export async function run() {
     }
   }
 
+  let sbom = null;
   if (opts.sbom) {
     const sbomRepo = resolve(opts.repo || ".");
-    const sbom = buildSbom(sbomRepo, {
+    sbom = buildSbom(sbomRepo, {
       serialNumber: `urn:uuid:${randomUUID()}`,
       timestamp: new Date().toISOString(),
     });
@@ -514,6 +648,18 @@ export async function run() {
     }
   }
 
+  if (opts.evidence) {
+    try {
+      const bundle = writeEvidence(merged, opts, { version: pkg.version, template: reportCtx.template, mdOpts, sbom, argv: process.argv.slice(2) });
+      if (!opts.quiet && !opts.json) {
+        process.stderr.write(`  Evidence bundle ${bundle.manifest.artifacts.length} files${bundle.signed ? ", signed" : ""} → ${opts.evidence}/ (penthera evidence verify ${opts.evidence})\n`);
+      }
+    } catch (e) {
+      printError(`Could not write the evidence bundle: ${e.message}`);
+      process.exit(2);
+    }
+  }
+
   if (merged.auditLoop && !opts.quiet && !opts.json) {
     const a = merged.auditLoop;
     process.stderr.write(
@@ -522,7 +668,7 @@ export async function run() {
     );
   }
 
-  if ((opts.output || opts.markdown || opts.sarif || opts.readiness || opts["policy-pack"] || opts.sbom || opts.history || opts.questionnaire) && !opts.quiet && !opts.json) {
+  if ((opts.output || opts.markdown || opts.sarif || opts.evidence || opts.readiness || opts["policy-pack"] || opts.sbom || opts.history || opts.questionnaire) && !opts.quiet && !opts.json) {
     process.stderr.write("\n");
   }
 

package/src/report/audience.js

@@ -0,0 +1,270 @@
+/**
+ * Audience reports (--audience developer | owner | auditor), rendered from the
+ * report model. The default report (src/report/markdown.js) is unchanged.
+ *
+ *   developer  findings with file:line, fix recipe or diff, how to fix, sources
+ *   owner      plain-language summary, top three things to do, owner actions, trend
+ *   auditor    scope and method, confidence and provenance, egress, inconclusive
+ *              probes, suppressions (who and why), loop timeline, NIS2 and OWASP
+ */
+import { buildReportModel, CONFIDENCE_LABELS } from "./model.js";
+
+export const AUDIENCES = ["developer", "owner", "auditor"];
+
+const METHODOLOGY_URL = "https://github.com/danoszz/penthera/blob/main/docs/METHODOLOGY.md";
+const EVIDENCE_URL = "https://github.com/danoszz/penthera/blob/main/docs/evidence.md";
+const SEV_TAG = { critical: "CRITICAL", high: "HIGH", medium: "MEDIUM", low: "LOW", info: "INFO" };
+const NIS2_STATUS = {
+  "tested-clean": "Tested, no gaps found",
+  "tested-findings": "Tested, gaps found",
+  "not-run": "Not run this scan",
+  evidence: "Evidence only",
+  planned: "Planned",
+  "out-of-scope": "Out of scope",
+};
+
+/** Inline text: one line, no table breaks, no raw HTML. */
+function md(s) {
+  return String(s ?? "").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\r?\n|\r/g, " ")
+    .replace(/\\/g, "\\\\").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "\\|");
+}
+/** Penthera's own remediation text (lib/remediation): may hold code spans, so only fold lines. */
+function prose(s) {
+  return String(s ?? "").replace(/\r?\n|\r/g, " ");
+}
+/** A code span that its content cannot close. */
+function code(s) {
+  return `\`${String(s ?? "").replace(/[`\r\n]/g, " ")}\``;
+}
+function when(iso) {
+  return iso ? `${String(iso).replace("T", " ").slice(0, 19)} UTC` : "-";
+}
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function sources(list) {
+  return list.map((r) => `[${md(r.cite)}](${r.url})`).join(" · ");
+}
+
+function header(L, title, m) {
+  L.push(`# ${title}`, "");
+  L.push(`> ${md(m.target)} · scanned ${when(m.timestamp)} · Penthera v${m.tool.version}`, "");
+}
+
+function footer(L) {
+  L.push("---", "", "*Authorized security testing only. See the Penthera README for ethical use guidelines.*", "");
+}
+
+function timelineSection(L, t, { heading = "## Fix timeline" } = {}) {
+  if (!t) return;
+  L.push(heading, "");
+  L.push(`Source: ${t.source}. ${t.verified} verified · ${t.failed} failed · ${t.open} open · median time to fix ${t.medianTimeToFix}.`, "");
+  L.push("| Finding | Found | Fixed | Verified | Time to fix |");
+  L.push("|---------|-------|-------|----------|-------------|");
+  for (const e of t.entries) {
+    const name = e.title ? `${md(e.title)} (${code(e.fid)})` : code(e.fid);
+    const fixed = e.fixed ? `${md(e.fixed)}${e.recipe ? ` (${code(e.recipe)})` : ""}` : "-";
+    const verified = e.verified ? md(e.verified) : e.failed ? `**failed** ${md(e.failed)}` : "-";
+    L.push(`| ${name} | ${md(e.found || "-")} | ${fixed} | ${verified} | ${e.timeToFix} |`);
+  }
+  L.push("");
+}
+
+function inconclusiveSection(L, m) {
+  if (!m.inconclusive.length) return;
+  L.push("## Inconclusive probes", "");
+  L.push(`${plural(m.summary.inconclusive, "probe")} could not complete. Their silence is not a clean result.`, "");
+  L.push("| Probe | URL | Error | Count |");
+  L.push("|-------|-----|-------|-------|");
+  for (const e of m.inconclusive) L.push(`| ${md(e.probe)} | ${code(e.url)} | ${md(e.message)} | ${e.count} |`);
+  L.push("");
+}
+
+export function formatDeveloperReport(m) {
+  const L = [];
+  header(L, "Security findings for developers", m);
+  const s = m.summary;
+  L.push(`${plural(s.total, "finding")}: ${s.critical} critical · ${s.high} high · ${s.medium} medium · ${s.low} low · ${s.info} info.`);
+  if (s.suppressed) L.push(`${s.suppressed} suppressed (listed at the end).`);
+  L.push("");
+  if (m.findings.some((f) => f.recipe && !f.diff)) {
+    L.push(`Findings with a recipe can be fixed locally: ${code("penthera fix --plan")} shows the diff, ${code("penthera fix --apply <id>")} applies it.`, "");
+  }
+  for (const f of m.findings) {
+    L.push(`### ${f.n}. [${SEV_TAG[f.severity] || "INFO"}] ${md(f.title)}`, "");
+    if (f.location) L.push(`- **Where:** ${f.url ? md(f.location) : code(f.location)}`);
+    L.push(`- **Confidence:** ${f.confidence}${f.source ? ` (${md(f.source)})` : ""}${f.fid ? ` · id ${code(f.fid)}` : ""}`);
+    if (f.recipe) L.push(`- **Fix recipe:** ${code(f.recipe)}`);
+    if (f.fixText) L.push(`- **How to fix:** ${prose(f.fixText)}`);
+    if (f.sources.length) L.push(`- **Sources:** ${sources(f.sources)}`);
+    if (f.description) L.push("", md(f.description));
+    if (f.diff) {
+      const fence = "`".repeat(Math.max(3, ...[...String(f.diff).matchAll(/`+/g)].map((x) => x[0].length + 1)));
+      L.push("", `${fence}diff`, String(f.diff).replace(/\n$/, ""), fence);
+    }
+    L.push("");
+  }
+  inconclusiveSection(L, m);
+  timelineSection(L, m.timeline);
+  if (m.suppressed.length) {
+    L.push("## Suppressed", "");
+    for (const x of m.suppressed) L.push(`- ${md(x.title)} (${code(x.fid)}): ${md(x.reason)} (${md(x.actor)}, ${x.by})`);
+    L.push("");
+  }
+  footer(L);
+  return L.join("\n");
+}
+
+export function formatOwnerReport(m) {
+  const L = [];
+  header(L, "Security summary", m);
+  const s = m.summary;
+  L.push("## In short", "");
+  if (s.total === 0) {
+    L.push(`Penthera checked ${md(m.target)} and found no problems in the areas it tested.`);
+  } else {
+    const parts = [];
+    if (s.serious) parts.push(`**${plural(s.serious, "serious problem")}** to fix this week`);
+    if (s.medium) parts.push(`${s.medium} moderate`);
+    if (s.low) parts.push(`${s.low} minor`);
+    if (s.info) parts.push(`${plural(s.info, "note")}`);
+    L.push(`Penthera checked ${md(m.target)} and found ${parts.join(", ")}.`);
+    L.push(s.serious ? "The serious ones are things an attacker could use today." : "Nothing here needs an emergency response.");
+  }
+  if (s.inconclusive) L.push(`${plural(s.inconclusive, "check")} could not finish, so those areas are untested, not clean.`);
+  if (s.suppressed) L.push(`${plural(s.suppressed, "known issue")} ${s.suppressed === 1 ? "was" : "were"} set aside on purpose by someone on the team (the auditor report lists who and why).`);
+  L.push("");
+
+  if (m.topActions.length) {
+    L.push("## What to do first", "");
+    m.topActions.forEach((a, i) => {
+      L.push(`${i + 1}. **${prose(a.action)}** (${a.effort}${a.ownerAction ? ", needs you" : ", a developer can do this"}). ${prose(a.why)}`);
+    });
+    L.push("");
+  }
+
+  if (m.ownerActions.length) {
+    L.push("## Things only you can do", "");
+    L.push("A tool or a developer cannot do these for you: they need account access, a provider dashboard or a DNS change.", "");
+    for (const a of m.ownerActions) L.push(`- **${prose(a.action)}**${a.fix ? `: ${prose(a.fix)}` : ""}`);
+    L.push("");
+  }
+
+  if (m.trend.length > 1) {
+    const first = m.trend[0];
+    const last = m.trend[m.trend.length - 1];
+    const dir = last.serious < first.serious ? "down" : last.serious > first.serious ? "up" : "flat";
+    L.push("## Trend", "");
+    L.push(`Serious problems went from ${first.serious} to ${last.serious} over the last ${m.trend.length} scans (${dir}).`, "");
+    L.push("| Scan | Serious | Moderate | Minor | Total |");
+    L.push("|------|---------|----------|-------|-------|");
+    for (const t of m.trend) L.push(`| ${t.date} | ${t.serious} | ${t.medium} | ${t.low} | ${t.total} |`);
+    L.push("");
+  }
+
+  if (m.timeline) {
+    const t = m.timeline;
+    L.push("## Fixes", "");
+    L.push(`${t.verified} ${t.verified === 1 ? "fix" : "fixes"} verified by a re-scan, ${t.failed} failed, ${t.open} still open. Typical time to fix: ${t.medianTimeToFix}.`, "");
+  }
+  footer(L);
+  return L.join("\n");
+}
+
+export function formatAuditorReport(m) {
+  const L = [];
+  header(L, "Security evidence report", m);
+  L.push("> Automated technical evidence. It is not an audit opinion, a compliance determination or a certification.", "");
+
+  L.push("## 1. Scope and method", "");
+  L.push("| | |", "|---|---|");
+  L.push(`| **Target** | ${code(m.target)} |`);
+  L.push(`| **Scan time** | ${when(m.timestamp)} |`);
+  if (m.duration) L.push(`| **Duration** | ${m.duration} |`);
+  L.push(`| **Modes** | ${md(m.modes || "-")} |`);
+  if (m.profile) L.push(`| **Profile** | ${md(m.profile)} |`);
+  L.push(`| **Network** | ${m.egress ? md(m.egress.mode) : "not recorded"} |`);
+  L.push(`| **Tool** | Penthera v${m.tool.version} |`);
+  L.push("");
+  if (m.probes.length) L.push(`Probes that ran: ${m.probes.map(code).join(", ")}.`, "");
+  L.push(`Method, threat model and limits: [docs/METHODOLOGY.md](${METHODOLOGY_URL}). A probe that is not listed did not run, and an area it covers is untested.`, "");
+
+  L.push("## 2. Confidence and provenance", "");
+  L.push("Every finding carries a confidence label that says how sure the scanner is that the issue is real, separate from its severity.", "");
+  L.push("| Label | Meaning | This scan |");
+  L.push("|-------|---------|-----------|");
+  for (const c of CONFIDENCE_LABELS) {
+    L.push(`| ${code(c.label)} | ${c.meaning} | ${m.findings.filter((f) => f.confidence === c.label).length} |`);
+  }
+  L.push("");
+  if (m.findings.length) {
+    L.push("| # | Id | Finding | Severity | Confidence | Source / method | Collected | Location |");
+    L.push("|---|----|---------|----------|------------|-----------------|-----------|----------|");
+    for (const f of m.findings) {
+      L.push(`| ${f.n} | ${f.fid ? code(f.fid) : "-"} | ${md(f.title)} | ${f.severity} | ${f.confidence} | ${md(f.source || "-")} / ${md(f.method || "-")} | ${when(f.collectedAt)} | ${f.location ? code(f.location) : "-"} |`);
+    }
+  } else {
+    L.push("No findings in the tested areas.");
+  }
+  L.push("");
+
+  L.push("## 3. Network egress", "");
+  if (m.egress) {
+    L.push(`- **Mode:** ${md(m.egress.mode)}`);
+    L.push(`- **User-Agent:** ${code(m.egress.userAgent)}`);
+    L.push(`- **Third-party hosts contacted:** ${m.egress.thirdPartyHosts.length ? m.egress.thirdPartyHosts.map((h) => `${code(h.host)} (${h.requests})`).join(", ") : "none"}`);
+    if (m.egress.blocked.length) L.push(`- **Blocked by --offline:** ${m.egress.blocked.map((h) => `${code(h.host)} (${h.requests})`).join(", ")}`);
+  } else {
+    L.push("No egress record (a repo-only or machine scan makes no network requests to the target).");
+  }
+  L.push("");
+  inconclusiveSection(L, m);
+
+  L.push("## 4. Suppressions", "");
+  if (m.suppressed.length) {
+    L.push("These findings were hidden from the results by a person's decision. Each needs a reason; review them.", "");
+    L.push("| Id | Finding | Severity | Who | Why | Recorded in | Expires |");
+    L.push("|----|---------|----------|-----|-----|-------------|---------|");
+    for (const x of m.suppressed) {
+      L.push(`| ${code(x.fid)} | ${md(x.title)} | ${x.severity} | ${md(x.actor)} | ${md(x.reason)} | ${x.by} | ${x.expires ? md(x.expires) : "never"} |`);
+    }
+  } else {
+    L.push("None. No finding was hidden from this report.");
+  }
+  L.push("");
+
+  timelineSection(L, m.timeline, { heading: "## 5. Fix timeline" });
+
+  L.push(`## ${m.timeline ? 6 : 5}. NIS2 Article 21(2) mapping`, "");
+  L.push("Technical evidence toward each measure, based on the probes that ran. Organisational measures need human process.", "");
+  L.push("| Art. 21(2) | Measure | This scan | Findings |");
+  L.push("|-----------|---------|-----------|----------|");
+  for (const x of m.nis2) L.push(`| (${x.id}) | ${md(x.title)} | ${NIS2_STATUS[x.status] || x.status} | ${x.findings || "-"} |`);
+  L.push("");
+
+  L.push(`## ${m.timeline ? 7 : 6}. OWASP mapping`, "");
+  if (m.owasp.length) {
+    L.push("| OWASP category | Findings | Ids |");
+    L.push("|----------------|----------|-----|");
+    for (const o of m.owasp) L.push(`| ${md(o.id)} | ${o.count} | ${md(o.findings)} |`);
+  } else {
+    L.push("No finding maps to an OWASP Top 10 category.");
+  }
+  L.push("");
+  const wstg = [...new Set(m.findings.flatMap((f) => f.wstg))].sort();
+  if (wstg.length) L.push(`OWASP WSTG test areas with findings: ${wstg.map(code).join(", ")}.`, "");
+
+  L.push("## Verifying this report", "");
+  L.push(`If this report came in an evidence bundle, check that nothing in it changed since it was produced: ${code("penthera evidence verify <dir> --allowed-signers <file>")}. See [docs/evidence.md](${EVIDENCE_URL}).`, "");
+  footer(L);
+  return L.join("\n");
+}
+
+const FORMATTERS = { developer: formatDeveloperReport, owner: formatOwnerReport, auditor: formatAuditorReport };
+
+/** Render the report for one audience. Throws on an unknown audience. */
+export function formatAudienceReport(result, audience, { version } = {}) {
+  const fmt = FORMATTERS[audience];
+  if (!fmt) throw new Error(`Unknown --audience "${audience}". Use one of: ${AUDIENCES.join(", ")}.`);
+  return fmt(buildReportModel(result, { version }));
+}