penthera 1.1.0

package/src/cli/ansi.js

@@ -0,0 +1,70 @@
+/**
+ * ANSI helpers + brand styling, respects NO_COLOR and terminal width.
+ */
+const off = !!process.env.NO_COLOR;
+
+export const bold = (s) => off ? s : `\x1b[1m${s}\x1b[0m`;
+export const dim = (s) => off ? s : `\x1b[2m${s}\x1b[0m`;
+export const cyan = (s) => off ? s : `\x1b[36m${s}\x1b[0m`;
+export const green = (s) => off ? s : `\x1b[32m${s}\x1b[0m`;
+export const yellow = (s) => off ? s : `\x1b[33m${s}\x1b[0m`;
+export const red = (s) => off ? s : `\x1b[31m${s}\x1b[0m`;
+
+// ── Brand ──────────────────────────────────────────────────────────────────
+// Penthera blue: #0000ed (rgb 0,0,237). Truecolor + bold, with graceful
+// degradation under NO_COLOR.
+const BRAND = "\x1b[1m\x1b[38;2;0;0;237m";
+const RESET = "\x1b[0m";
+export const brand = (s) => off ? s : `${BRAND}${s}${RESET}`;
+
+// "PENTHERA", ANSI Shadow block letters (~67 cols wide).
+const LOGO_BIG = [
+  "██████╗ ███████╗███╗   ██╗████████╗██╗  ██╗███████╗██████╗  █████╗ ",
+  "██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██║  ██║██╔════╝██╔══██╗██╔══██╗",
+  "██████╔╝█████╗  ██╔██╗ ██║   ██║   ███████║█████╗  ██████╔╝███████║",
+  "██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══██║██╔══╝  ██╔══██╗██╔══██║",
+  "██║     ███████╗██║ ╚████║   ██║   ██║  ██║███████╗██║  ██║██║  ██║",
+  "╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝",
+];
+
+// Compact wordmark for narrow terminals / nested output.
+const LOGO_SMALL = "▌▌ P E N T H E R A";
+
+/**
+ * Render the Penthera logo. Falls back to a compact wordmark when the
+ * terminal is narrower than the block art.
+ */
+export function logo(tagline = "security check for your vibecoded app") {
+  const cols = process.stdout.columns || 80;
+  const lines = [""];
+
+  if (cols >= 72) {
+    for (const row of LOGO_BIG) lines.push("  " + brand(row));
+  } else {
+    lines.push("  " + brand(LOGO_SMALL));
+  }
+
+  lines.push("");
+  if (tagline) lines.push("  " + dim(tagline));
+  lines.push("");
+  return lines.join("\n");
+}
+
+// Back-compat alias, older callers import `banner`.
+export function banner() {
+  return logo();
+}
+
+export function box(title, lines) {
+  const out = [`  ${bold(title)}`, ""];
+  for (const line of lines) out.push(`  ${line}`);
+  out.push("");
+  return out.join("\n");
+}
+
+/** Dim horizontal rule sized to the terminal (capped). */
+export function hr(width) {
+  const cols = process.stdout.columns || 60;
+  const len = Math.min(width || 58, Math.max(20, cols - 4));
+  return dim("─".repeat(len));
+}

package/src/cli/baseline.js

@@ -0,0 +1,37 @@
+/**
+ * Compare scan findings against a previous JSON report.
+ */
+import { readFileSync } from "node:fs";
+
+function findingKey(f) {
+  return `${f.severity}::${f.title}::${f.url || ""}::${f.source || ""}`;
+}
+
+export function compareWithBaseline(currentFindings, baselinePath) {
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(baselinePath, "utf-8"));
+  } catch (e) {
+    throw new Error(`Cannot read baseline report: ${baselinePath} (${e.message})`);
+  }
+
+  const prev = baseline.findings || [];
+  const prevKeys = new Set(prev.map(findingKey));
+  const currKeys = new Set((currentFindings || []).map(findingKey));
+
+  const newFindings = (currentFindings || []).filter((f) => !prevKeys.has(findingKey(f)));
+  const resolvedFindings = prev.filter((f) => !currKeys.has(findingKey(f)));
+  const unchangedFindings = (currentFindings || []).filter((f) => prevKeys.has(findingKey(f)));
+
+  return {
+    newFindings,
+    resolvedFindings,
+    unchangedFindings,
+    stats: {
+      path: baselinePath,
+      newCount: newFindings.length,
+      resolvedCount: resolvedFindings.length,
+      unchangedCount: unchangedFindings.length,
+    },
+  };
+}

