penthera 1.2.0 → 1.5.0

package/lib/fix/util.js

@@ -0,0 +1,231 @@
+/**
+ * Shared helpers for fix recipes: framework detection, file discovery, and the
+ * small, anchor-based text edits recipes are built from. No AST: every edit
+ * keys off a line the recipe can recognise exactly, and gives up otherwise.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { detectFramework as detectSourceFramework } from "../whitebox/frameworks.js";
+import { createPatch } from "./diff.js";
+
+const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "vendor", "reports", ".security-results"]);
+const CODE_EXT = /\.(js|ts|mjs|cjs|jsx|tsx)$/;
+const MAX_FILES = 2000;
+
+export const ENTRY_CANDIDATES = [
+  "server.js", "server.ts", "server.mjs", "app.js", "app.ts", "app.mjs",
+  "index.js", "index.ts", "index.mjs", "main.js", "main.ts",
+  "src/server.js", "src/server.ts", "src/app.js", "src/app.ts",
+  "src/index.js", "src/index.ts", "src/main.js", "src/main.ts",
+];
+
+export function readText(repoPath, rel) {
+  try {
+    return readFileSync(join(repoPath, rel), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function readPackageJson(repoPath) {
+  const text = readText(repoPath, "package.json");
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function hasDep(repoPath, name) {
+  const pkg = readPackageJson(repoPath);
+  return Boolean(pkg && (pkg.dependencies?.[name] || pkg.devDependencies?.[name]));
+}
+
+/**
+ * The web framework a repo uses: "next" | "hono" | "fastify" | "express" | null.
+ * package.json decides; source imports (via the white-box route scanner's
+ * detector) are the fallback for repos without one.
+ */
+export function detectFramework(repoPath) {
+  for (const fw of ["next", "hono", "fastify", "express"]) if (hasDep(repoPath, fw)) return fw;
+  if (["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"].some((f) => existsSync(join(repoPath, f)))) return "next";
+  for (const rel of ENTRY_CANDIDATES) {
+    const source = readText(repoPath, rel);
+    if (!source) continue;
+    const fw = detectSourceFramework(source);
+    if (fw !== "node") return fw;
+  }
+  return null;
+}
+
+/** Repo-relative paths of JS/TS source files, skipping dependencies and build output. */
+export function walkCodeFiles(repoPath) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort()) {
+      if (out.length >= MAX_FILES) return;
+      if (SKIP.has(entry)) continue;
+      const full = join(dir, entry);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(full);
+      else if (CODE_EXT.test(entry) && !/\.(test|spec)\.|\.d\.ts$|\.min\.js$/.test(entry)) out.push(relative(repoPath, full));
+    }
+  };
+  walk(repoPath);
+  return out;
+}
+
+/** First entry-candidate file whose source matches `anchor`. */
+export function findEntryFile(repoPath, anchor) {
+  const candidates = [...ENTRY_CANDIDATES];
+  const main = readPackageJson(repoPath)?.main;
+  if (typeof main === "string") candidates.unshift(main.replace(/^\.\//, ""));
+  for (const rel of candidates) {
+    const source = readText(repoPath, rel);
+    if (source && anchor.test(source)) return { file: rel, source };
+  }
+  return null;
+}
+
+export const isTypeScript = (file) => /\.tsx?$/.test(file);
+
+export function moduleStyle(source) {
+  if (/^\s*import\s[^;]*?from\s+['"]|^\s*import\s+['"]|^\s*export\s/m.test(source)) return "esm";
+  if (/\brequire\s*\(/.test(source)) return "cjs";
+  return "esm";
+}
+
+/** Index of the line after the last top-level import/require statement. */
+function importBlockEnd(lines) {
+  let end = 0;
+  let open = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (open) {
+      if (/\bfrom\s+['"][^'"]+['"];?\s*$/.test(l)) { open = false; end = i + 1; }
+      continue;
+    }
+    if (/^import\s.*\bfrom\s+['"][^'"]+['"];?\s*$/.test(l) || /^import\s+['"][^'"]+['"];?\s*$/.test(l)) end = i + 1;
+    else if (/^import\s+(?:type\s+)?\{[^}]*$/.test(l)) open = true;
+    else if (/^(?:const|let|var)\s+[\w{}\s,:]+=\s*require\(\s*['"][^'"]+['"]\s*\)[\w.]*;?\s*$/.test(l)) end = i + 1;
+    else if (i === 0 && /^#!/.test(l)) end = 1;
+    else if (/^['"]use (strict|client|server)['"];?\s*$/.test(l)) end = Math.max(end, i + 1);
+  }
+  return end;
+}
+
+/** Insert `block` (lines) after the import block, separated by a blank line. */
+export function insertAfterImports(source, block) {
+  const lines = source.split("\n");
+  const at = importBlockEnd(lines);
+  const insert = [...block];
+  if (at > 0 && lines[at - 1].trim() !== "") insert.unshift("");
+  if (lines[at] !== undefined && lines[at].trim() !== "") insert.push("");
+  lines.splice(at, 0, ...insert);
+  return lines.join("\n");
+}
+
+/** Add an import (ESM or CommonJS, matching the file) unless the module is already imported. */
+export function addImport(source, { name, module, named = false }) {
+  const escaped = module.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  if (new RegExp(`from\\s+['"]${escaped}['"]|require\\(\\s*['"]${escaped}['"]\\s*\\)`).test(source)) return source;
+  const line = moduleStyle(source) === "cjs"
+    ? `const ${named ? `{ ${name} }` : name} = require("${module}");`
+    : `import ${named ? `{ ${name} }` : name} from "${module}";`;
+  const lines = source.split("\n");
+  const at = importBlockEnd(lines);
+  lines.splice(at, 0, line);
+  return lines.join("\n");
+}
+
+/** Insert lines right after line `index`, matching that line's indentation. */
+export function insertAfterLine(source, index, block) {
+  const lines = source.split("\n");
+  const indent = lines[index].match(/^\s*/)[0];
+  lines.splice(index + 1, 0, ...block.map((l) => (l ? indent + l : l)));
+  return lines.join("\n");
+}
+
+/** Index of the first line matching re, or -1. */
+export function findLine(source, re) {
+  return source.split("\n").findIndex((l) => re.test(l));
+}
+
+/**
+ * Split a call's arguments starting at the "(" at `open`, on one line only.
+ * Returns { args: [{ text, start, end }], close } with absolute offsets, or
+ * null if the call does not close before the end of the line.
+ */
+export function splitCallArgs(text, open) {
+  const args = [];
+  let depth = 0;
+  let quote = null;
+  let argStart = open + 1;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\n" && !quote) return null;
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      else if (ch === "\n") return null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      if (depth === 0) {
+        if (text.slice(argStart, i).trim()) args.push({ text: text.slice(argStart, i).trim(), start: argStart, end: i });
+        return { args, close: i };
+      }
+    } else if (ch === "," && depth === 1) {
+      args.push({ text: text.slice(argStart, i).trim(), start: argStart, end: i });
+      argStart = i + 1;
+    }
+  }
+  return null;
+}
+
+/** Add `NAME=value` to .env.example (creating it) unless NAME is already listed. */
+export function envExampleChange(repoPath, name, value = "", comment = null) {
+  const before = readText(repoPath, ".env.example");
+  if (before != null && new RegExp(`^\\s*${name}\\s*=`, "m").test(before)) return null;
+  const add = [...(comment ? [`# ${comment}`] : []), `${name}=${value}`].join("\n") + "\n";
+  const after = before == null ? add : before + (before.endsWith("\n") || before === "" ? "" : "\n") + add;
+  return { file: ".env.example", before, after };
+}
+
+/** Turn [{ file, before, after }] into { diff, files }, dropping no-op changes. */
+export function toDiff(changes) {
+  const parts = [];
+  const files = [];
+  for (const c of changes.filter(Boolean)) {
+    const patch = createPatch(c.file, c.before, c.after);
+    if (!patch) continue;
+    parts.push(patch);
+    files.push(c.file);
+  }
+  if (parts.length === 0) return null;
+  return { diff: parts.join(""), files };
+}
+
+/** "sessionSecret" / "api-key" -> "SESSION_SECRET" / "API_KEY". */
+export function toEnvName(key) {
+  return String(key)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toUpperCase();
+}

package/lib/fuzzer.js

@@ -8,8 +8,17 @@
  *   - Schemathesis, property-based testing from API schemas
  *   - RESTler, stateful fuzzing with dependency inference
  *   - fast-check, shrinkable random generators
+ *
+ * What this file is, for anyone reviewing the package:
+ *   The values below are edge-case test inputs (type confusion, oversized
+ *   strings, well-known injection probes). Penthera never executes them. They
+ *   are sent as JSON request bodies to the user's own target, and only when
+ *   the user opts in with --fuzz (or the deep profile), to see whether the API
+ *   validates its input. Nothing runs on the machine running Penthera.
  */
 
+import { request } from "../src/utils/http.js";
+
 // ── Payload Generators ────────────────────────────────────────────────────
 
 /** Generate fuzz values for a given field name (heuristic-based) */
@@ -176,15 +185,14 @@ export async function fuzzEndpoint(baseUrl, path, validBody, opts = {}) {
       continue; // can't serialize (e.g., circular)
     }
 
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-
     try {
-      const res = await fetch(`${baseUrl}${path}`, {
+      const res = await request(`${baseUrl}${path}`, {
         method,
         headers,
         body,
-        signal: controller.signal,
+        timeout,
+        probe: "api-fuzzing",
+        redirect: "follow",
       });
 
       const text = await res.text().catch(() => "");
@@ -223,9 +231,7 @@ export async function fuzzEndpoint(baseUrl, path, validBody, opts = {}) {
         findings.push(result);
       }
     } catch {
-      // timeout or network error, skip
-    } finally {
-      clearTimeout(timer);
+      // timeout or network error: recorded in result.errors by the HTTP client
     }
   }
 

package/lib/hook/index.js

@@ -0,0 +1,312 @@
+/**
+ * `penthera hook`: a git pre-commit hook that runs the checks that matter most
+ * before code leaves the laptop, on staged content only.
+ *
+ *   - secrets in staged files (lib/whitebox/secrets.js, AI provider keys included)
+ *   - `penthera agents` rules on staged agent config (.mcp.json, CLAUDE.md, skills/, ...)
+ *   - a staged package-lock.json: the capability diff against HEAD's lockfile,
+ *     plus the license policy when penthera.policy.json has one
+ *
+ * Everything is read from the git index (what will be committed), never the
+ * working tree, so a half-staged file is judged by its staged half. Offline,
+ * no telemetry. Findings use the standard shape, so ids match a full scan and
+ * penthera.suppress.json works here too.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, posix, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findSecretsInText, isSecretScanTarget, maskMatch } from "../whitebox/secrets.js";
+import { loadPolicy } from "../install/policy.js";
+import { loadRepoSuppressions } from "../memory/repo-suppress.js";
+import { findingId } from "../memory/views.js";
+import { fingerprintFinding } from "../audit-loop.js";
+import { globToRegExp, isAtLeast, SEVERITIES } from "./policy.js";
+
+export const HOOK_MARKER = "# penthera-hook";
+export const BACKUP_NAME = "pre-commit.pre-penthera";
+const MAX_BLOB_BYTES = 2 * 1024 * 1024;
+
+// ── git plumbing ──────────────────────────────────────────────────────────
+
+function git(cwd, args, opts = {}) {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024, ...opts });
+}
+
+export function repoRoot(cwd) {
+  try {
+    return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    throw new Error(`Not inside a git repository: ${cwd}`);
+  }
+}
+
+/** Paths added, copied, modified or renamed in the index (what this commit adds). */
+export function stagedFiles(root) {
+  return git(root, ["diff", "--cached", "--name-only", "-z", "--diff-filter=ACMR", "--no-renames"]).split("\0").filter(Boolean);
+}
+
+/** Read index blobs in one `git cat-file --batch` call. Returns Map(path → Buffer); large files are skipped. */
+export function readStaged(root, paths) {
+  const out = new Map();
+  const wanted = paths.filter((p) => !p.includes("\n"));
+  if (!wanted.length) return out;
+  const r = spawnSync("git", ["cat-file", "--batch"], { cwd: root, input: wanted.map((p) => `:${p}\n`).join(""), maxBuffer: 1024 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git cat-file failed: ${String(r.stderr).trim()}`);
+  const buf = r.stdout;
+  let pos = 0;
+  for (const p of wanted) {
+    const nl = buf.indexOf(10, pos);
+    if (nl === -1) break;
+    const header = buf.subarray(pos, nl).toString();
+    pos = nl + 1;
+    const m = /^\S+ (\w+) (\d+)$/.exec(header);
+    if (!m) continue; // "<name> missing"
+    const size = Number(m[2]);
+    if (m[1] === "blob" && size <= MAX_BLOB_BYTES) out.set(p, buf.subarray(pos, pos + size));
+    pos += size + 1;
+  }
+  return out;
+}
+
+// ── Checks ────────────────────────────────────────────────────────────────
+
+function lineOf(text, index) {
+  let n = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+function checkSecrets(files, blobs) {
+  const findings = [];
+  for (const path of files) {
+    if (!isSecretScanTarget(path)) continue;
+    const buf = blobs.get(path);
+    if (!buf || buf.subarray(0, 8192).includes(0)) continue;
+    const text = buf.toString("utf-8");
+    for (const hit of findSecretsInText(text)) {
+      // Same title/url/category/source as the repo scan, so finding ids match.
+      findings.push({
+        severity: hit.severity,
+        title: `${hit.name} in source`,
+        description: `Possible secret in \`${path}\`: \`${maskMatch(hit.match)}\``,
+        url: path,
+        line: lineOf(text, text.indexOf(hit.match)),
+        evidence: maskMatch(hit.match),
+        category: "secrets",
+        source: "secret-scan",
+      });
+    }
+  }
+  return findings;
+}
+
+const AGENT_FILES = new Set(["AGENTS.md", "CLAUDE.md", "CLAUDE.local.md", "GEMINI.md", ".cursorrules", ".windsurfrules", ".mcp.json", ".github/copilot-instructions.md", ".vscode/mcp.json"]);
+const AGENT_DIRS = [".claude/", ".cursor/", ".agents/", ".codex/", ".clinerules/", ".claude-plugin/", ".github/instructions/", "skills/", "plugins/"];
+
+/** Is this repo path agent configuration that `penthera agents` reads? */
+export function isAgentConfig(path) {
+  return AGENT_FILES.has(path) || AGENT_DIRS.some((d) => path.startsWith(d));
+}
+
+/**
+ * Agent rules on the staged view of the agent config. The whole agent config
+ * in the index is checked out to a temp folder (a skill is judged as a folder,
+ * not file by file); only findings that touch a staged path are kept.
+ */
+async function checkAgents(root, staged) {
+  const touched = staged.filter(isAgentConfig);
+  if (!touched.length) return { findings: [], files: 0 };
+  const all = git(root, ["ls-files", "-z", "--cached"]).split("\0").filter((p) => p && isAgentConfig(p));
+  const tmp = realpathSync(mkdtempSync(join(tmpdir(), "penthera-hook-")));
+  try {
+    const r = spawnSync("git", ["checkout-index", "-z", "--stdin", `--prefix=${tmp}/`], { cwd: root, input: all.join("\0") });
+    if (r.status !== 0) throw new Error(`git checkout-index failed: ${String(r.stderr).trim()}`);
+    const { scanAgents } = await import("../agents/index.js");
+    const result = await scanAgents(tmp, { lockPath: join(tmp, ".penthera-hook-no-lock") });
+    const relates = (url) => touched.some((s) => url === s || s.startsWith(`${url}/`) || url.startsWith(`${s}/`));
+    const findings = result.findings
+      .filter((f) => !String(f.templateId).startsWith("agents/lock-") && relates(f.url))
+      .map((f) => {
+        const m = /\(line (\d+)\)/.exec(f.description || "");
+        return m ? { ...f, line: Number(m[1]) } : f;
+      });
+    return { findings, files: touched.length };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const EMPTY_LOCK = { lockfileVersion: 3, packages: {} };
+
+/** Capability diff (and license policy) for each staged lockfile, against HEAD. */
+async function checkLockfiles(root, staged, blobs, { licensePolicy }) {
+  const locks = staged.filter((p) => ["package-lock.json", "npm-shrinkwrap.json"].includes(posix.basename(p)));
+  if (!locks.length) return { findings: [], files: 0 };
+  const { scanDeps } = await import("../deps/index.js");
+  const findings = [];
+  for (const path of locks) {
+    const buf = blobs.get(path);
+    if (!buf) continue;
+    let lock;
+    try { lock = JSON.parse(buf.toString("utf-8")); } catch (e) {
+      findings.push({ severity: "high", title: `${path} is not valid JSON`, description: e.message, url: path, category: "dependency-risk", source: "deps-scan" });
+      continue;
+    }
+    let baseLock = EMPTY_LOCK;
+    try { baseLock = JSON.parse(git(root, ["show", `HEAD:${path}`])); } catch { /* new lockfile or first commit */ }
+    const dir = posix.dirname(path);
+    const result = await scanDeps(join(root, dir), { lock, baseLock, baseLabel: "HEAD", changedOnly: true, licensePolicy });
+    const prefix = dir === "." ? "" : `${dir}/`;
+    for (const f of result.findings) findings.push({ ...f, url: f.url ? `${prefix}${f.url}` : path });
+  }
+  return { findings, files: locks.length };
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────
+
+function suppressedBy(entries, f) {
+  if (!entries.length) return null;
+  const id = findingId(f);
+  const fp = fingerprintFinding(f);
+  return entries.find((e) => e.id === id || e.fingerprint === fp) || null;
+}
+
+const bySeverity = (a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity) || String(a.url).localeCompare(String(b.url)) || (a.line || 0) - (b.line || 0);
+
+/**
+ * Check what is staged. Never writes to the repo.
+ * @param {string} cwd anywhere inside the repo
+ * @param {{ policyPath?: string, now?: string }} opts
+ * @returns {Promise<{ root, staged, checked, blocking, below, suppressed, blockOn, policyPath, warnings, duration }>}
+ */
+export async function runHook(cwd, opts = {}) {
+  const started = Date.now();
+  const root = repoRoot(cwd);
+  const { policy, path: policyPath } = loadPolicy(root, opts.policyPath || null);
+  const { blockOn, checks, ignore } = policy.hook;
+  const ignored = ignore.map(globToRegExp);
+  const staged = stagedFiles(root).filter((p) => !ignored.some((re) => re.test(p)));
+
+  const wantBlobs = staged.filter((p) => (checks.secrets && isSecretScanTarget(p)) || /(^|\/)(package-lock|npm-shrinkwrap)\.json$/.test(p));
+  const blobs = readStaged(root, wantBlobs);
+
+  const secrets = checks.secrets ? checkSecrets(staged, blobs) : [];
+  const agents = checks.agents ? await checkAgents(root, staged) : { findings: [], files: 0 };
+  const deps = checks.deps ? await checkLockfiles(root, staged, blobs, { licensePolicy: checks.licenses ? policy.licenses : null }) : { findings: [], files: 0 };
+
+  const sup = loadRepoSuppressions(root, { now: opts.now });
+  const all = [...secrets, ...agents.findings, ...deps.findings].map((f) => ({ ...f, id: findingId(f) }));
+  const suppressed = [];
+  const kept = [];
+  for (const f of all) {
+    const s = suppressedBy(sup.entries, f);
+    if (s) suppressed.push({ ...f, suppression: { reason: s.reason } });
+    else kept.push(f);
+  }
+  kept.sort(bySeverity);
+  return {
+    root,
+    staged: staged.length,
+    checked: { secrets: checks.secrets ? staged.filter(isSecretScanTarget).length : 0, agents: agents.files, lockfiles: deps.files },
+    blockOn,
+    policyPath,
+    blocking: kept.filter((f) => isAtLeast(f.severity, blockOn)),
+    below: kept.filter((f) => !isAtLeast(f.severity, blockOn)),
+    suppressed,
+    warnings: sup.warnings,
+    duration: Date.now() - started,
+  };
+}
+
+/** One short "how to fix" line per finding. */
+export function fixHint(f) {
+  if (f.category === "secrets") return "Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.";
+  if (f.category === "license") return `Replace ${f.package}, or add it to "allowPackages" in the licenses section of penthera.policy.json.`;
+  if (f.category === "dependency-risk") return `Review it before committing the lockfile: \`penthera deps --base HEAD -v\` shows the evidence.`;
+  const first = String(f.description || "").replace(/\s*\[[^\]]*\]$/, "").replace(/\s*\(line \d+\)/, "").split(/(?<=\.)\s/)[0];
+  return first || "See `penthera agents` for details.";
+}
+
+// ── Install / uninstall ───────────────────────────────────────────────────
+
+const BIN = fileURLToPath(new URL("../../bin/penthera.js", import.meta.url));
+const sq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+export function hookScript({ node = process.execPath, bin = BIN } = {}) {
+  return `#!/bin/sh
+${HOOK_MARKER}: pre-commit hook installed by \`penthera hook install\`.
+# Remove it with \`penthera hook uninstall\`, which restores any hook it replaced.
+# Skip it for one commit with \`git commit --no-verify\`.
+hook_dir=$(dirname "$0")
+if [ -x "$hook_dir/${BACKUP_NAME}" ]; then
+  "$hook_dir/${BACKUP_NAME}" "$@" || exit $?
+fi
+if [ -f ${sq(bin)} ] && [ -x ${sq(node)} ]; then
+  exec ${sq(node)} ${sq(bin)} hook run
+elif command -v penthera >/dev/null 2>&1; then
+  exec penthera hook run
+fi
+echo "penthera: not found, pre-commit check skipped (npm install -g penthera, then penthera hook install)" >&2
+exit 0
+`;
+}
+
+/** Where git looks for hooks (honours core.hooksPath and worktrees). */
+export function hooksDir(root) {
+  return resolve(root, git(root, ["rev-parse", "--git-path", "hooks"]).trim());
+}
+
+function hooksPathSetting(root) {
+  try { return git(root, ["config", "--get", "core.hooksPath"]).trim() || null; } catch { return null; }
+}
+
+const isOurs = (path) => existsSync(path) && readFileSync(path, "utf-8").includes(HOOK_MARKER);
+
+/**
+ * Write .git/hooks/pre-commit. An existing hook that is not ours is kept as
+ * pre-commit.pre-penthera and runs first.
+ * @returns {{ path, chained: string|null, updated: boolean }}
+ */
+export function installHook(cwd, { force = false, script = hookScript() } = {}) {
+  const root = repoRoot(cwd);
+  const custom = hooksPathSetting(root);
+  if (custom && !force) {
+    const err = new Error(`core.hooksPath is set to "${custom}" (husky, lefthook or similar manage hooks here). Add \`penthera hook run\` to that tool's pre-commit config instead, or rerun with --force to write ${join(custom, "pre-commit")}.`);
+    err.code = "HOOKS_PATH";
+    throw err;
+  }
+  const dir = hooksDir(root);
+  const path = join(dir, "pre-commit");
+  const backup = join(dir, BACKUP_NAME);
+  let updated = false;
+  if (existsSync(path)) {
+    if (isOurs(path)) updated = true;
+    else if (existsSync(backup)) throw new Error(`Both ${path} and ${backup} exist. Merge them by hand, then run \`penthera hook install\` again.`);
+    else renameSync(path, backup);
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, script);
+  chmodSync(path, 0o755);
+  return { path, chained: existsSync(backup) ? backup : null, updated };
+}
+
+/**
+ * Remove our hook and put back the one it replaced.
+ * @returns {{ path, removed: boolean, restored: string|null }}
+ */
+export function uninstallHook(cwd) {
+  const root = repoRoot(cwd);
+  const dir = hooksDir(root);
+  const path = join(dir, "pre-commit");
+  const backup = join(dir, BACKUP_NAME);
+  if (!existsSync(path)) return { path, removed: false, restored: null };
+  if (!isOurs(path)) throw new Error(`${path} was not installed by penthera; left untouched.`);
+  unlinkSync(path);
+  if (existsSync(backup)) {
+    renameSync(backup, path);
+    return { path, removed: true, restored: path };
+  }
+  return { path, removed: true, restored: null };
+}

package/lib/hook/policy.js

@@ -0,0 +1,62 @@
+/**
+ * The `hook` section of penthera.policy.json: what `penthera hook run` checks
+ * and what blocks a commit.
+ *
+ *   "hook": {
+ *     "blockOn": "high",                 // lowest severity that blocks: critical | high | medium | low
+ *     "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true },
+ *     "ignore": ["tests/fixtures/**"]    // staged paths the hook skips (globs)
+ *   }
+ */
+export const SEVERITIES = ["critical", "high", "medium", "low", "info"];
+const CHECKS = ["secrets", "agents", "deps", "licenses"];
+
+export const DEFAULT_HOOK_POLICY = Object.freeze({
+  blockOn: "high",
+  checks: Object.freeze(Object.fromEntries(CHECKS.map((c) => [c, true]))),
+  ignore: Object.freeze([]),
+});
+
+export function normalizeHookPolicy(raw, label = "hook") {
+  if (raw == null) return { ...DEFAULT_HOOK_POLICY, checks: { ...DEFAULT_HOOK_POLICY.checks }, ignore: [] };
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected an object`);
+  const extra = Object.keys(raw).filter((k) => !["blockOn", "checks", "ignore"].includes(k));
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected blockOn, checks, ignore)`);
+  const blockOn = raw.blockOn ?? "high";
+  if (!SEVERITIES.slice(0, 4).includes(blockOn)) throw new Error(`${label}: "blockOn" must be one of critical, high, medium, low`);
+  const checks = { ...DEFAULT_HOOK_POLICY.checks };
+  if (raw.checks != null) {
+    if (typeof raw.checks !== "object" || Array.isArray(raw.checks)) throw new Error(`${label}: "checks" must be an object`);
+    for (const [k, v] of Object.entries(raw.checks)) {
+      if (!CHECKS.includes(k)) throw new Error(`${label}: unknown check "${k}" (known: ${CHECKS.join(", ")})`);
+      if (typeof v !== "boolean") throw new Error(`${label}: checks.${k} must be true or false`);
+      checks[k] = v;
+    }
+  }
+  const ignore = raw.ignore ?? [];
+  if (!Array.isArray(ignore) || ignore.some((x) => typeof x !== "string" || !x.trim())) throw new Error(`${label}: "ignore" must be an array of path globs`);
+  return { blockOn, checks, ignore: ignore.map((x) => x.trim()) };
+}
+
+/** Git-style path glob: `**` crosses folders, `*` and `?` stay inside one; a bare name matches at any depth. */
+export function globToRegExp(glob) {
+  let g = glob.replace(/^\.\//, "");
+  if (!g.includes("/")) g = `**/${g}`;
+  if (g.endsWith("/")) g += "**";
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const ch = g[i];
+    if (ch === "*" && g[i + 1] === "*") {
+      i++;
+      if (g[i + 1] === "/") { i++; re += "(?:.*/)?"; } else re += ".*";
+    } else if (ch === "*") re += "[^/]*";
+    else if (ch === "?") re += "[^/]";
+    else re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function isAtLeast(severity, threshold) {
+  const s = SEVERITIES.indexOf(severity);
+  return s !== -1 && s <= SEVERITIES.indexOf(threshold);
+}