penthera 1.4.0 → 1.6.0

package/skills/penthera/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: penthera
 description: >
-  The routine work of a security team, run locally with the Penthera CLI. Scans the
+  Open-source security for the apps and AI systems the user ships, run locally with
+  the Penthera CLI. Scans the
   user's own live URL and repo (TLS, headers, auth, OpenAPI, secrets incl. AI keys,
-  opt-in injection); checks npm dependencies offline ("is this dependency safe?",
-  "what changed in my deps?", "install X safely"); audits AI tooling ("audit my MCP
-  servers / skills / hooks", "check this skill before I install it"); fixes findings
+  opt-in injection); checks npm and Python dependencies offline ("is this dependency safe?",
+  "what changed in my deps?", "install X safely", "any AGPL in our deps?"); blocks
+  secrets and risky agent config before they are committed ("add a pre-commit hook");
+  audits AI tooling ("audit my MCP servers / skills / hooks", "check this skill
+  before I install it"); fixes findings
   on a local branch and re-scans to verify ("scan and fix my app"); and writes
   reports and evidence ("report for my auditor / manager", NIS2, SARIF, baseline
   diff). Use when the user asks to scan, audit, harden, fix, or review the security of
@@ -16,7 +19,7 @@ compatibility: Node.js 22+, network access to target, Penthera CLI (npm link or
 allowed-tools: "Bash(node:*) Bash(npm:*) Bash(penthera:*) Read Write Edit"
 metadata:
   author: danoszz
-  version: 1.4.0
+  version: 1.6.0
   category: security
 ---
 
@@ -68,6 +71,8 @@ All examples below use `penthera`; substitute `node bin/penthera.js` when needed
 | Scan repo only (secrets, routes) | `penthera --repo . -o reports/repo-scan.json` |
 | Is this dependency safe? / what changed in my deps? | `penthera deps` or `penthera deps --base origin/main` (see **Dependency risk scan**) |
 | Install X safely / is it safe to add this package? | `penthera install <pkg> --dry-run`, then `penthera install <pkg>` (see **Install firewall**) |
+| Are our dependency licenses OK? / any AGPL? | `penthera deps --license-policy permissive` (see **License policy**) |
+| Add a pre-commit hook / stop me committing secrets | `penthera hook install` (see **Pre-commit hook**) |
 | URL + source combined | `penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif` |
 | Scan and fix my app | **Workflow 4**: `penthera agent --loop` (scan, fix, verify, commit locally), then hand-fix what is left from [references/remediation.md](references/remediation.md) |
 | Compare to previous scan | `penthera <url> -o reports/scan.json --baseline reports/previous.json` |
@@ -75,6 +80,7 @@ All examples below use `penthera`; substitute `node bin/penthera.js` when needed
 | macOS machine audit | `penthera --machine` |
 | Audit MCP servers, skills, hooks, agent config | `penthera agents . --home -o reports/agents.json` (see **Workflow 6**) |
 | Report for my auditor / manager / developers | `--audience auditor\|owner\|developer --markdown reports/<who>.md`, or `--evidence <dir>` (see **Workflow 7**) |
+| Open the penthera dashboard / show me my security posture | `penthera ui --open` (see **Dashboard**) |
 
 ## Default safe behavior
 
@@ -265,19 +271,20 @@ Summarize secret findings; remind user to rotate any exposed credentials.
 
 ## Dependency risk scan
 
-**Triggers:** "is this dependency safe?", "what changed in my deps?", "review this lockfile change / dependency upgrade", "does this package have install scripts?", "is this a typosquat?"
+**Triggers:** "is this dependency safe?", "what changed in my deps?", "review this lockfile change / dependency upgrade", "does this package have install scripts?", "is this a typosquat?", "is this pip / PyPI package safe?", "check my requirements.txt / uv.lock / poetry.lock / venv", "does this package have a .pth file or setup.py hook?"
 
-Offline and read-only: it reads `package-lock.json` and `node_modules`, runs no package code, and sends nothing anywhere, so no target authorization is needed. It never installs anything; if `node_modules` is missing, tell the user to run `npm ci --ignore-scripts` first.
+Offline and read-only: it reads `package-lock.json` and `node_modules`, or for Python `uv.lock` / `poetry.lock` / `pdm.lock` / `Pipfile.lock` / `requirements*.txt` and the `.venv` (or `--venv <path>`), runs no package code (not even pip), and sends nothing anywhere, so no target authorization is needed. It never installs anything; if `node_modules` is missing, tell the user to run `npm ci --ignore-scripts` first. For Python without a venv, suggest `uv sync` or `pip install -r requirements.txt` into a `.venv` (wheels only, `--only-binary :all:`, if they are wary of setup.py).
 
 ```bash
 penthera deps                              # what every installed package can do
 penthera deps --base origin/main           # capability diff vs the lockfile on main
 penthera deps --diff ../base-checkout      # diff vs another installed tree
 penthera deps --prod -o reports/deps.json  # skip devDependencies, write JSON + Markdown
+penthera deps --venv path/to/venv          # Python: a virtualenv that is not .venv/venv
 ```
 
 1. Lead with the diff: which packages are **new** or **gained** capabilities (network, shell, install script, whole environment, dynamic code), each with its `file:line` evidence.
-2. Then critical/high risk signals (AI-config writes, AI CLI invocation, GitHub token harvesting, obfuscation, env exfiltration). Open the evidence file and read the lines before calling anything malicious: a capability is what code *can* do, not a verdict.
+2. Then critical/high risk signals (AI-config writes, AI CLI invocation, GitHub token harvesting, obfuscation, env exfiltration; for Python also `.pth` startup hooks that run risky code, unowned `.pth` files, files changed since install). Open the evidence file and read the lines before calling anything malicious: a capability is what code *can* do, not a verdict.
 3. If old versions were "not compared", say so; suggest installing the base tree and passing it to `--diff`.
 4. `--online` is the only network use (npm registry metadata: publish age, publisher change, deprecation). Only add it if the user agrees.
 
@@ -296,6 +303,46 @@ penthera install <pkg> --yes              # install only if nothing breaches the
 2. Exit 1 means blocked: the project is untouched. Never add a package to `allow` in `penthera.policy.json`, or approve install scripts, without the user saying so after seeing the evidence.
 3. If the user approves, run `penthera install <pkg>` in their terminal (the prompt is theirs to answer), or `--yes` after they have added an `allow` entry.
 
+## License policy
+
+**Triggers:** "are our licenses OK?", "do we ship anything GPL / AGPL?", "license check before release", "add a license policy"
+
+```bash
+penthera deps --license-policy permissive --json   # presets: permissive, weak-copyleft-ok, no-agpl
+```
+
+1. Findings have category `license`: a breach or `UNLICENSED` is high; a missing, custom or non-SPDX license is medium.
+2. Without the flag, the `licenses` section of `penthera.policy.json` applies if present. Never add packages to `allowPackages` without the user's say-so; that is a legal decision, not a technical one.
+
+## Pre-commit hook
+
+**Triggers:** "add a pre-commit hook", "stop me committing secrets / API keys", "check before I commit", "block bad MCP config in commits"
+
+```bash
+penthera hook install   # .git/hooks/pre-commit; an existing hook is kept and runs first
+penthera hook run       # check what is staged now (exit 1 = blocked)
+```
+
+1. It checks staged content only: secrets and AI provider keys, `penthera agents` rules on staged agent config, and the capability diff plus license policy when `package-lock.json` is staged. Blocks on high and critical by default (`hook.blockOn` in `penthera.policy.json`).
+2. If `core.hooksPath` is set (husky, lefthook), do not pass `--force`; add `npx --no-install penthera hook run` to that tool's pre-commit config instead.
+3. Never suggest `git commit --no-verify` to get past a finding unless the user asks how to skip it; suggest fixing it or a `penthera.suppress.json` entry with a reason.
+
+## Dashboard
+
+**Triggers:** "open the penthera dashboard", "show me the dashboard", "show my security posture", "run the agent from the UI".
+
+```bash
+penthera ui --open                                   # this folder, reports in ./reports
+penthera ui --project <dir> --reports <dir> --open   # other folders
+penthera ui --demo --open                            # fake data, to look around first
+```
+
+1. Start it in the user's terminal (it keeps running until Ctrl-C). It binds 127.0.0.1 on a random port and prints a one-time URL: tell the user to open that link (or pass `--open`). Never paste the token anywhere else.
+2. It reads only the `--project` folders, the reports folder and `~/.penthera`. If the screens are empty, scan with `-o reports/<name>.json` first (and `penthera deps -o reports/deps.json`, `penthera agents . -o reports/agents.json`).
+3. The Run screen starts scans, dependency checks, AI tooling audits and the fix loop. The fix loop is `penthera agent --loop` with the same rules: the user approves every diff in the page, nothing is pushed. A URL that is not on this machine needs its hostname typed to confirm; the authorization gate above still applies.
+
+See [docs/dashboard.md](../../docs/dashboard.md).
+
 ## Examples
 
 **Example 1: Localhost quick check**

package/src/cli/deps.js

@@ -2,14 +2,45 @@
  * `penthera deps [path]`: CLI runner for the dependency capability scan.
  */
 import { resolve } from "node:path";
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+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";
+import { prepareReportOptions, customReport, writeEvidence } from "./report-outputs.js";
+import { compareWithBaseline } from "./baseline.js";
 
-export const DEPS_FLAGS = ["diff", "base", "online", "pr-comment", "prod"];
+export const DEPS_FLAGS = ["diff", "base", "online", "pr-comment", "prod", "license-policy", "venv"];
+
+/**
+ * Scan-command flags that mean nothing for a dependency scan. Rejected rather
+ * than ignored: a flag that silently does nothing reads as a check that ran.
+ * (--audience, --report-template, --evidence, --sign-key and --baseline work.)
+ */
+export const DEPS_UNSUPPORTED = [
+  "memory", "framework", "readiness", "assessment", "questionnaire", "policy-pack", "org", "history",
+  "sbom", "aibom", "repo", "api-root", "recon", "deep", "fuzz", "nuclei", "templates", "adaptive", "all",
+  "machine", "home", "pin", "profile", "auth-cookie", "auth-bearer",
+];
+
+/**
+ * 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) {
@@ -20,11 +51,23 @@ export async function runDeps(args, opts, { version }) {
     printError("Use --diff <lockfile|dir> or --base <git-ref>, not both.");
     process.exit(2);
   }
+  const unsupported = DEPS_UNSUPPORTED.filter((f) => opts[f] !== undefined && opts[f] !== false);
+  if (unsupported.length) {
+    printError(`${unsupported.map((f) => `--${f}`).join(", ")} ${unsupported.length > 1 ? "do" : "does"} not apply to \`penthera deps\` (URL and --repo scans only). Deps supports --diff, --base, --online, --prod, --venv, --pr-comment, --license-policy, -o, --markdown, --sarif, --audience, --report-template, --evidence, --sign-key and --baseline.`);
+    process.exit(2);
+  }
   const root = resolve(args[0] || ".");
   if (!existsSync(root)) {
     printError(`Path not found: ${root}`);
     process.exit(2);
   }
+  let reportCtx;
+  try {
+    reportCtx = prepareReportOptions(opts);
+  } catch (e) {
+    printError(e.message);
+    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" +
@@ -34,11 +77,14 @@ export async function runDeps(args, opts, { version }) {
   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,
+      venv: opts.venv || null,
       onPhase: createProgress(quiet),
     });
   } catch (e) {
@@ -49,11 +95,30 @@ export async function runDeps(args, opts, { version }) {
   const merged = mergeResults([result]);
   merged.actionPlan = buildActionPlan(merged.findings);
 
+  let baselineStats = null;
+  if (opts.baseline) {
+    let comparison;
+    try {
+      comparison = compareWithBaseline(merged.findings, resolve(opts.baseline));
+    } catch (e) {
+      printError(`--baseline: ${e.message}`);
+      process.exit(2);
+    }
+    baselineStats = comparison.stats;
+    if (opts.quiet) merged.findings = comparison.newFindings;
+    else if (!opts.json) {
+      process.stderr.write(`\n  Baseline: ${comparison.stats.newCount} new, ${comparison.stats.resolvedCount} resolved, ${comparison.stats.unchangedCount} unchanged\n\n`);
+    }
+  }
+  const custom = customReport(merged, opts, { version, template: reportCtx.template });
+
   if (opts.json) console.log(JSON.stringify(merged, null, 2));
+  else if (custom && !opts.markdown) process.stdout.write(custom);
   else if (opts.quiet) printFindings(merged.findings);
   else printReport(merged, { verbose: opts.verbose });
 
-  const mdOpts = { version };
+  const footer = !opts["no-footer"];
+  const mdOpts = { version, baseline: baselineStats, footer };
   const note = (s) => { if (!quiet) process.stderr.write(s); };
   if (opts.output) {
     writeJsonReport(merged, opts.output);
@@ -62,7 +127,8 @@ export async function runDeps(args, opts, { version }) {
     note(`  JSON report    ${opts.output}\n  Markdown report ${md}\n`);
   }
   if (opts.markdown) {
-    writeMarkdownReport(merged, opts.markdown, mdOpts);
+    if (custom) writeFileSync(resolve(opts.markdown), custom);
+    else writeMarkdownReport(merged, opts.markdown, mdOpts);
     note(`  Markdown report ${opts.markdown}\n`);
   }
   if (opts.sarif) {
@@ -73,10 +139,19 @@ export async function runDeps(args, opts, { version }) {
     const { formatPrComment } = await import("../../lib/deps/report.js");
     const path = resolve(opts["pr-comment"]);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, formatPrComment(merged, { version }));
+    writeFileSync(path, formatPrComment(merged, { version, footer }));
     note(`  PR comment     ${opts["pr-comment"]}\n`);
   }
-  if (opts.output || opts.markdown || opts.sarif || opts["pr-comment"]) note("\n");
+  if (opts.evidence) {
+    try {
+      const bundle = writeEvidence(merged, { ...opts, repo: root }, { version, template: reportCtx.template, mdOpts, sbom: null, argv: process.argv.slice(2) });
+      note(`  Evidence bundle ${bundle.manifest.artifacts.length} files${bundle.signed ? ", signed" : ""} → ${opts.evidence}/ (penthera evidence verify ${opts.evidence})\n`);
+    } catch (e) {
+      printError(`Could not write the evidence bundle: ${e.message}`);
+      process.exit(2);
+    }
+  }
+  if (opts.output || opts.markdown || opts.sarif || opts["pr-comment"] || opts.evidence) 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");

package/src/cli/evidence.js

@@ -1,5 +1,5 @@
 /**
- * `penthera evidence verify <dir> [--allowed-signers <file>] [--json]`
+ * `penthera evidence verify <dir> [--allowed-signers <file>] [--require-signature] [--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
@@ -9,12 +9,16 @@ import { parseArgs } from "node:util";
 import { verifyEvidence } from "../report/evidence.js";
 
 const HELP = `
-  penthera evidence verify <dir> [--allowed-signers <file>] [--json]
+  penthera evidence verify <dir> [--allowed-signers <file>] [--require-signature] [--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.
 
+  A signed bundle only verifies with --allowed-signers (a valid signature by
+  an unknown key proves nothing). An unsigned bundle passes with an UNSIGNED
+  warning; --require-signature makes it fail.
+
   Exit codes: 0 verified, 1 verification failed, 2 usage error.
   See docs/evidence.md.
 `;
@@ -27,6 +31,7 @@ export function runEvidence(argv, { out = process.stdout } = {}) {
       allowPositionals: true,
       options: {
         "allowed-signers": { type: "string" },
+        "require-signature": { type: "boolean", default: false },
         json: { type: "boolean", default: false },
         help: { type: "boolean", short: "h", default: false },
       },
@@ -41,7 +46,11 @@ export function runEvidence(argv, { out = process.stdout } = {}) {
     return values.help ? 0 : 2;
   }
 
-  const r = verifyEvidence(positionals[1], { allowedSigners: values["allowed-signers"] || null });
+  if (values["require-signature"] && !values["allowed-signers"]) {
+    process.stderr.write(`  --require-signature needs --allowed-signers <file>: a signature is only worth something against keys you trust.\n${HELP}`);
+    return 2;
+  }
+  const r = verifyEvidence(positionals[1], { allowedSigners: values["allowed-signers"] || null, requireSignature: values["require-signature"] });
   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");
@@ -62,6 +71,7 @@ export function runEvidence(argv, { out = process.stdout } = {}) {
     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`);
+  for (const w of r.warnings || []) process.stderr.write(`\n  WARNING  ${w}\n`);
+  out.write(r.ok ? `\n  Verified: every artifact matches the manifest${r.signature?.status === "valid" ? `, signed by ${r.signature.principal}` : " (UNSIGNED)"}.\n\n` : `\n  NOT VERIFIED:\n${r.problems.map((p) => `    - ${p}\n`).join("")}\n`);
   return r.ok ? 0 : 1;
 }

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;
+}

package/src/cli/install.js

@@ -3,7 +3,7 @@
  *
  * 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
+ * then runs `npm ci` on the reviewed lockfile. Exit codes: 0 installed (or a clean
  * --dry-run), 1 blocked or aborted (project untouched), 2 error.
  */
 import { parseArgs } from "node:util";
@@ -30,6 +30,7 @@ const HELP = `
     -D, --save-dev         Save as devDependencies
     -E, --save-exact       Save exact versions
         --offline          npm resolves from its cache only (no registry traffic at all)
+        --allow-non-registry  Accept git and tarball-URL packages (refused by default)
         --json             Print the plan as JSON
     -v, --verbose          Show more evidence per capability
     -h, --help             Show this help
@@ -38,13 +39,17 @@ const HELP = `
     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.
+    Nothing in your project changes until you approve. Then \`npm ci\` installs
+    exactly the reviewed lockfile. Approved install scripts run; otherwise the
+    install uses --ignore-scripts. A package Penthera could not read is held for
+    approval whatever the policy says, and one whose lockfile claims an install
+    script the scan did not find is always refused.
 
   ${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"] }
+    "script-mismatch" is always denied and "unscanned" always needs approval.
     The requireApproval list above is the default.
 `;
 
@@ -70,6 +75,7 @@ function printPlan(plan, { policyPath, verbose }) {
       : 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.unscanned) L.push(`      ${red("not scanned")}: ${i.unscanned}`);
     if (i.flags.includes("install-scripts")) {
       for (const [hook, cmd] of Object.entries(i.installScripts || {})) {
         const was = i.previousInstallScripts?.[hook];
@@ -120,6 +126,7 @@ export async function runInstall(argv) {
         "save-dev": { type: "boolean", short: "D", default: false },
         "save-exact": { type: "boolean", short: "E", default: false },
         offline: { type: "boolean", default: false },
+        "allow-non-registry": { type: "boolean", default: false },
         json: { type: "boolean", default: false },
         verbose: { type: "boolean", short: "v", default: false },
         help: { type: "boolean", short: "h", default: false },
@@ -164,6 +171,7 @@ export async function runInstall(argv) {
       saveDev: opts["save-dev"],
       saveExact: opts["save-exact"],
       offline: opts.offline,
+      allowNonRegistry: opts["allow-non-registry"],
       onPhase: createProgress(json),
     });
   } catch (e) {
@@ -195,7 +203,8 @@ export async function runInstall(argv) {
       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;
+    // A package that could not be read may have install scripts nobody saw.
+    const withScripts = scripts.length > 0 || needsApproval.some((i) => i.approval.includes("unscanned"));
     await initPrompt();
     const answer = (await ask(withScripts
       ? `  Install anyway? [y]es, run the install scripts / [s]kip scripts / [N]o: `
@@ -209,7 +218,7 @@ export async function runInstall(argv) {
     }
   }
 
-  out(`\n  ${dim("▸")} npm install${runScripts ? "" : " --ignore-scripts"} ${dim("(installs the reviewed lockfile)")}\n`);
+  out(`\n  ${dim("▸")} npm ci${runScripts ? "" : " --ignore-scripts"} ${dim("(installs exactly the reviewed lockfile)")}\n`);
   let applied;
   try {
     applied = await applyInstall(plan, { runScripts, offline: opts.offline });

package/src/cli/report-outputs.js

@@ -13,6 +13,7 @@ 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";
+import { footerLines } from "../report/footer.js";
 
 /** Validate the report flags. Returns { template } or throws with a user-facing message. */
 export function prepareReportOptions(opts) {
@@ -34,7 +35,7 @@ export function prepareReportOptions(opts) {
 /** 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 });
+  if (opts.audience) return formatAudienceReport(result, opts.audience, { version, footer: !opts["no-footer"] });
   return null;
 }
 
@@ -43,11 +44,13 @@ export function customReport(result, opts, { version, template }) {
  * 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 footer = !opts["no-footer"];
   const artifacts = [
+    { path: "README.md", kind: "readme", content: evidenceReadme(result, { version, footer }) },
     { 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 }) })),
+    ...AUDIENCES.map((a) => ({ path: `report-${a}.md`, kind: `audience:${a}`, content: formatAudienceReport(result, a, { version, footer }) })),
   ];
   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) });
@@ -70,3 +73,23 @@ export function writeEvidence(result, opts, { version, template, mdOpts, sbom, a
     signKey: opts["sign-key"] || null,
   });
 }
+
+/** README.md at the root of an evidence bundle: what is in it and how to check it. */
+export function evidenceReadme(result, { version, footer = true } = {}) {
+  return [
+    "# Penthera evidence bundle",
+    "",
+    `Target: \`${String(result.target || "unknown").replace(/`/g, "")}\` · Penthera v${version}`,
+    "",
+    "- `manifest.json` lists every file with its SHA-256; `manifest.json.sig` is its signature when the bundle was signed.",
+    "- `report.json` and `report.sarif` are the machine-readable results; `report.md` and `report-<audience>.md` are for people.",
+    "",
+    "Check that nothing changed since the bundle was written:",
+    "",
+    "```",
+    "penthera evidence verify <this-dir> --allowed-signers <file>",
+    "```",
+    "",
+    ...footerLines({ footer }),
+  ].join("\n");
+}