penthera 1.5.0 → 1.6.0

package/src/cli/deps.js

@@ -8,8 +8,21 @@ 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", "license-policy"];
+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
@@ -38,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" +
@@ -59,6 +84,7 @@ export async function runDeps(args, opts, { version }) {
       base: opts.base || null,
       online: !!opts.online,
       prod: !!opts.prod,
+      venv: opts.venv || null,
       onPhase: createProgress(quiet),
     });
   } catch (e) {
@@ -69,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);
@@ -82,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) {
@@ -93,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/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");
+}

package/src/cli/ui.js

@@ -0,0 +1,89 @@
+/**
+ * `penthera ui [--port 0] [--open] [--project <dir>]... [--reports <dir>] [--demo]`
+ *
+ * Starts the local dashboard on 127.0.0.1 and prints a one-time URL. See
+ * docs/dashboard.md for the security model.
+ */
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { bold, dim, red, green } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera ui")}: the local dashboard, on 127.0.0.1 only
+
+  ${dim("Usage")}
+    $ penthera ui [--open] [--port <n>] [--project <dir>]... [--reports <dir>]
+    $ penthera ui --demo          Realistic fake data, for a first look or screenshots
+
+  ${dim("Options")}
+        --port <n>          Port to listen on (default: 0, a random free port)
+        --open              Open the one-time URL in your browser
+        --project <dir>     Folder the dashboard may read and run the agent loop in
+                            (repeatable; default: the current folder)
+        --reports <dir>     Report JSON folder (default: <first project>/reports)
+        --demo              Seed fake data; nothing is read from disk
+    -h, --help              Show this help
+
+  The URL holds a one-time token. Opening it sets a session cookie; the token
+  then stops working. Nothing outside the project folders and ~/.penthera is
+  read, and the server never contacts the network. Ctrl-C stops it.
+`;
+
+function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch { /* the URL is printed anyway */ }
+}
+
+export async function runUi(argv, { version }) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: false,
+      options: {
+        port: { type: "string", default: "0" },
+        open: { type: "boolean", default: false },
+        project: { type: "string", multiple: true },
+        reports: { type: "string" },
+        demo: { type: "boolean", default: false },
+        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) { console.log(HELP); return 0; }
+  const port = Number(opts.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    process.stderr.write(`  ${red("Error")} --port must be 0-65535\n`);
+    return 2;
+  }
+
+  const { startUiServer } = await import("../ui/server.js");
+  let ui;
+  try {
+    ui = await startUiServer({ port, projects: opts.project, reportsDir: opts.reports, demo: opts.demo, version });
+  } catch (e) {
+    process.stderr.write(`  ${red("Not started")} ${e.message}\n`);
+    return 2;
+  }
+
+  process.stdout.write(`\n  ${bold("penthera ui")}${opts.demo ? dim("  (demo data)") : ""}\n`);
+  process.stdout.write(`  ${green(ui.url)}\n`);
+  process.stdout.write(dim(`  one-time link: it signs this browser in once, then stops working\n`));
+  process.stdout.write(dim(`  listening on 127.0.0.1:${ui.port} only. Ctrl-C to stop\n\n`));
+  if (opts.open) openBrowser(ui.url);
+
+  await new Promise((resolve) => {
+    const stop = () => { process.stdout.write("\n  Stopped.\n"); ui.close().then(resolve); };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  return 0;
+}

package/src/cli.js

@@ -59,12 +59,14 @@ const HELP = `
     $ penthera --repo <path>         Scan a local repo (white-box)
     $ penthera <url> --repo <path>   Full scan (both)
     $ penthera agents [path]         Audit AI agent config: skills, MCP, hooks (offline)
-    $ penthera deps [path]           What your npm dependencies can do (offline)
+    $ penthera deps [path]           What your npm and Python dependencies can do (offline)
     $ penthera install <pkg...>      Check what an npm install adds before anything runs
+    $ penthera hook install          Pre-commit hook: staged secrets, agent config, lockfiles
     $ penthera memory show|verify|forget  Local learning store (never leaves the machine)
     $ penthera fix --plan            Plan local fix recipes (penthera fix --help)
     $ penthera evidence verify <dir> Check an evidence bundle's hashes and signature
     $ penthera agent --loop          Scan, fix, verify, learn; local commits only (--help)
