penthera 1.2.0 → 1.5.0

package/src/cli/agent.js

@@ -0,0 +1,183 @@
+/**
+ * `penthera agent --loop`: the local scan → fix → verify → learn loop.
+ *
+ *   penthera agent --loop [--repo <path>] [--url <url>] [--max-iterations 5]
+ *                         [--auto low] [--run-tests] [--fix-model <name>] [--allow-dirty] [-o run.json]
+ *
+ * Every diff is shown and needs y (apply), n (not this run), s (skip for now)
+ * or q (quit). Fixes land as local commits on penthera/fix-<yyyymmdd-hhmm>.
+ * Nothing is pushed. See docs/local-loop.md.
+ */
+import { parseArgs } from "node:util";
+import { resolve, dirname } from "node:path";
+import { existsSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { runLoop, LoopError } from "../agent/loop.js";
+import { normalizeBaseUrl } from "../utils/url.js";
+import { printPlan } from "./fix.js";
+import { bold, dim, green, red, yellow } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera agent --loop")} — scan, fix, verify and learn, on this machine only
+
+  ${dim("Usage")}
+    $ penthera agent --loop [--repo <path>] [--url <url>]
+
+  ${dim("Options")}
+    -r, --repo <path>          Repo to fix (default: .). Must be a clean git tree on a branch
+    -u, --url <url>            Also scan this running app (egress limited to this host)
+        --max-iterations <n>   Stop after n scan/fix rounds (default: 5)
+        --auto low             Apply without asking only recipes that memory shows verified
+                               3+ times on this framework with no failures
+        --run-tests            Run the project's test script (node --run test) to verify
+        --fix-model <name>     Ask a local Ollama model (127.0.0.1:11434 only) when no recipe
+                               matches. Its diffs always need approval
+        --allow-dirty          Start with uncommitted changes or a detached HEAD (files with
+                               changes are never patched)
+    -o, --output <file>        Write the loopRun JSON here
+    -h, --help                 Show this help
+
+  Each diff asks: y apply, n not this run, s skip for now, q quit.
+  Fixes are committed on a local branch penthera/fix-<yyyymmdd-hhmm>. Nothing is
+  pushed, fetched or opened as a pull request. Ctrl-C stops after the current step.
+`;
+
+/** Line reader that works for a TTY and for piped answers. EOF answers "n". */
+function createAsker(signal) {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  const lines = rl[Symbol.asyncIterator]();
+  let eof = false;
+  const aborted = new Promise((r) => signal.addEventListener("abort", () => r({ abort: true }), { once: true }));
+
+  async function readLine(question) {
+    process.stdout.write(question);
+    if (eof) return null;
+    const next = await Promise.race([lines.next(), aborted]);
+    if (next.abort) return "q";
+    if (next.done) { eof = true; return null; }
+    if (!process.stdin.isTTY) process.stdout.write(`${next.value}\n`);
+    return next.value.trim().toLowerCase();
+  }
+
+  return {
+    async ask({ plan, iteration, index, total, memory }) {
+      process.stdout.write(`\n  ${bold(`[${iteration}.${index}/${total}]`)}`);
+      if (memory) process.stdout.write(dim(`  memory: ${memory.verified} verified, ${memory.failed} failed`));
+      printPlan(plan);
+      for (let tries = 0; tries < 5; tries++) {
+        const a = await readLine(`\n  Apply this fix? ${dim("[y]es / [n]o / [s]kip / [q]uit")} `);
+        if (a === null) {
+          process.stdout.write(`\n  ${yellow("No more input")}: not applying (answer y on a terminal to apply).\n`);
+          return "n";
+        }
+        if (a === "y" || a === "yes") return "y";
+        if (a === "n" || a === "no") return "n";
+        if (a === "s" || a === "skip") return "skip";
+        if (a === "q" || a === "quit") return "quit";
+      }
+      return "skip";
+    },
+    close: () => rl.close(),
+  };
+}
+
+export async function runAgent(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        loop: { type: "boolean", default: false },
+        repo: { type: "string", short: "r" },
+        url: { type: "string", short: "u" },
+        "max-iterations": { type: "string" },
+        auto: { type: "string" },
+        "run-tests": { type: "boolean", default: false },
+        "fix-model": { type: "string" },
+        "allow-dirty": { type: "boolean", default: false },
+        output: { type: "string", short: "o" },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`  ${red("Error")} ${e.message}\n${HELP}`);
+    return 2;
+  }
+  const opts = parsed.values;
+  if (opts.help || !opts.loop) {
+    console.log(HELP);
+    return opts.help ? 0 : 2;
+  }
+  if (opts.auto != null && opts.auto !== "low") {
+    process.stderr.write(`  ${red("Error")} --auto only accepts "low"\n`);
+    return 2;
+  }
+  const maxIterations = opts["max-iterations"] == null ? 5 : Number(opts["max-iterations"]);
+  if (!Number.isInteger(maxIterations) || maxIterations < 1 || maxIterations > 50) {
+    process.stderr.write(`  ${red("Error")} --max-iterations must be a whole number from 1 to 50\n`);
+    return 2;
+  }
+  const repo = resolve(opts.repo || ".");
+  if (!existsSync(repo) || !statSync(repo).isDirectory()) {
+    process.stderr.write(`  ${red("Error")} Repo not found: ${repo}\n`);
+    return 2;
+  }
+  const rawUrl = opts.url || parsed.positionals[0];
+  const url = rawUrl ? normalizeBaseUrl(rawUrl) : null;
+
+  const controller = new AbortController();
+  const handle = {};
+  let interrupts = 0;
+  const onSigint = () => {
+    interrupts++;
+    if (interrupts === 1) {
+      process.stdout.write(`\n  ${yellow("Stopping")} after the current step. Ctrl-C again to revert the fix in flight and exit now.\n`);
+      controller.abort();
+      return;
+    }
+    try { handle.revertPending?.(); } catch { /* best effort */ }
+    process.stdout.write(`\n  ${red("Stopped.")} The fix branch holds only verified commits.\n`);
+    process.exit(130);
+  };
+  process.on("SIGINT", onSigint);
+
+  const asker = createAsker(controller.signal);
+  process.stdout.write(`\n  ${bold("penthera agent --loop")} ${dim(repo)}${url ? dim(` + ${url}`) : ""}\n`);
+  process.stdout.write(dim(`  local only: egress limited to ${url ? new URL(url).host : "no hosts (repo scan only)"}${opts["fix-model"] ? " and Ollama on 127.0.0.1:11434" : ""}; nothing is pushed\n`));
+
+  let run;
+  try {
+    run = await runLoop({
+      repo, url, maxIterations, auto: opts.auto || "off", runTests: opts["run-tests"],
+      fixModel: opts["fix-model"] || null, allowDirty: opts["allow-dirty"],
+      ask: asker.ask, log: (l) => process.stdout.write(`${l}\n`), signal: controller.signal, handle,
+    });
+  } catch (e) {
+    asker.close();
+    process.off("SIGINT", onSigint);
+    process.stderr.write(`  ${red("Not started")} ${e.message}\n`);
+    return e instanceof LoopError ? 2 : 1;
+  }
+  asker.close();
+  process.off("SIGINT", onSigint);
+
+  if (opts.output) {
+    const out = resolve(opts.output);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, JSON.stringify({ loopRun: run }, null, 2) + "\n");
+  }
+
+  const t = run.totals;
+  process.stdout.write(`\n  ${bold("Done")}: ${run.stopReason} after ${t.iterations} iteration${t.iterations === 1 ? "" : "s"} (${(run.durationMs / 1000).toFixed(1)}s)\n`);
+  process.stdout.write(`  ${green(`${t.verified} verified`)}, ${t.failed ? red(`${t.failed} failed and reverted`) : "0 failed"}, ${t.declined} declined, ${t.skipped} skipped\n`);
+  process.stdout.write(`  findings: ${run.findings.initial ?? "?"} → ${run.findings.final ?? "?"} (non-info)\n`);
+  if (run.error) process.stdout.write(`  ${red("Error")} ${run.error}\n`);
+  process.stdout.write(`  branch ${bold(run.branch.fix)}: review with  git log --stat ${run.branch.base || run.branch.baseSha.slice(0, 12)}..${run.branch.fix}\n`);
+  if (opts.output) process.stdout.write(`  loopRun written to ${opts.output}\n`);
+  process.stdout.write(`  Nothing was pushed. Merge or push the branch yourself when you are happy with it.\n\n`);
+
+  if (run.stopReason === "error") return 1;
+  if (run.stopReason === "interrupted") return 130;
+  return run.stopReason === "no-fixable-findings" ? 0 : 1;
+}

package/src/cli/deps.js

@@ -0,0 +1,104 @@
+/**
+ * `penthera deps [path]`: CLI runner for the dependency capability scan.
+ */
+import { resolve } from "node:path";
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { mergeResults } from "./merge-results.js";
+import { buildActionPlan } from "../../lib/remediation/index.js";
+import { printReport, printFindings, writeJsonReport, writeSarifReport, createProgress, printError } from "../reporter.js";
+import { writeMarkdownReport, markdownPathFromJson } from "../report/markdown.js";
+
+export const DEPS_FLAGS = ["diff", "base", "online", "pr-comment", "prod", "license-policy"];
+
+/**
+ * The license policy for this run: `--license-policy <preset|file>`, else the
+ * `licenses` section of penthera.policy.json, else none.
+ */
+async function resolveLicensePolicy(root, flag) {
+  const { normalizeLicensePolicy, LICENSE_PRESETS } = await import("../../lib/deps/license.js");
+  if (flag) {
+    if (LICENSE_PRESETS[flag]) return normalizeLicensePolicy({ preset: flag }, "--license-policy");
+    const path = resolve(flag);
+    if (!existsSync(path)) throw new Error(`--license-policy: "${flag}" is neither a preset (${Object.keys(LICENSE_PRESETS).join(", ")}) nor a file`);
+    let raw;
+    try { raw = JSON.parse(readFileSync(path, "utf-8")); } catch (e) { throw new Error(`${flag}: ${e.message}`); }
+    return normalizeLicensePolicy(raw && typeof raw === "object" && "licenses" in raw ? raw.licenses : raw, `${flag}: licenses`);
+  }
+  const { loadPolicy } = await import("../../lib/install/policy.js");
+  return loadPolicy(root).policy.licenses;
+}
+
+export async function runDeps(args, opts, { version }) {
+  if (args.length > 1) {
+    printError(`deps takes one path, got: ${args.join(" ")}`);
+    process.exit(2);
+  }
+  if (opts.diff && opts.base) {
+    printError("Use --diff <lockfile|dir> or --base <git-ref>, not both.");
+    process.exit(2);
+  }
+  const root = resolve(args[0] || ".");
+  if (!existsSync(root)) {
+    printError(`Path not found: ${root}`);
+    process.exit(2);
+  }
+  const quiet = opts.quiet || opts.json;
+  if (opts.online && !quiet) {
+    process.stderr.write("\n  \x1b[33mNOTE\x1b[0m --online fetches public package metadata from the npm registry.\n" +
+      "       This is the only network use in `penthera deps`; without it, nothing leaves this machine.\n\n");
+  }
+
+  const { scanDeps } = await import("../../lib/deps/index.js");
+  let result;
+  try {
+    const licensePolicy = await resolveLicensePolicy(root, opts["license-policy"]);
+    result = await scanDeps(root, {
+      licensePolicy,
+      diff: opts.diff || null,
+      base: opts.base || null,
+      online: !!opts.online,
+      prod: !!opts.prod,
+      onPhase: createProgress(quiet),
+    });
+  } catch (e) {
+    printError(e.message);
+    process.exit(2);
+  }
+
+  const merged = mergeResults([result]);
+  merged.actionPlan = buildActionPlan(merged.findings);
+
+  if (opts.json) console.log(JSON.stringify(merged, null, 2));
+  else if (opts.quiet) printFindings(merged.findings);
+  else printReport(merged, { verbose: opts.verbose });
+
+  const mdOpts = { version };
+  const note = (s) => { if (!quiet) process.stderr.write(s); };
+  if (opts.output) {
+    writeJsonReport(merged, opts.output);
+    const md = markdownPathFromJson(opts.output);
+    writeMarkdownReport(merged, md, mdOpts);
+    note(`  JSON report    ${opts.output}\n  Markdown report ${md}\n`);
+  }
+  if (opts.markdown) {
+    writeMarkdownReport(merged, opts.markdown, mdOpts);
+    note(`  Markdown report ${opts.markdown}\n`);
+  }
+  if (opts.sarif) {
+    writeSarifReport(merged, opts.sarif);
+    note(`  SARIF report   ${opts.sarif}\n`);
+  }
+  if (opts["pr-comment"]) {
+    const { formatPrComment } = await import("../../lib/deps/report.js");
+    const path = resolve(opts["pr-comment"]);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, formatPrComment(merged, { version }));
+    note(`  PR comment     ${opts["pr-comment"]}\n`);
+  }
+  if (opts.output || opts.markdown || opts.sarif || opts["pr-comment"]) note("\n");
+
+  // exitCode, not exit(): large --json output to a pipe must drain first.
+  const hasSevere = merged.findings.some((f) => f.severity === "critical" || f.severity === "high");
+  process.exitCode = hasSevere ? 1 : 0;
+}

package/src/cli/evidence.js

@@ -0,0 +1,67 @@
+/**
+ * `penthera evidence verify <dir> [--allowed-signers <file>] [--json]`
+ *
+ * Recomputes every artifact hash in an evidence bundle and checks the SSH
+ * signature over manifest.json. Exit 0 when the bundle verifies, 1 when it
+ * does not, 2 on a usage error.
+ */
+import { parseArgs } from "node:util";
+import { verifyEvidence } from "../report/evidence.js";
+
+const HELP = `
+  penthera evidence verify <dir> [--allowed-signers <file>] [--json]
+
+  Recomputes the SHA-256 of every file in an evidence bundle (written with
+  --evidence <dir>), fails on any changed, missing or extra file, and checks
+  manifest.json.sig with ssh-keygen against the allowed signers file.
+
+  Exit codes: 0 verified, 1 verification failed, 2 usage error.
+  See docs/evidence.md.
+`;
+
+export function runEvidence(argv, { out = process.stdout } = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        "allowed-signers": { type: "string" },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`  ${e.message}\n${HELP}`);
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  if (values.help || positionals[0] !== "verify" || positionals.length !== 2) {
+    (values.help ? out : process.stderr).write(HELP);
+    return values.help ? 0 : 2;
+  }
+
+  const r = verifyEvidence(positionals[1], { allowedSigners: values["allowed-signers"] || null });
+  if (values.json) {
+    const { manifest, ...rest } = r;
+    out.write(JSON.stringify({ ...rest, target: manifest?.target || null, generated_at: manifest?.generated_at || null }, null, 2) + "\n");
+    return r.ok ? 0 : 1;
+  }
+
+  const m = r.manifest;
+  if (m) {
+    out.write(`\n  Bundle     ${positionals[1]}\n`);
+    out.write(`  Target     ${m.target}\n`);
+    out.write(`  Generated  ${m.generated_at} by penthera ${m.tool?.version}\n`);
+    if (m.git) out.write(`  Git        ${m.git.commit}${m.git.dirty ? " (uncommitted changes)" : ""}\n`);
+    out.write("\n");
+  }
+  for (const f of r.files) out.write(`  ${f.ok ? "ok  " : "FAIL"}  ${f.path}${f.ok ? "" : `  (${f.reason})`}\n`);
+  for (const p of r.unlisted) out.write(`  FAIL  ${p}  (not in manifest)\n`);
+  if (r.signature) {
+    const label = r.signature.ok ? (r.signature.status === "valid" ? "ok  " : "warn") : "FAIL";
+    out.write(`  ${label}  signature: ${r.signature.detail}\n`);
+  }
+  out.write(r.ok ? "\n  Verified: every artifact matches the manifest.\n\n" : `\n  NOT VERIFIED:\n${r.problems.map((p) => `    - ${p}\n`).join("")}\n`);
+  return r.ok ? 0 : 1;
+}

package/src/cli/fix.js

@@ -0,0 +1,191 @@
+/**
+ * `penthera fix`: plan and apply deterministic fix recipes, locally.
+ *
+ *   penthera fix --plan [--repo <path>] [-o <report.json>]
+ *   penthera fix --apply <id> [--repo <path>] [-o <report.json>] [--yes] [--dry-run] [--allow-dirty]
+ *
+ * Planning never writes. Applying needs an explicit plan id plus approval (a
+ * y/N prompt, or --yes), never pushes, and refuses a dirty git tree. Nothing
+ * here touches the network, except the optional --fix-model fallback, which
+ * only talks to Ollama on 127.0.0.1.
+ */
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { scanRepo } from "../scan-repo.js";
+import { planFixes, probeRepo, redactPlan, applyDiff, findingKey, createModelFixer } from "../../lib/fix/index.js";
+import { bold, dim, green, red, yellow, cyan } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera fix")} — plan and apply local fix recipes
+
+  ${dim("Usage")}
+    $ penthera fix --plan [--repo <path>]          Print a diff for each fixable finding
+    $ penthera fix --apply <id> [--repo <path>]    Apply one planned diff (asks first)
+
+  ${dim("Options")}
+    -r, --repo <path>        Repo to fix (default: .)
+    -o, --input <file>       Use findings from a JSON report (penthera ... -o report.json)
+                             instead of a fresh repo scan
+        --fix-model <name>   Ask a local Ollama model (127.0.0.1:11434 only) when no recipe
+                             matches. Off by default; output needs human review
+        --json               Print plans as JSON (secrets masked)
+        --yes                Approve the diff without the y/N prompt (for --apply)
+        --dry-run            Check that the diff applies, write nothing
+        --allow-dirty        Apply even with uncommitted changes in the repo
+    -h, --help               Show this help
+
+  Recipes: security headers, cookie flags, CORS allowlist, login rate limit,
+  hardcoded secret to env var. Plans change after each apply: run --plan again.
+`;
+
+/** Findings for the repo: a report's findings, or a fresh scan plus recipe probes. */
+async function gatherFindings(repo, input) {
+  if (input) {
+    const report = JSON.parse(readFileSync(resolve(input), "utf-8"));
+    return { findings: report.findings || [], fresh: false };
+  }
+  const result = await scanRepo(repo, {});
+  const seen = new Set();
+  const findings = [...result.findings, ...probeRepo(repo)].filter((f) => {
+    if (f.severity === "info" && f.category === "config") return false;
+    const k = findingKey(f);
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+  return { findings, fresh: true };
+}
+
+export function colorDiff(diff) {
+  return diff.split("\n").map((l) => {
+    if (/^(---|\+\+\+) /.test(l)) return bold(l);
+    if (l.startsWith("@@")) return cyan(l);
+    if (l.startsWith("+")) return green(l);
+    if (l.startsWith("-")) return red(l);
+    return l;
+  }).join("\n");
+}
+
+export function printPlan(plan) {
+  const conf = plan.confidence === "needs-human-review" ? yellow(plan.confidence) : plan.confidence;
+  process.stdout.write(`\n  ${bold(plan.id)}  ${plan.title}${plan.framework ? dim(` (${plan.framework})`) : ""}  confidence: ${conf}  source: ${plan.source}\n`);
+  for (const f of plan.findings) process.stdout.write(`    ${dim("fixes")} [${f.severity || "?"}] ${f.title}${f.url ? dim(` ${f.url}`) : ""}\n`);
+  for (const a of plan.ownerActions) process.stdout.write(`    ${yellow("owner action")} ${a}\n`);
+  process.stdout.write("\n" + colorDiff(plan.diff).replace(/^/gm, "    ").trimEnd() + "\n");
+}
+
+async function approve(plan, opts) {
+  if (opts.yes) return true;
+  if (!process.stdin.isTTY) {
+    process.stderr.write(`  Not applying ${plan.id}: review the diff above, then re-run with --yes to approve it.\n`);
+    return false;
+  }
+  const { initPrompt, confirm, closePrompt } = await import("./prompt.js");
+  await initPrompt();
+  const ok = await confirm(`\n  Apply ${plan.id} to the working tree?`, false);
+  closePrompt();
+  return ok;
+}
+
+export async function runFix(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: false,
+      options: {
+        plan: { type: "boolean", default: false },
+        apply: { type: "string" },
+        repo: { type: "string", short: "r" },
+        input: { type: "string", short: "o" },
+        "fix-model": { type: "string" },
+        json: { type: "boolean", default: false },
+        yes: { type: "boolean", default: false },
+        "dry-run": { type: "boolean", default: false },
+        "allow-dirty": { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`  ${red("Error")} ${e.message}\n${HELP}`);
+    process.exit(2);
+  }
+  const opts = parsed.values;
+  if (opts.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const repo = resolve(opts.repo || ".");
+  if (!existsSync(repo) || !statSync(repo).isDirectory()) {
+    process.stderr.write(`  ${red("Error")} Repo not found: ${repo}\n`);
+    process.exit(2);
+  }
+
+  let model = null;
+  if (opts["fix-model"]) model = createModelFixer({ model: opts["fix-model"] });
+
+  let gathered;
+  try {
+    gathered = await gatherFindings(repo, opts.input);
+  } catch (e) {
+    process.stderr.write(`  ${red("Error")} Could not read findings: ${e.message}\n`);
+    process.exit(2);
+  }
+  const { plans, unmatched } = await planFixes(repo, gathered.findings, { model });
+
+  if (!opts.apply) {
+    if (opts.json) {
+      console.log(JSON.stringify({ repo, plans: plans.map(redactPlan), unmatched: unmatched.map((f) => ({ title: f.title, category: f.category, severity: f.severity, url: f.url || null })) }, null, 2));
+      process.exit(0);
+    }
+    process.stdout.write(`\n  ${bold("penthera fix")} ${dim(repo)}\n`);
+    process.stdout.write(`  ${plans.length} fix${plans.length === 1 ? "" : "es"} planned for ${gathered.findings.length} finding${gathered.findings.length === 1 ? "" : "s"}${gathered.fresh ? " (fresh repo scan)" : ` (from ${opts.input})`}\n`);
+    for (const p of plans) printPlan(redactPlan(p));
+    const manual = unmatched.filter((f) => f.severity !== "info");
+    if (manual.length) {
+      process.stdout.write(`\n  ${dim(`${manual.length} finding${manual.length === 1 ? "" : "s"} without a recipe; fix by hand (see the report's action plan)${model ? "" : " or try --fix-model <name>"}:`)}\n`);
+      for (const f of manual.slice(0, 20)) process.stdout.write(`    [${f.severity}] ${f.title}\n`);
+    }
+    if (plans.length) process.stdout.write(`\n  Apply one:  penthera fix --apply <id>${opts.repo ? ` --repo ${opts.repo}` : ""}${opts.input ? ` -o ${opts.input}` : ""}\n\n`);
+    process.exit(0);
+  }
+
+  const plan = plans.find((p) => p.id === opts.apply);
+  if (!plan) {
+    process.stderr.write(`  ${red("Error")} No plan with id ${opts.apply}. Plans change after each apply; run penthera fix --plan again.\n`);
+    process.exit(2);
+  }
+  printPlan(redactPlan(plan));
+  if (!opts["dry-run"] && !(await approve(plan, opts))) process.exit(1);
+
+  let result;
+  try {
+    result = applyDiff(repo, plan.diff, { dryRun: opts["dry-run"], allowDirty: opts["allow-dirty"] });
+  } catch (e) {
+    process.stderr.write(`  ${red("Not applied")} ${e.message}\n`);
+    process.exit(2);
+  }
+  const verb = result.applied ? "Applied" : "Dry run, would change";
+  process.stdout.write(`\n  ${green(verb)} ${result.files.map((f) => f.path + (f.created ? " (new)" : "")).join(", ")}\n`);
+  if (!result.applied) process.exit(0);
+
+  // Verify by re-scanning. Report findings came from a scan we can't repeat here.
+  if (gathered.fresh) {
+    const after = await gatherFindings(repo, null);
+    const still = new Set(after.findings.map(findingKey));
+    for (const f of plan.findings) {
+      const gone = !still.has(findingKey(f));
+      process.stdout.write(`  ${gone ? green("verified") : yellow("still reported")} ${f.title}\n`);
+    }
+  } else {
+    process.stdout.write(`  Re-run the scan that produced ${opts.input} to verify.\n`);
+  }
+  if (plan.ownerActions.length) {
+    process.stdout.write(`\n  ${yellow("Still on you:")}\n`);
+    for (const a of plan.ownerActions) process.stdout.write(`    - ${a}\n`);
+  }
+  process.stdout.write(`\n  Nothing was committed or pushed. Review with git diff, then commit it yourself.\n\n`);
+  process.exit(0);
+}

package/src/cli/hook.js

@@ -0,0 +1,131 @@
+/**
+ * `penthera hook install|uninstall|run`: the pre-commit hook (lib/hook/).
+ * Exit codes for `run`: 0 commit may go ahead, 1 blocked, 2 error (also blocks).
+ */
+import { parseArgs } from "node:util";
+import { relative, resolve } from "node:path";
+import { runHook, installHook, uninstallHook, fixHint } from "../../lib/hook/index.js";
+import { printError } from "../reporter.js";
+import { bold, dim, green, red, yellow, cyan } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera hook")} — block secrets, malicious agent config and risky lockfile changes before they are committed
+
+  ${dim("Usage")}
+    $ penthera hook install      Write .git/hooks/pre-commit (an existing hook is kept and runs first)
+    $ penthera hook uninstall    Remove it and restore the hook it replaced
+    $ penthera hook run          Check what is staged now (what the hook runs)
+
+  ${dim("Options")}
+        --policy <file>    Policy file (default: ./penthera.policy.json)
+        --force            install: write into core.hooksPath even when another tool manages it
+        --json             run: print the result as JSON
+    -v, --verbose          run: also list findings below the blocking severity
+    -h, --help             Show this help
+
+  ${dim("What it checks (staged content only, offline)")}
+    Secrets and AI provider keys in staged files; \`penthera agents\` rules on staged
+    .mcp.json, CLAUDE.md, AGENTS.md, .claude/, .cursor/ and skills/; and, when
+    package-lock.json is staged, the capability diff against HEAD plus the license
+    policy. Blocks on high and critical by default.
+
+  ${dim("Policy")}  ${dim("(penthera.policy.json)")}
+    { "hook": { "blockOn": "high", "ignore": ["tests/fixtures/**"],
+                "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true } } }
+
+  ${dim("Other hook managers")}
+    pre-commit:  repo: https://github.com/danoszz/penthera, hooks: [{ id: penthera }]
+    husky:       echo "npx --no-install penthera hook run" >> .husky/pre-commit
+    lefthook:    pre-commit: { commands: { penthera: { run: npx --no-install penthera hook run } } }
+`;
+
+const SEV = { critical: red, high: red, medium: yellow, low: dim, info: dim };
+const where = (f) => `${f.url}${f.line ? `:${f.line}` : ""}`;
+
+function findingLine(f, mark) {
+  const sev = (SEV[f.severity] || dim)(f.severity.toUpperCase().padEnd(8));
+  const ev = f.evidence ? `  ${dim(f.evidence)}` : "";
+  return `  ${mark} ${sev} ${cyan(where(f))}  ${f.title}${ev}  ${dim(`id ${f.id}`)}\n      ${dim("→")} ${fixHint(f)}`;
+}
+
+function printRun(r, { verbose }) {
+  const L = [];
+  const secs = (r.duration / 1000).toFixed(1);
+  const what = [`${r.staged} staged file${r.staged === 1 ? "" : "s"}`, r.checked.agents && `${r.checked.agents} agent config`, r.checked.lockfiles && `${r.checked.lockfiles} lockfile`].filter(Boolean).join(", ");
+  for (const w of r.warnings) L.push(`  ${yellow("!")} ${w}`);
+  if (!r.blocking.length) {
+    const below = r.below.length ? dim(` · ${r.below.length} below ${r.blockOn}${verbose ? "" : " (-v to list)"}`) : "";
+    const sup = r.suppressed.length ? dim(` · ${r.suppressed.length} suppressed`) : "";
+    L.push(`  ${green("✓")} ${bold("penthera")} ${what} checked in ${secs}s${below}${sup}`);
+    if (verbose) for (const f of r.below) L.push(findingLine(f, yellow("!")));
+    process.stderr.write(L.join("\n") + "\n");
+    return;
+  }
+  L.push("");
+  L.push(`  ${red("✗")} ${bold("penthera")} blocked this commit: ${r.blocking.length} finding${r.blocking.length === 1 ? "" : "s"} at ${r.blockOn} or above ${dim(`(${what}, ${secs}s)`)}`);
+  L.push("");
+  for (const f of r.blocking) L.push(findingLine(f, red("✗")));
+  if (verbose) for (const f of r.below) L.push(findingLine(f, yellow("!")));
+  else if (r.below.length) L.push(dim(`  + ${r.below.length} below ${r.blockOn}, not blocking (-v to list)`));
+  L.push("");
+  L.push(`  Fix and \`git add\` again. A false positive? Add it to penthera.suppress.json:`);
+  L.push(dim(`    { "version": 1, "suppress": [{ "id": "${r.blocking[0].id}", "reason": "why this is safe" }] }`));
+  L.push(`  To skip the check for one commit: ${bold("git commit --no-verify")} ${dim("(the finding still ships)")}`);
+  L.push("");
+  process.stderr.write(L.join("\n") + "\n");
+}
+
+export async function runHookCommand(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        policy: { type: "string" },
+        force: { 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 } = parsed;
+  const sub = positionals[0];
+  if (opts.help || !sub) {
+    console.log(HELP);
+    return sub || opts.help ? 0 : 2;
+  }
+  const cwd = process.cwd();
+  const rel = (p) => relative(cwd, p) || p;
+  try {
+    if (sub === "install") {
+      const r = installHook(cwd, { force: opts.force });
+      console.log(`  ${green("✓")} ${r.updated ? "Updated" : "Installed"} ${rel(r.path)}`);
+      if (r.chained) console.log(`  ${dim("▸")} Your existing hook moved to ${rel(r.chained)} and runs first; \`penthera hook uninstall\` puts it back.`);
+      console.log(`  ${dim("▸")} Every commit now checks staged secrets, agent config and lockfile changes. Skip once with git commit --no-verify.`);
+      return 0;
+    }
+    if (sub === "uninstall") {
+      const r = uninstallHook(cwd);
+      if (!r.removed) console.log(`  ${dim("No penthera pre-commit hook installed.")}`);
+      else console.log(`  ${green("✓")} Removed ${rel(r.path)}${r.restored ? `; your previous hook is back in place` : ""}`);
+      return 0;
+    }
+    if (sub === "run") {
+      const r = await runHook(cwd, { policyPath: opts.policy ? resolve(opts.policy) : null });
+      if (opts.json) console.log(JSON.stringify(r, null, 2));
+      else printRun(r, { verbose: opts.verbose });
+      return r.blocking.length ? 1 : 0;
+    }
+  } catch (e) {
+    printError(e.message);
+    if (sub === "run") process.stderr.write(`  ${dim("The commit is blocked because the check could not run. Skip it once with git commit --no-verify.")}\n`);
+    return 2;
+  }
+  printError(`Unknown hook command "${sub}". Use install, uninstall or run.`);
+  return 2;
+}