penthera 1.2.0 → 1.4.0

package/src/cli/install.js

@@ -0,0 +1,225 @@
+/**
+ * `penthera install [pkg...]`: the install firewall CLI (lib/install/).
+ *
+ * Shows what an install would change (new packages, capabilities gained, new
+ * install scripts and their commands), applies penthera.policy.json, and only
+ * then runs the real `npm install`. Exit codes: 0 installed (or a clean
+ * --dry-run), 1 blocked or aborted (project untouched), 2 error.
+ */
+import { parseArgs } from "node:util";
+import { resolve, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { planInstall, applyInstall, scriptChanges, npmInfo } from "../../lib/install/index.js";
+import { loadPolicy, RULE_LABELS, POLICY_FILE } from "../../lib/install/policy.js";
+import { createProgress, printError } from "../reporter.js";
+import { initPrompt, ask, closePrompt } from "./prompt.js";
+import { bold, dim, green, red, yellow, cyan } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera install")} — install npm packages through a capability firewall
+
+  ${dim("Usage")}
+    $ penthera install <pkg> [<pkg>...]   Check, then install (asks when the policy says so)
+    $ penthera install                    Same, for what package.json already lists
+
+  ${dim("Options")}
+    -y, --yes              Never prompt: install only if nothing breaches the policy (CI)
+        --dry-run          Report only; never install
+        --policy <file>    Policy file (default: ./${POLICY_FILE}, else built-in defaults)
+        --dir <path>       Project folder (default: .)
+    -D, --save-dev         Save as devDependencies
+    -E, --save-exact       Save exact versions
+        --offline          npm resolves from its cache only (no registry traffic at all)
+        --json             Print the plan as JSON
+    -v, --verbose          Show more evidence per capability
+    -h, --help             Show this help
+
+  ${dim("How it works")}
+    npm resolves the new tree in a temporary copy with scripts disabled, new
+    tarballs go into npm's cache (integrity-verified, never unpacked or run),
+    and the \`penthera deps\` engine diffs capabilities against your lockfile.
+    Nothing in your project changes until you approve. Approved install scripts
+    run; otherwise the install uses --ignore-scripts.
+
+  ${dim("Policy")}  ${dim(`(${POLICY_FILE})`)}
+    { "allow": ["@acme/*", "esbuild"], "deny": ["token-harvest"],
+      "requireApproval": ["install-scripts", "ai-config-write", "ai-cli-invoke",
+                          "token-harvest", "obfuscated", "typosquat", "unscanned"] }
+    The requireApproval list above is the default.
+`;
+
+const label = (id) => RULE_LABELS[id] || id;
+const at = (i) => `${i.name}@${i.version}`;
+
+function printPlan(plan, { policyPath, verbose }) {
+  const L = [];
+  const { items, denied, needsApproval } = plan.verdict;
+  const added = items.filter((i) => i.change === "added");
+  const upgraded = items.filter((i) => i.change === "upgraded");
+  L.push("");
+  L.push(`  ${bold("Changes")}   ${added.length} added · ${upgraded.length} upgraded · ${plan.removed.length} removed`);
+  L.push("");
+  if (items.length === 0 && plan.removed.length === 0) L.push(`  ${green("✓")} Nothing changes: the lockfile already has this.`);
+  for (const i of [...upgraded, ...added]) {
+    const head = i.change === "upgraded"
+      ? `${yellow("▲")} ${bold(i.name)} ${i.from} → ${i.version}`
+      : `${cyan("+")} ${bold(i.name)} ${i.version} ${dim("(new)")}`;
+    const shown = i.flags.length ? i.flags : i.capabilities;
+    const note = shown.length
+      ? (i.change === "upgraded" ? red(`+ ${shown.map(label).join(", ")}`) : shown.map(label).join(", "))
+      : dim(i.change === "upgraded" ? (i.compared ? "no new capabilities" : "old version not readable") : "no notable capabilities");
+    L.push(`  ${head}  ${note}`);
+    if (i.typosquatOf) L.push(`      ${yellow(`looks like ${i.typosquatOf}`)}: check this is the package you meant`);
+    if (i.flags.includes("install-scripts")) {
+      for (const [hook, cmd] of Object.entries(i.installScripts || {})) {
+        const was = i.previousInstallScripts?.[hook];
+        L.push(`      ${red(hook)}: ${cmd}${was && was !== cmd ? dim(`  (was: ${was})`) : ""}`);
+      }
+    }
+    const ev = plan.evidence?.[at(i)] || {};
+    for (const id of i.flags.filter((f) => f !== "install-scripts")) {
+      for (const e of (ev[id] || []).slice(0, verbose ? 3 : 1)) L.push(`      ${dim(`${e.file}:${e.line}`)}  ${e.snippet}`);
+    }
+  }
+  for (const r of plan.removed) L.push(`  ${dim("−")} ${r.name} ${r.version} ${dim("(removed)")}`);
+
+  L.push("");
+  L.push(`  ${bold("Policy")}    ${policyPath ? relative(process.cwd(), policyPath) || policyPath : dim(`defaults (no ${POLICY_FILE})`)}`);
+  for (const i of denied) L.push(`  ${red("✗")} ${at(i)}  ${red("denied")}: ${i.deny.map(label).join(", ")}`);
+  for (const i of needsApproval) L.push(`  ${yellow("!")} ${at(i)}  needs approval: ${i.approval.map(label).join(", ")}`);
+  for (const i of items.filter((x) => x.allowedBy && x.flags.length)) L.push(`  ${green("✓")} ${at(i)}  allowed by "${i.allowedBy}"`);
+  if (plan.verdict.clean) L.push(`  ${green("✓")} Nothing breaches the policy.`);
+  L.push("");
+  process.stdout.write(L.join("\n") + "\n");
+}
+
+function planJson(plan, extra) {
+  return {
+    root: plan.root,
+    specs: plan.specs,
+    npm: { version: plan.npm.version, registry: plan.npm.registry },
+    clean: plan.verdict.clean,
+    changes: plan.verdict.items,
+    removed: plan.removed,
+    typosquats: plan.typosquats,
+    ...extra,
+  };
+}
+
+export async function runInstall(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        yes: { type: "boolean", short: "y", default: false },
+        "dry-run": { type: "boolean", default: false },
+        policy: { type: "string" },
+        dir: { type: "string" },
+        "save-dev": { type: "boolean", short: "D", default: false },
+        "save-exact": { type: "boolean", short: "E", default: false },
+        offline: { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        verbose: { type: "boolean", short: "v", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    printError(e.message);
+    return 2;
+  }
+  const { values: opts, positionals: specs } = parsed;
+  if (opts.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const root = resolve(opts.dir || ".");
+  if (!existsSync(root)) {
+    printError(`Path not found: ${root}`);
+    return 2;
+  }
+  const json = opts.json;
+  const out = (s) => { if (!json) process.stdout.write(s); };
+
+  let policy;
+  let policyPath;
+  try {
+    ({ policy, path: policyPath } = loadPolicy(root, opts.policy ? resolve(opts.policy) : null));
+  } catch (e) {
+    printError(e.message);
+    return 2;
+  }
+
+  let plan;
+  try {
+    const info = await npmInfo(root);
+    out(`\n  ${bold("penthera install")}  ${specs.length ? specs.join(" ") : dim("(package.json)")}  ${dim(`npm ${info.version}`)}\n`);
+    out(`  ${bold("Network")}   ${opts.offline
+      ? "npm runs with --offline (its cache only). Penthera makes no network calls."
+      : `npm contacts ${cyan(info.registry)} to resolve and download. That is the only egress; Penthera itself makes no network calls.`}\n\n`);
+    plan = await planInstall(root, specs, {
+      policy,
+      info,
+      saveDev: opts["save-dev"],
+      saveExact: opts["save-exact"],
+      offline: opts.offline,
+      onPhase: createProgress(json),
+    });
+  } catch (e) {
+    printError(e.message);
+    return 2;
+  }
+
+  if (!json) printPlan(plan, { policyPath, verbose: opts.verbose });
+  const { denied, needsApproval, clean } = plan.verdict;
+  const untouched = "Project untouched.";
+  const finish = (code, action, extra = {}) => {
+    if (json) console.log(JSON.stringify(planJson(plan, { action, ...extra }), null, 2));
+    return code;
+  };
+
+  if (opts["dry-run"]) {
+    out(`  ${dim("--dry-run: nothing installed.")}\n\n`);
+    return finish(clean ? 0 : 1, "dry-run");
+  }
+  if (denied.length) {
+    out(`  ${red("Blocked")}: ${denied.length} package(s) denied by policy. ${untouched}\n  Add them to "allow" in ${POLICY_FILE} if you trust them.\n\n`);
+    return finish(1, "blocked");
+  }
+
+  const scripts = scriptChanges(plan);
+  let runScripts = true;
+  if (!clean) {
+    if (opts.yes) {
+      out(`  ${red("Blocked")}: ${needsApproval.length} package(s) need approval and --yes only installs when nothing breaches the policy. ${untouched}\n\n`);
+      return finish(1, "blocked");
+    }
+    const withScripts = scripts.length > 0;
+    await initPrompt();
+    const answer = (await ask(withScripts
+      ? `  Install anyway? [y]es, run the install scripts / [s]kip scripts / [N]o: `
+      : `  Install anyway? [y/N]: `)).toLowerCase();
+    closePrompt();
+    if (answer === "y" || answer === "yes") runScripts = true;
+    else if (withScripts && (answer === "s" || answer === "skip")) runScripts = false;
+    else {
+      out(`\n  Aborted. ${untouched}\n\n`);
+      return finish(1, "aborted");
+    }
+  }
+
+  out(`\n  ${dim("▸")} npm install${runScripts ? "" : " --ignore-scripts"} ${dim("(installs the reviewed lockfile)")}\n`);
+  let applied;
+  try {
+    applied = await applyInstall(plan, { runScripts, offline: opts.offline });
+  } catch (e) {
+    printError(e.message);
+    return finish(2, "failed");
+  }
+  if (applied.allowScriptsAdded.length) out(`  ${dim("▸")} Approved install scripts pinned in package.json allowScripts: ${applied.allowScriptsAdded.join(", ")}\n`);
+  if (!runScripts && scripts.length) out(`  ${yellow("!")} Install scripts skipped for ${scripts.map(at).join(", ")}. Run \`npm rebuild <pkg>\` later if a package needs them.\n`);
+  if (applied.drift.length) out(`  ${yellow("!")} npm's lockfile differs from the reviewed one: ${applied.drift.slice(0, 5).join(", ")}. Run \`penthera deps --base HEAD\` to review.\n`);
+  out(`  ${green("✓")} Installed.\n\n`);
+  return finish(0, "installed", { scriptsRan: runScripts, allowScriptsAdded: applied.allowScriptsAdded, drift: applied.drift });
+}

package/src/cli/memory.js

@@ -0,0 +1,146 @@
+/**
+ * `penthera memory show | verify | forget [--all] | suppress <id> --reason <text>`
+ *
+ * Selects the project the same way a scan does: --repo <path> (default: the
+ * current directory) or --url <url> for URL-only scans.
+ */
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import {
+  openMemory, projectIdFor, memoryRoot, forgetAll, buildViews,
+} from "../../lib/memory/index.js";
+
+const USAGE = `
+  Usage
+    $ penthera memory show     [--repo <path> | --url <url>] [--json]
+    $ penthera memory verify   [--repo <path> | --url <url>]
+    $ penthera memory forget   [--repo <path> | --url <url>] [--all]
+    $ penthera memory suppress <finding-id> --reason <text> [--expires <date>]
+
+  Memory lives in ${memoryRoot()} (override with PENTHERA_HOME).
+  It is never read from the scanned repo, and nothing in it is ever executed.
+`;
+
+// Memory content is data from earlier runs: strip control characters so a
+// stored string cannot drive the terminal (ANSI escapes, cursor moves).
+const clean = (s) => String(s ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+
+export async function runMemoryCommand(argv, { out = (s) => process.stdout.write(s + "\n"), err = (s) => process.stderr.write(s + "\n") } = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        repo:    { type: "string", short: "r" },
+        url:     { type: "string" },
+        all:     { type: "boolean", default: false },
+        json:    { type: "boolean", default: false },
+        reason:  { type: "string" },
+        expires: { type: "string" },
+        help:    { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    err(`  ${e.message}`);
+    return 2;
+  }
+  const { values: opts, positionals } = parsed;
+  const cmd = positionals[0];
+  if (opts.help || !cmd) { out(USAGE); return cmd || opts.help ? 0 : 2; }
+
+  if (cmd === "forget" && opts.all) {
+    const root = memoryRoot();
+    const existed = forgetAll({ root });
+    out(existed ? `  Removed all Penthera memory in ${root}` : `  No memory at ${root}`);
+    return 0;
+  }
+
+  let project;
+  try {
+    project = opts.url ? projectIdFor({ url: opts.url }) : projectIdFor({ repo: resolve(opts.repo || ".") });
+  } catch (e) {
+    err(`  ${e.message}`);
+    return 2;
+  }
+  const mem = openMemory(project.id, { label: project.label });
+
+  switch (cmd) {
+    case "verify": {
+      const r = mem.verify();
+      if (r.ok) {
+        out(`  OK  ${r.count} event(s), chain intact${r.count ? `, tip ${r.tip.slice(0, 16)}` : ""}`);
+        out(`      ${mem.file}`);
+        return 0;
+      }
+      err(`  BROKEN  line ${r.brokenAt}: ${r.reason}`);
+      err(`      ${mem.file}`);
+      err(`      Memory is ignored by scans until this is fixed. \`penthera memory forget\` starts over.`);
+      return 1;
+    }
+
+    case "show": {
+      const r = mem.verify();
+      const v = r.ok ? buildViews(mem.events()) : null;
+      if (opts.json) {
+        out(JSON.stringify({ projectId: project.id, file: mem.file, chain: r, views: v }, null, 2));
+        return r.ok ? 0 : 1;
+      }
+      out(`  Project   ${clean(project.label)}`);
+      out(`  Id        ${project.id}`);
+      out(`  Log       ${mem.file}`);
+      out(`  Chain     ${r.ok ? `ok, ${r.count} event(s)` : `BROKEN at line ${r.brokenAt}: ${r.reason}`}`);
+      if (!v) return r.ok ? 0 : 1;
+      out(`  Scans     ${v.scans}`);
+      out(`  Median time to fix  ${v.medianTimeToFixDays == null ? "-" : `${v.medianTimeToFixDays}d`}`);
+      out("");
+      out("  Suppressions");
+      if (!v.suppressions.length) out("    none");
+      for (const s of v.suppressions) {
+        out(`    ${clean(s.id)}  ${clean(s.reason)}  (by ${clean(s.actor)}${s.expires ? `, until ${clean(s.expires)}` : ""})`);
+      }
+      out("");
+      out("  Recipe success rate");
+      if (!v.recipeSuccess.length) out("    none yet");
+      for (const x of v.recipeSuccess) {
+        const rate = x.rate == null ? "-" : `${Math.round(x.rate * 100)}%`;
+        out(`    ${clean(x.framework).padEnd(12)} ${clean(x.recipe).padEnd(28)} ${rate.padStart(4)}  (${x.verified} ok / ${x.failed} failed / ${x.applied} applied)`);
+      }
+      out("");
+      out("  Probe yield per stack");
+      const stacks = Object.keys(v.probeRanking);
+      if (!stacks.length) out("    none yet");
+      for (const st of stacks) {
+        out(`    ${clean(st)}`);
+        for (const p of v.probeRanking[st].slice(0, 10)) {
+          out(`      ${clean(p.probe).padEnd(24)} ${p.yield.toFixed(2)} per run  (${p.findings} in ${p.runs})`);
+        }
+      }
+      return 0;
+    }
+
+    case "forget": {
+      const existed = mem.forget();
+      out(existed ? `  Removed memory for ${clean(project.label)}` : `  No memory for ${clean(project.label)}`);
+      return 0;
+    }
+
+    case "suppress": {
+      const id = positionals[1];
+      if (!id || !/^[0-9a-f]{16}$/.test(id)) { err("  suppress needs a finding id (16 hex chars, the `fid` in --memory reports)"); return 2; }
+      const reason = (opts.reason || "").trim();
+      if (!reason) { err("  suppress needs --reason <text>"); return 2; }
+      if (opts.expires && Number.isNaN(Date.parse(opts.expires))) { err("  --expires is not a date"); return 2; }
+      const r = mem.verify();
+      if (!r.ok) { err(`  Memory chain is broken at line ${r.brokenAt}; not appending. Run \`penthera memory verify\`.`); return 1; }
+      mem.append({ type: "fp_suppressed", data: { id, reason, actor: "user", ...(opts.expires ? { expires: opts.expires } : {}) } });
+      out(`  Suppressed ${id} for ${clean(project.label)}`);
+      return 0;
+    }
+
+    default:
+      err(`  Unknown memory command "${clean(cmd)}"`);
+      out(USAGE);
+      return 2;
+  }
+}

package/src/cli/merge-results.js

@@ -31,6 +31,8 @@ export function mergeResults(results) {
       apiRoot: results.find((r) => r.apiRoot)?.apiRoot || null,
       machine: results.find((r) => r.machine)?.machine || null,
       executedProbes: results.flatMap((r) => r.executedProbes || []),
+      egress: results.find((r) => r.egress)?.egress || null,
+      errors: results.flatMap((r) => r.errors || []),
       findings: dedupeFindings(results.flatMap((r) => r.findings || [])),
     };
   }

package/src/cli/report-outputs.js

@@ -0,0 +1,72 @@
+/**
+ * --audience, --report-template and --evidence for the scan command. Kept out
+ * of src/cli.js: prepareReportOptions() runs before the scan (so a bad
+ * template or a non-empty evidence directory fails fast), customReport()
+ * renders the chosen report, writeEvidence() writes the bundle.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatAudienceReport, AUDIENCES } from "../report/audience.js";
+import { buildReportModel } from "../report/model.js";
+import { parseTemplate, renderTemplate } from "../report/template.js";
+import { formatMarkdownReport } from "../report/markdown.js";
+import { formatSarif } from "../reporter.js";
+import { formatReadinessMarkdown } from "../../lib/compliance/readiness.js";
+import { writeEvidenceBundle, assertEmptyDir } from "../report/evidence.js";
+
+/** Validate the report flags. Returns { template } or throws with a user-facing message. */
+export function prepareReportOptions(opts) {
+  if (opts.audience && !AUDIENCES.includes(opts.audience)) {
+    throw new Error(`Unknown --audience "${opts.audience}". Use one of: ${AUDIENCES.join(", ")}.`);
+  }
+  if (opts.audience && opts["report-template"]) throw new Error("Use --audience or --report-template, not both.");
+  if (opts["sign-key"] && !opts.evidence) throw new Error("--sign-key signs an evidence bundle; add --evidence <dir>.");
+  if (opts["sign-key"] && !existsSync(resolve(opts["sign-key"]))) throw new Error(`--sign-key ${opts["sign-key"]} not found.`);
+  if (opts.evidence) assertEmptyDir(resolve(opts.evidence));
+  let template = null;
+  if (opts["report-template"]) {
+    const src = readFileSync(resolve(opts["report-template"]), "utf-8");
+    template = parseTemplate(src); // throws TemplateError with a line number
+  }
+  return { template };
+}
+
+/** The --audience or --report-template report as Markdown, or null when neither is set. */
+export function customReport(result, opts, { version, template }) {
+  if (template) return renderTemplate(template, buildReportModel(result, { version }));
+  if (opts.audience) return formatAudienceReport(result, opts.audience, { version });
+  return null;
+}
+
+/**
+ * Write the evidence bundle: JSON, Markdown, SARIF, the three audience reports,
+ * the custom template report, readiness and SBOM when they were produced.
+ */
+export function writeEvidence(result, opts, { version, template, mdOpts, sbom, argv, now = new Date().toISOString() }) {
+  const artifacts = [
+    { path: "report.json", kind: "json", content: JSON.stringify(result, null, 2) + "\n" },
+    { path: "report.md", kind: "markdown", content: formatMarkdownReport(result, mdOpts) },
+    { path: "report.sarif", kind: "sarif", content: JSON.stringify(formatSarif(result), null, 2) + "\n" },
+    ...AUDIENCES.map((a) => ({ path: `report-${a}.md`, kind: `audience:${a}`, content: formatAudienceReport(result, a, { version }) })),
+  ];
+  if (template) artifacts.push({ path: "report-custom.md", kind: "template", content: renderTemplate(template, buildReportModel(result, { version })) });
+  if (result.readiness) artifacts.push({ path: "nis2-readiness.md", kind: "readiness", content: formatReadinessMarkdown(result.readiness) });
+  if (sbom) artifacts.push({ path: "sbom.cdx.json", kind: "sbom", content: JSON.stringify(sbom, null, 2) + "\n" });
+
+  return writeEvidenceBundle(opts.evidence, artifacts, {
+    version,
+    argv,
+    target: result.target || "unknown",
+    generatedAt: now,
+    scan: {
+      timestamp: result.timestamp || null,
+      modes: result.modes || (result.mode ? [result.mode] : []),
+      profile: result.profile || null,
+      offline: Boolean(result.egress?.offline),
+      findings: (result.findings || []).length,
+      suppressed: (result.suppressed || []).length,
+    },
+    repo: opts.repo ? resolve(opts.repo) : null,
+    signKey: opts["sign-key"] || null,
+  });
+}

package/src/cli/run-scan.js

@@ -59,6 +59,8 @@ export async function executeScan(config) {
     verbose,
     authCookie,
     authBearer,
+    offline: config.offline || false,
+    userAgent: config.userAgent || null,
     onPhase: onPhase || createProgress(quiet || json),
   };