+    $ penthera ui [--open] [--demo]  Local dashboard on 127.0.0.1 (penthera ui --help)
 
   ${dim("Scan modes")}
         --profile <name>        quick | standard | deep (default: standard)
@@ -79,17 +81,19 @@ const HELP = `
         --all                   Enable all modes (recon + deep + fuzz)
         --machine               macOS machine audit (keyloggers, trojans, rootkits)
         --offline               Contact only the scan target: no recon sources, no
-                               Retire.js download (uses the vendored snapshot)
+                               Retire.js download (uses the vendored snapshot),
+                               no DNS lookups for SPF/DMARC
 
   ${dim("Agents mode")}  ${dim("(penthera agents [path], offline, read-only)")}
         --home                  Also audit ~/.claude, ~/.cursor and Claude Desktop config
         --pin                   Write penthera.lock (SHA-256 of skills, MCP servers, hooks)
 
-  ${dim("Deps mode")}  ${dim("(penthera deps [path], reads package-lock.json + node_modules, offline)")}
+  ${dim("Deps mode")}  ${dim("(penthera deps [path], reads package-lock.json, Python lockfiles or a .venv, offline)")}
         --diff <lock|dir>       Capability diff against an old lockfile or installed tree
         --base <git-ref>        Capability diff against the lockfile at a git ref
         --online                Also check npm registry metadata (the only network use)
-        --prod                  Skip devDependencies
+        --prod                  Skip dev dependencies
+        --venv <path>           Python virtualenv to read (default: .venv or venv)
         --pr-comment <file>     Write a short Markdown capability diff for a PR comment
         --license-policy <p>    permissive | weak-copyleft-ok | no-agpl, or a policy file
 
@@ -108,6 +112,7 @@ const HELP = `
         --audience <who>    developer | owner | auditor report (for --markdown or stdout)
         --report-template <file.md>  Your own Markdown template ({{summary.critical}}, {{#each findings}})
         --evidence <dir>    Evidence bundle: all reports + manifest.json with SHA-256s
+        --no-footer         Leave the one-line "Checked by Penthera" footer off Markdown output
         --sign-key <key>    Sign the bundle's manifest with an SSH key (ssh-keygen -Y sign)
         --baseline <file>   Compare against previous JSON report
         --framework <name>  Add a compliance mapping to reports (nis2)
@@ -191,6 +196,11 @@ export async function run() {
     return runFix(process.argv.slice(3));
   }
 
+  if (process.argv[2] === "ui") {
+    const { runUi } = await import("./cli/ui.js");
+    process.exit(await runUi(process.argv.slice(3), { version: pkg.version }));
+  }
+
   if (process.argv[2] === "agent") {
     const { runAgent } = await import("./cli/agent.js");
     process.exit(await runAgent(process.argv.slice(3)));
@@ -207,6 +217,7 @@ export async function run() {
         markdown:    { type: "string" },
         sarif:       { type: "string" },
         audience:    { type: "string" },
+        "no-footer": { type: "boolean", default: false },
         "report-template": { type: "string" },
         evidence:    { type: "string" },
         "sign-key":  { type: "string" },
@@ -233,6 +244,7 @@ export async function run() {
         "pr-comment": { type: "string" },
         prod:        { type: "boolean", default: false },
         "license-policy": { type: "string" },
+        venv:        { type: "string" },
         profile:     { type: "string" },
         "auth-cookie": { type: "string" },
         "auth-bearer": { type: "string" },
@@ -371,8 +383,8 @@ export async function run() {
     await runDeps(positionals.slice(1), opts, { version: pkg.version });
     return;
   }
-  if (opts.diff || opts.base || opts.online || opts["pr-comment"] || opts.prod || opts["license-policy"]) {
-    printError("--diff, --base, --online, --prod, --pr-comment and --license-policy only apply to `penthera deps`.");
+  if (opts.diff || opts.base || opts.online || opts["pr-comment"] || opts.prod || opts["license-policy"] || opts.venv) {
+    printError("--diff, --base, --online, --prod, --pr-comment, --license-policy and --venv only apply to `penthera deps`.");
     process.exit(2);
   }
 
@@ -582,7 +594,7 @@ export async function run() {
     }
   }
 
-  const mdOpts = { version: pkg.version, baseline: baselineStats };
+  const mdOpts = { version: pkg.version, baseline: baselineStats, footer: !opts["no-footer"] };
   const custom = customReport(merged, opts, { version: pkg.version, template: reportCtx.template });
 
   // Output

package/src/report/audience.js

@@ -8,6 +8,8 @@
  *              probes, suppressions (who and why), loop timeline, NIS2 and OWASP
  */
 import { buildReportModel, CONFIDENCE_LABELS } from "./model.js";
+import { mdInline } from "./md-escape.js";
+import { footerLines } from "./footer.js";
 
 export const AUDIENCES = ["developer", "owner", "auditor"];
 
@@ -24,10 +26,7 @@ const NIS2_STATUS = {
 };
 
 /** Inline text: one line, no table breaks, no raw HTML. */
-function md(s) {
-  return String(s ?? "").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\r?\n|\r/g, " ")
-    .replace(/\\/g, "\\\\").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "\\|");
-}
+const md = mdInline;
 /** Penthera's own remediation text (lib/remediation): may hold code spans, so only fold lines. */
 function prose(s) {
   return String(s ?? "").replace(/\r?\n|\r/g, " ");
@@ -51,8 +50,9 @@ function header(L, title, m) {
   L.push(`> ${md(m.target)} · scanned ${when(m.timestamp)} · Penthera v${m.tool.version}`, "");
 }
 
-function footer(L) {
+function footer(L, m) {
   L.push("---", "", "*Authorized security testing only. See the Penthera README for ethical use guidelines.*", "");
+  L.push(...footerLines(m));
 }
 
 function timelineSection(L, t, { heading = "## Fix timeline" } = {}) {
@@ -111,7 +111,7 @@ export function formatDeveloperReport(m) {
     for (const x of m.suppressed) L.push(`- ${md(x.title)} (${code(x.fid)}): ${md(x.reason)} (${md(x.actor)}, ${x.by})`);
     L.push("");
   }
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
@@ -167,7 +167,7 @@ export function formatOwnerReport(m) {
     L.push("## Fixes", "");
     L.push(`${t.verified} ${t.verified === 1 ? "fix" : "fixes"} verified by a re-scan, ${t.failed} failed, ${t.open} still open. Typical time to fix: ${t.medianTimeToFix}.`, "");
   }
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
@@ -256,15 +256,15 @@ export function formatAuditorReport(m) {
 
   L.push("## Verifying this report", "");
   L.push(`If this report came in an evidence bundle, check that nothing in it changed since it was produced: ${code("penthera evidence verify <dir> --allowed-signers <file>")}. See [docs/evidence.md](${EVIDENCE_URL}).`, "");
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
 const FORMATTERS = { developer: formatDeveloperReport, owner: formatOwnerReport, auditor: formatAuditorReport };
 
 /** Render the report for one audience. Throws on an unknown audience. */
-export function formatAudienceReport(result, audience, { version } = {}) {
+export function formatAudienceReport(result, audience, { version, footer = true } = {}) {
   const fmt = FORMATTERS[audience];
   if (!fmt) throw new Error(`Unknown --audience "${audience}". Use one of: ${AUDIENCES.join(", ")}.`);
-  return fmt(buildReportModel(result, { version }));
+  return fmt({ ...buildReportModel(result, { version }), footer });
 }

package/src/report/evidence.js

@@ -9,11 +9,12 @@
  * See docs/evidence.md.
  */
 import { createHash } from "node:crypto";
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import {
   readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, lstatSync,
 } from "node:fs";
 import { join, resolve, relative, sep } from "node:path";
+import { createGit } from "../agent/git.js";
 
 export const SCHEMA = "penthera-evidence/1";
 export const NAMESPACE = "penthera-evidence";
@@ -75,8 +76,10 @@ function quote(a) {
 export function gitInfo(dir) {
   if (!dir) return null;
   try {
-    const commit = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    const status = execFileSync("git", ["-C", dir, "status", "--porcelain"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    // The scanned repo is untrusted: no fsmonitor, no hooks, no transports.
+    const git = createGit(dir);
+    const commit = git.run("rev-parse", "HEAD").trim();
+    const status = git.run("status", "--porcelain");
     return /^[0-9a-f]{40,64}$/.test(commit) ? { commit, dirty: status.trim().length > 0 } : null;
   } catch {
     return null;
@@ -174,19 +177,28 @@ function sshVerify(args, manifestBuf) {
   return { ok: r.status === 0, out: `${r.stdout || ""}${r.stderr || ""}`.trim() };
 }
 
-function checkSignature(root, manifestBuf, allowedSigners) {
+/**
+ * Signature status. A bundle that says it is signed (manifest.signature, or a
+ * .sig file) only passes when the signature verifies against --allowed-signers:
+ * anyone can re-sign a rewritten manifest with their own key, so a signature
+ * whose signer was not checked proves nothing and must not read as "verified".
+ */
+function checkSignature(root, manifestBuf, manifest, allowedSigners) {
   const sigPath = join(root, SIGNATURE);
+  const declared = manifest.signature != null;
   if (!existsSync(sigPath)) {
+    if (declared) return { status: "missing", ok: false, detail: `the manifest declares a signature but ${SIGNATURE} is missing` };
     return allowedSigners
       ? { status: "missing", ok: false, detail: `--allowed-signers was given but there is no ${SIGNATURE}` }
-      : { status: "unsigned", ok: true, detail: "bundle is not signed; hashes only prove it is internally consistent" };
+      : { status: "unsigned", ok: true, detail: "UNSIGNED: hashes only prove the bundle is internally consistent, not who wrote it" };
+  }
+  if (lstatSync(sigPath).isSymbolicLink() || !lstatSync(sigPath).isFile()) {
+    return { status: "invalid", ok: false, detail: `${SIGNATURE} is not a regular file` };
   }
   if (!allowedSigners) {
     const r = sshVerify(["check-novalidate", "-n", NAMESPACE, "-s", sigPath], manifestBuf);
-    if (r.missing) return { status: "unchecked", ok: true, detail: "ssh-keygen not found; signature not checked" };
-    return r.ok
-      ? { status: "valid-unknown-signer", ok: true, detail: "signature is valid, but the signer was not checked: pass --allowed-signers" }
-      : { status: "invalid", ok: false, detail: r.out };
+    if (!r.missing && !r.ok) return { status: "invalid", ok: false, detail: r.out };
+    return { status: "unverified", ok: false, detail: "the bundle is signed, but the signer was not checked: pass --allowed-signers <file> listing the keys you trust" };
   }
   const allowed = resolve(allowedSigners);
   if (!existsSync(allowed)) return { status: "invalid", ok: false, detail: `allowed signers file ${allowedSigners} not found` };
@@ -203,14 +215,16 @@ function checkSignature(root, manifestBuf, allowedSigners) {
 
 /**
  * Verify a bundle. Never throws on a bad bundle; returns { ok, ... }.
+ * `warnings` carries the UNSIGNED notice for a bundle that passes without a
+ * signature; `requireSignature` turns that into a failure.
  * @param {string} dir
- * @param {{ allowedSigners?: string }} opts
+ * @param {{ allowedSigners?: string, requireSignature?: boolean }} opts
  */
-export function verifyEvidence(dir, { allowedSigners = null } = {}) {
+export function verifyEvidence(dir, { allowedSigners = null, requireSignature = false } = {}) {
   const root = resolve(dir);
   const problems = [];
   const files = [];
-  const fail = (msg) => ({ ok: false, problems: [msg], files, unlisted: [], signature: null, manifest: null });
+  const fail = (msg) => ({ ok: false, problems: [msg], warnings: [], files, unlisted: [], signature: null, manifest: null });
 
   const manifestPath = join(root, MANIFEST);
   if (!existsSync(manifestPath)) return fail(`${MANIFEST} not found in ${dir}`);
@@ -246,8 +260,13 @@ export function verifyEvidence(dir, { allowedSigners = null } = {}) {
   for (const p of unlisted) problems.push(`${p} is in the bundle but not in the manifest`);
   for (const f of files) if (!f.ok) problems.push(`${f.path}: ${f.reason}`);
 
-  const signature = checkSignature(root, manifestBuf, allowedSigners);
+  const signature = checkSignature(root, manifestBuf, manifest, allowedSigners);
   if (!signature.ok) problems.push(`signature: ${signature.detail}`);
+  const warnings = [];
+  if (signature.status === "unsigned") {
+    if (requireSignature) problems.push("signature: --require-signature was given but the bundle is not signed");
+    else warnings.push("UNSIGNED bundle: anyone could have written it. Ask for a signed bundle and verify with --allowed-signers --require-signature.");
+  }
 
-  return { ok: problems.length === 0, problems, files, unlisted, signature, manifest };
+  return { ok: problems.length === 0, problems, warnings, files, unlisted, signature, manifest };
 }