package/src/cli/merge-results.js

@@ -0,0 +1,71 @@
+/**
+ * Merge multi-target scan results into one report.
+ */
+import { enrichFindingsWithWstg } from "../../lib/owasp-wstg.js";
+import { stampProvenance } from "../../lib/provenance.js";
+
+export function mergeResults(results) {
+  let merged;
+
+  if (results.length === 1) {
+    merged = { ...results[0] };
+  } else {
+    merged = {
+      target: results.map((r) => r.target).join(" + "),
+      modes: results.map((r) => r.mode),
+      local: results.some((r) => r.local),
+      timestamp: new Date().toISOString(),
+      duration: results.reduce((sum, r) => sum + (r.duration || 0), 0),
+      reachable: results.some((r) => r.reachable),
+      tls: results.find((r) => r.tls)?.tls || null,
+      fingerprint: results.find((r) => r.fingerprint)?.fingerprint || null,
+      recon: results.find((r) => r.recon)?.recon || null,
+      openapi: results.find((r) => r.openapi)?.openapi || null,
+      endpoints: mergeEndpoints(results),
+      cookies: results.find((r) => r.cookies)?.cookies || null,
+      jsLibraries: results.find((r) => r.jsLibraries)?.jsLibraries || null,
+      paramDiscovery: results.find((r) => r.paramDiscovery)?.paramDiscovery || null,
+      attackSurface: results.find((r) => r.attackSurface?.length)?.attackSurface || null,
+      boundaries: results.find((r) => r.boundaries && Object.keys(r.boundaries).length)?.boundaries || null,
+      apiRoot: results.find((r) => r.apiRoot)?.apiRoot || null,
+      machine: results.find((r) => r.machine)?.machine || null,
+      executedProbes: results.flatMap((r) => r.executedProbes || []),
+      findings: dedupeFindings(results.flatMap((r) => r.findings || [])),
+    };
+  }
+
+  merged.findings = enrichFindingsWithWstg(merged.findings);
+  // Provenance + honest-confidence on every finding (source, method,
+  // collected_at, confidence). Additive: consumers that don't use it ignore it.
+  merged.findings = stampProvenance(merged.findings, merged.timestamp);
+  return merged;
+}
+
+function mergeEndpoints(results) {
+  const all = results.flatMap((r) => {
+    if (r.endpoints?.list) return r.endpoints.list;
+    return [];
+  });
+
+  if (all.length === 0) {
+    const first = results.find((r) => r.endpoints);
+    return first?.endpoints || { total: 0, discovered: 0, byStatus: {} };
+  }
+
+  const byStatus = {};
+  for (const ep of all) {
+    byStatus[ep.status] = (byStatus[ep.status] || 0) + 1;
+  }
+
+  return { total: all.length, discovered: all.length, byStatus, list: all };
+}
+
+export function dedupeFindings(findings) {
+  const seen = new Set();
+  return findings.filter((f) => {
+    const key = `${f.severity}::${f.title}::${f.url || ""}::${f.source || ""}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/cli/onboarding.js

@@ -0,0 +1,216 @@
+/**
+ * PostHog-style interactive onboarding, simple defaults, advanced hidden.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { initPrompt, closePrompt, ask, choose, confirm, normalizeUrlInput } from "./prompt.js";
+import { banner, box, bold, dim, cyan, green, yellow, hr, brand } from "./ansi.js";
+import { executeScan, writeScanReports } from "./run-scan.js";
+import { isPrivateHost } from "../utils/url.js";
+import { printError } from "../reporter.js";
+
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8"));
+
+function countFindings(findings) {
+  const c = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings || []) c[f.severity] = (c[f.severity] || 0) + 1;
+  return c;
+}
+
+function summarize(findings) {
+  const c = countFindings(findings);
+  const parts = [];
+  if (c.critical) parts.push(`${c.critical} critical`);
+  if (c.high) parts.push(`${c.high} high`);
+  if (c.medium) parts.push(`${c.medium} medium`);
+  if (c.low) parts.push(`${c.low} low`);
+  if (parts.length === 0) return green("No issues found, looking good!");
+  return yellow(parts.join(" · "));
+}
+
+const SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+function topFindings(findings, limit = 3) {
+  return [...(findings || [])]
+    .filter((f) => f.severity !== "info")
+    .sort((a, b) => (SEV_RANK[a.severity] ?? 5) - (SEV_RANK[b.severity] ?? 5))
+    .slice(0, limit);
+}
+
+function printTopFixes(findings) {
+  const top = topFindings(findings);
+  if (top.length === 0) return;
+  process.stdout.write(`\n  ${bold("Start here")}\n`);
+  top.forEach((f, i) => {
+    process.stdout.write(`  ${i + 1}. ${f.title} ${dim(`(${f.severity})`)}\n`);
+  });
+}
+
+async function runSimpleScan(config) {
+  process.stdout.write(`\n  ${dim("Scanning")}${dim("...")}\n\n`);
+  const result = await executeScan({ ...config, version: pkg.version });
+  const paths = writeScanReports(
+    { merged: result.merged },
+    result.paths,
+    result.mdOpts,
+    { verbose: false, quiet: true, writeSarif: true },
+  );
+  return { ...result, paths };
+}
+
+function printScanFailure(url, err) {
+  if (/unreachable/i.test(err.message)) {
+    printError(`Couldn't reach ${url}. Is your app running?`);
+    process.stdout.write(
+      `\n  ${dim("Tip:")} start your dev server, then run ${bold("penthera")} again.\n\n`,
+    );
+    return;
+  }
+  printError(err.message);
+}
+
+export async function runOnboarding() {
+  await initPrompt();
+
+  process.stdout.write(banner());
+  process.stdout.write(box("Welcome", [
+    "Shipped something you vibecoded? Pressure-test it before attackers do.",
+    "Penthera checks your live app + repo for the gaps that get apps owned, ",
+    "exposed APIs, missing headers, weak auth, leaked secrets.",
+    "",
+    dim("Only scan apps you own or have permission to test."),
+  ]));
+  process.stdout.write(
+    `  ${dim("Expert?")} ${dim("skip the wizard with")} ${brand("penthera <url> --profile deep")} ${dim("· see")} ${brand("penthera --help")}\n\n`,
+  );
+
+  // ── Step 1: URL (required) ─────────────────────────────────────────────
+  process.stdout.write(`  ${bold("Step 1")}  ${dim("Where is your app running?")}\n\n`);
+  const urlRaw = await ask(`  ${cyan(">")} URL ${dim("(e.g. https://myapp.com or localhost:3000)")}: `);
+  const url = normalizeUrlInput(urlRaw);
+
+  if (!url) {
+    printError("A URL is required. Example: localhost:3000 or https://staging.myapp.com");
+    closePrompt();
+    process.exit(2);
+  }
+
+  // ── Step 2: Source code (optional, default yes if package.json) ────────
+  const hasProject = existsSync(resolve("package.json"));
+  let repo = null;
+
+  if (hasProject) {
+    process.stdout.write(`\n  ${bold("Step 2")}  ${dim("Scan your source code too?")}\n`);
+    process.stdout.write(`  ${dim("Finds hardcoded secrets and risky API routes in this folder.")}\n\n`);
+    const scanRepo = await confirm(`  ${cyan(">")} Scan ./`, true);
+    if (scanRepo) repo = ".";
+  } else {
+    process.stdout.write(`\n  ${dim("Step 2 skipped, no package.json in current folder.")}\n`);
+  }
+
+  // ── Permission check for remote targets ────────────────────────────────
+  if (!isPrivateHost(url)) {
+    process.stdout.write(`\n  ${yellow("Note")}  ${dim("We'll send safe checks to")} ${cyan(url)}\n`);
+    process.stdout.write(`  ${dim("No attack payloads in the default scan.")}\n\n`);
+    // Default to "no": for a security tool the safe default is to not scan a
+    // remote host unless the user explicitly affirms authorization.
+    const ok = await confirm(`  ${cyan(">")} You have permission to scan this URL`, false);
+    if (!ok) {
+      process.stdout.write(`\n  ${dim("Aborted.")}\n\n`);
+      closePrompt();
+      process.exit(0);
+    }
+  }
+
+  closePrompt();
+
+  // ── Run default scan (standard profile) ────────────────────────────────
+  let scanResult;
+  try {
+    scanResult = await runSimpleScan({ url, repo, profile: "standard" });
+  } catch (e) {
+    printScanFailure(url, e);
+    process.exit(2);
+  }
+
+  const { merged, paths, hasSevere } = scanResult;
+
+  process.stdout.write(`\n  ${hr()}\n`);
+  process.stdout.write(`  ${green("Done!")}  ${summarize(merged.findings)}\n`);
+  printTopFixes(merged.findings);
+  process.stdout.write(`\n  ${bold("Read your report")}\n`);
+  process.stdout.write(`  ${cyan(paths.markdown)}  ${dim("← start here (plain English)")}\n`);
+  process.stdout.write(`  ${dim(paths.json)}  ${dim("(machine-readable)")}\n`);
+  process.stdout.write(`\n  ${hr()}\n`);
+
+  // ── Post-scan menu (re-open prompt) ────────────────────────────────────
+  await initPrompt();
+
+  const next = await choose("What next?", [
+    { id: "done", label: "Looks good, I'm done" },
+    { id: "deeper", label: "Run a deeper scan (sends test payloads, needs permission)" },
+    { id: "custom", label: "Custom setup (profiles, auth tokens, advanced flags)" },
+  ]);
+
+  if (next === "done") {
+    closePrompt();
+    process.stdout.write(`\n  ${dim("Tip:")} re-run anytime with ${bold("penthera")} or ${bold("penthera <url>")}\n\n`);
+    process.exit(hasSevere ? 1 : 0);
+  }
+
+  if (next === "deeper") {
+    process.stdout.write(`\n  ${yellow("Deep scan")} sends SQLi, XSS, and fuzz payloads.\n`);
+    const ok = await confirm(`  ${cyan(">")} I have permission to run destructive tests`, false);
+    closePrompt();
+    if (!ok) {
+      process.stdout.write(`\n  ${dim("Skipped deep scan.")}\n\n`);
+      process.exit(hasSevere ? 1 : 0);
+    }
+
+    try {
+      const deep = await runSimpleScan({ url, repo, profile: "deep" });
+      process.stdout.write(`\n  ${green("Deep scan complete.")}  ${summarize(deep.merged.findings)}\n`);
+      process.stdout.write(`  ${cyan(deep.paths.markdown)}\n\n`);
+      process.exit(deep.hasSevere ? 1 : 0);
+    } catch (e) {
+      printScanFailure(url, e);
+      process.exit(2);
+    }
+  }
+
+  // ── Custom setup (hidden power-user path) ──────────────────────────────
+  process.stdout.write(box("Custom setup", [
+    "Power-user options. Most people never need this.",
+    dim("Press enter to keep defaults shown in [brackets]."),
+  ]));
+
+  const profileAns = await ask(`  Profile ${dim("[standard]")} quick | standard | deep: `);
+  const profile = ["quick", "standard", "deep"].includes(profileAns) ? profileAns : "standard";
+
+  const repoAns = await ask(`  Repo path ${dim("[.]")}: `);
+  const customRepo = repoAns || repo || null;
+
+  const bearer = await ask(`  Bearer token ${dim("(optional, for logged-in routes)")}: `);
+  const cookie = await ask(`  Session cookie ${dim("(optional)")}: `);
+
+  const customUrl = await ask(`  URL ${dim(`[${url}]`)}: `);
+  closePrompt();
+
+  try {
+    const custom = await runSimpleScan({
+      url: customUrl || url,
+      repo: customRepo,
+      profile,
+      authBearer: bearer || null,
+      authCookie: cookie || null,
+    });
+    process.stdout.write(`\n  ${green("Custom scan complete.")}  ${summarize(custom.merged.findings)}\n`);
+    process.stdout.write(`  ${cyan(custom.paths.markdown)}\n\n`);
+    process.stdout.write(`  ${dim("Expert mode:")} penthera --help\n\n`);
+    process.exit(custom.hasSevere ? 1 : 0);
+  } catch (e) {
+    printScanFailure(customUrl || url, e);
+    process.exit(2);
+  }
+}

package/src/cli/profiles.js

@@ -0,0 +1,53 @@
+/**
+ * Scan profile presets.
+ */
+
+export const PROFILES = {
+  quick: {
+    label: "Quick",
+    description: "Headers, OpenAPI, auth smoke tests, skips Retire.js and param discovery",
+    recon: false,
+    deep: false,
+    fuzz: false,
+    skipRetireJs: true,
+    skipParamDiscovery: true,
+  },
+  standard: {
+    label: "Standard",
+    description: "Full non-destructive scan (default)",
+    recon: false,
+    deep: false,
+    fuzz: false,
+    skipRetireJs: false,
+    skipParamDiscovery: false,
+  },
+  deep: {
+    label: "Deep",
+    description: "Maximum coverage: recon + injection probes + API fuzzing",
+    recon: true,
+    deep: true,
+    fuzz: true,
+    skipRetireJs: false,
+    skipParamDiscovery: false,
+  },
+};
+
+export function resolveScanOptions(opts) {
+  const profileName = opts.profile || "standard";
+  const profile = PROFILES[profileName];
+
+  if (!profile) {
+    throw new Error(`Unknown profile "${profileName}". Use: quick, standard, or deep.`);
+  }
+
+  const all = opts.all === true;
+
+  return {
+    profile: profileName,
+    recon: all || opts.recon === true || profile.recon,
+    deep: all || opts.deep === true || profile.deep,
+    fuzz: all || opts.fuzz === true || profile.fuzz,
+    skipRetireJs: profile.skipRetireJs,
+    skipParamDiscovery: profile.skipParamDiscovery,
+  };
+}

package/src/cli/prompt.js

@@ -0,0 +1,64 @@
+/**
+ * Shared terminal prompt helpers (TTY + piped stdin).
+ */
+import { createInterface } from "node:readline";
+
+let _pipedLines = null;
+let _rl = null;
+
+export async function initPrompt() {
+  if (process.stdin.isTTY) {
+    _rl = createInterface({ input: process.stdin, output: process.stdout });
+  } else {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    _pipedLines = Buffer.concat(chunks).toString().split("\n").map((l) => l.trim());
+  }
+}
+
+export function closePrompt() {
+  if (_rl) _rl.close();
+}
+
+export function ask(question) {
+  if (_pipedLines) {
+    process.stdout.write(question);
+    const answer = _pipedLines.shift() || "";
+    process.stdout.write(answer + "\n");
+    return Promise.resolve(answer);
+  }
+  return new Promise((resolve) => {
+    _rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+/** Normalize user URL input (adds http/https). */
+export function normalizeUrlInput(raw, forceLocal = false) {
+  if (!raw) return null;
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
+    const looksLocal = forceLocal ||
+      /^(localhost|127\.|0\.0\.0|192\.168\.|10\.|172\.(1[6-9]|2\d|3[01]))/.test(trimmed);
+    return looksLocal ? `http://${trimmed}` : `https://${trimmed}`;
+  }
+  return trimmed;
+}
+
+/** Single-choice menu. Returns selected option id. */
+export async function choose(question, options) {
+  process.stdout.write(`\n${question}\n`);
+  options.forEach((opt, i) => {
+    process.stdout.write(`  ${i + 1}. ${opt.label}\n`);
+  });
+  const answer = await ask(`\n  Choice [1-${options.length}]: `);
+  const idx = parseInt(answer, 10) - 1;
+  if (idx >= 0 && idx < options.length) return options[idx].id;
+  return options[0].id;
+}
+
+export async function confirm(question, defaultYes = true) {
+  const hint = defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = await ask(`${question} ${hint}: `);
+  if (!answer) return defaultYes;
+  return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+}

package/src/cli/run-scan.js

@@ -0,0 +1,152 @@
+/**
+ * Shared scan execution, used by CLI and interactive onboarding.
+ */
+import { resolve, join } from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+import { scanUrl } from "../scan-url.js";
+import { scanRepo } from "../scan-repo.js";
+import { mergeResults } from "./merge-results.js";
+import { resolveScanOptions } from "./profiles.js";
+import { compareWithBaseline } from "./baseline.js";
+import { normalizeBaseUrl, urlToFilename } from "../utils/url.js";
+import {
+  printReport,
+  printFindings,
+  writeJsonReport,
+  writeSarifReport,
+  createProgress,
+} from "../reporter.js";
+import { writeMarkdownReport, markdownPathFromJson } from "../report/markdown.js";
+import { buildActionPlan } from "../../lib/remediation/index.js";
+
+export async function executeScan(config) {
+  const {
+    url = null,
+    repo = null,
+    machine = false,
+    profile = "standard",
+    recon = false,
+    deep = false,
+    fuzz = false,
+    output = null,
+    markdown = null,
+    sarif = null,
+    baseline = null,
+    authCookie = null,
+    authBearer = null,
+    apiRoot = null,
+    quiet = false,
+    verbose = false,
+    json = false,
+    version = "0.2.0",
+    onPhase = null,
+  } = config;
+
+  const profileOpts = resolveScanOptions({ profile, recon, deep, fuzz, all: false });
+
+  const scanOpts = {
+    timeout: config.timeout || 10_000,
+    concurrency: config.concurrency || 15,
+    fuzz: profileOpts.fuzz,
+    recon: profileOpts.recon,
+    deep: profileOpts.deep,
+    profile: profileOpts.profile,
+    skipRetireJs: profileOpts.skipRetireJs,
+    skipParamDiscovery: profileOpts.skipParamDiscovery,
+    nucleiPath: config.nucleiPath || null,
+    templatePaths: config.templatePaths || [],
+    adaptive: config.adaptive || false,
+    verbose,
+    authCookie,
+    authBearer,
+    onPhase: onPhase || createProgress(quiet || json),
+  };
+
+  const results = [];
+
+  if (url) {
+    const urlResult = await scanUrl(normalizeBaseUrl(url), scanOpts);
+    results.push(urlResult);
+    if (!urlResult.reachable && !repo) {
+      throw new Error(`Target unreachable: ${url}`);
+    }
+  }
+
+  if (repo) {
+    const repoResult = await scanRepo(resolve(repo), {
+      ...scanOpts,
+      apiRoot: apiRoot ? resolve(apiRoot) : null,
+    });
+    results.push(repoResult);
+  }
+
+  if (machine) {
+    const { auditMachine } = await import("../../lib/machine.js");
+    const machineResult = await auditMachine({ onPhase: scanOpts.onPhase });
+    results.push({
+      target: "this machine",
+      mode: "machine",
+      timestamp: new Date().toISOString(),
+      duration: 0,
+      machine: machineResult,
+      findings: machineResult.findings,
+    });
+  }
+
+  const merged = mergeResults(results);
+  merged.profile = profileOpts.profile;
+  // Parity with the main CLI path so onboarding reports carry the action plan.
+  merged.actionPlan = buildActionPlan(merged.findings);
+
+  let baselineStats = null;
+  if (baseline) {
+    const comparison = compareWithBaseline(merged.findings, resolve(baseline));
+    baselineStats = comparison.stats;
+    if (quiet) merged.findings = comparison.newFindings;
+  }
+
+  const mdOpts = { version, baseline: baselineStats };
+
+  // Default report paths
+  let jsonPath = output;
+  let mdPath = markdown;
+  let sarifPath = sarif;
+
+  if (!jsonPath && !json) {
+    const reportsDir = resolve("reports");
+    if (!existsSync(reportsDir)) mkdirSync(reportsDir, { recursive: true });
+    const ts = new Date().toISOString().slice(0, 19).replace(/[T:]/g, "-");
+    const base = url ? urlToFilename(normalizeBaseUrl(url)) : repo ? "repo" : "scan";
+    jsonPath = join(reportsDir, `${base}_${ts}.json`);
+    mdPath = mdPath || markdownPathFromJson(jsonPath);
+    sarifPath = sarifPath || join(reportsDir, `${base}_${ts}.sarif`);
+  } else if (jsonPath && !mdPath) {
+    mdPath = markdownPathFromJson(jsonPath);
+  }
+
+  return {
+    merged,
+    profileOpts,
+    paths: { json: jsonPath, markdown: mdPath, sarif: sarifPath },
+    mdOpts,
+    hasSevere: merged.findings.some((f) => f.severity === "critical" || f.severity === "high"),
+  };
+}
+
+export function writeScanReports(result, paths, mdOpts, opts = {}) {
+  const { quiet = false, json = false, writeSarif = true } = opts;
+
+  if (json) {
+    console.log(JSON.stringify(result.merged, null, 2));
+  } else if (!quiet) {
+    printReport(result.merged, { verbose: opts.verbose });
+  } else {
+    printFindings(result.merged.findings);
+  }
+
+  if (paths.json) writeJsonReport(result.merged, paths.json);
+  if (paths.markdown) writeMarkdownReport(result.merged, paths.markdown, mdOpts);
+  if (writeSarif && paths.sarif) writeSarifReport(result.merged, paths.sarif);
+
+  return paths;
+}