penthera 1.7.0 → 1.8.0

package/scripts/rules/build-pack.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Build a rule pack's pack.json: hash every rule file in the directory and
+ * write the index. Run it after editing any rule file, then sign the result
+ * with scripts/rules/sign-pack.sh (maintainer only).
+ *
+ *   node scripts/rules/build-pack.mjs <dir> [--name n] [--version x.y.z]
+ *        [--min-penthera x.y.z] [--description "..."] [--created-at ISO]
+ *
+ * Existing pack.json values are kept unless overridden. created_at only moves
+ * when a rule file changed, so rebuilding an unchanged pack is a no-op. A
+ * pack.json.sig left over from before a change is deleted: it no longer
+ * matches, and a stale signature is worse than none.
+ */
+import { readFileSync, writeFileSync, readdirSync, existsSync, unlinkSync } from "node:fs";
+import { join, resolve, basename, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const { values: opts, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    name: { type: "string" },
+    version: { type: "string" },
+    "min-penthera": { type: "string" },
+    description: { type: "string" },
+    "created-at": { type: "string" },
+  },
+});
+if (positionals.length !== 1) {
+  console.error("usage: node scripts/rules/build-pack.mjs <pack-dir> [--name n] [--version x.y.z] [--min-penthera x.y.z] [--description text] [--created-at ISO]");
+  process.exit(2);
+}
+
+const dir = resolve(positionals[0]);
+const manifestPath = join(dir, "pack.json");
+const old = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf-8")) : {};
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf-8"));
+
+const rules = readdirSync(dir)
+  .filter((f) => f.endsWith(".json") && f !== "pack.json")
+  .sort()
+  .map((file) => {
+    const buf = readFileSync(join(dir, file));
+    let kind;
+    try { kind = JSON.parse(buf.toString("utf-8")).kind; } catch (e) { console.error(`${file}: invalid JSON (${e.message})`); process.exit(1); }
+    return { file, kind, sha256: createHash("sha256").update(buf).digest("hex") };
+  });
+if (rules.length === 0) { console.error(`No rule files (*.json) in ${dir}`); process.exit(1); }
+
+const changed = JSON.stringify(old.rules || []) !== JSON.stringify(rules);
+const manifest = {
+  schema: 1,
+  name: opts.name || old.name || basename(dir),
+  version: opts.version || old.version || "1.0.0",
+  created_at: opts["created-at"] || (!changed && old.created_at) || new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+  min_penthera: opts["min-penthera"] || old.min_penthera || pkg.version,
+  ...(opts.description || old.description ? { description: opts.description || old.description } : {}),
+  rules,
+};
+const out = JSON.stringify(manifest, null, 2) + "\n";
+const before = existsSync(manifestPath) ? readFileSync(manifestPath, "utf-8") : null;
+writeFileSync(manifestPath, out);
+
+// Validate the result with the same code that loads packs.
+const { verifyPack } = await import("../../lib/rules/pack.js");
+const sigPath = join(dir, "pack.json.sig");
+if (before !== out && existsSync(sigPath)) {
+  unlinkSync(sigPath);
+  console.log("Removed pack.json.sig: pack.json changed, so the old signature no longer applies. Re-sign it.");
+}
+const v = verifyPack(dir);
+if (!v.ok) {
+  console.error(`pack.json written, but the pack does not verify:\n  ${v.errors.join("\n  ")}`);
+  process.exit(1);
+}
+for (const w of v.warnings) console.log(`warning: ${w}`);
+console.log(`${before === out ? "Unchanged" : "Wrote"} ${manifestPath}: ${manifest.name}@${manifest.version}, ${v.count} rule(s) in ${rules.length} file(s). Signature: ${v.signature}.`);
+if (v.signature !== "valid") console.log("Next: sign it with scripts/rules/sign-pack.sh before release.");

package/scripts/rules/check-bundled.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Release gate: every rule pack bundled in lib/rules/ must verify and carry a
+ * valid signature from a key in lib/rules/allowed_signers. Runs in the publish
+ * workflow before `npm stage publish`, so a rule change cannot ship without
+ * passing through the maintainer's signing key.
+ *
+ *   node scripts/rules/check-bundled.mjs        (npm run rules:check)
+ */
+import { basename } from "node:path";
+import { verifyPack, bundledPackDirs } from "../../lib/rules/index.js";
+
+let bad = 0;
+for (const dir of bundledPackDirs()) {
+  const v = verifyPack(dir);
+  const name = `${basename(dir)}${v.version ? `@${v.version}` : ""}`;
+  if (!v.ok) {
+    console.error(`FAIL ${name}: ${v.errors.join("; ")}`);
+    bad++;
+  } else if (v.signature !== "valid") {
+    console.error(`FAIL ${name}: ${v.signature === "missing" ? "not signed" : `signature invalid (${v.signatureError})`}. Sign it: scripts/rules/sign-pack.sh lib/rules/${basename(dir)}`);
+    bad++;
+  } else {
+    console.log(`ok   ${name}: ${v.count} rules, signed by ${v.signer}`);
+  }
+}
+if (bad) {
+  console.error(`\n${bad} bundled rule pack(s) not ready to release. See docs/rule-packs.md ("Signing a release").`);
+  process.exit(1);
+}

package/scripts/rules/sign-pack.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Sign a rule pack's pack.json. Maintainer only: it needs the private half of
+# a key listed in lib/rules/allowed_signers. Never run this in CI; the point
+# of the signature is that the key stays on the maintainer's machine (or a
+# hardware key), so a compromised workflow cannot produce a trusted pack.
+#
+#   scripts/rules/sign-pack.sh <pack-dir> [private-key]
+#
+# private-key defaults to ~/.ssh/id_ed25519. Steps:
+#   1. node scripts/rules/build-pack.mjs <pack-dir>   (hashes are current)
+#   2. ssh-keygen -Y sign -n penthera-rules            (writes pack.json.sig)
+#   3. penthera rules verify <pack-dir>                (checks it against allowed_signers)
+# Review `git diff <pack-dir>` before signing: the signature vouches for
+# every rule in the pack.
+set -euo pipefail
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "usage: $0 <pack-dir> [private-key]" >&2
+  exit 2
+fi
+DIR="$1"
+KEY="${2:-$HOME/.ssh/id_ed25519}"
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+[ -f "$DIR/pack.json" ] || { echo "No pack.json in $DIR (run build-pack.mjs first)" >&2; exit 1; }
+[ -f "$KEY" ] || { echo "Private key not found: $KEY" >&2; exit 1; }
+command -v ssh-keygen >/dev/null || { echo "ssh-keygen not found (OpenSSH 8.1+ needed)" >&2; exit 1; }
+
+node "$ROOT/scripts/rules/build-pack.mjs" "$DIR"
+rm -f "$DIR/pack.json.sig"
+ssh-keygen -Y sign -f "$KEY" -n penthera-rules "$DIR/pack.json"
+node "$ROOT/bin/penthera.js" rules verify "$DIR"

package/skills/penthera/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: penthera
 description: >
-  Open-source security for the apps and AI systems the user ships, run locally with
-  the Penthera CLI. Sets it up in one command ("set up penthera in this repo").
-  Scans the user's own live URL and repo (TLS, headers, auth, OpenAPI, secrets incl. AI keys,
-  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
+  Offline cyber security agent for the user's own apps and AI coding tools, run
+  locally with the Penthera CLI; open R&D, measured in public. Sets it up in one
+  command ("set up penthera in this repo"). Scans the user's own live URL and repo
+  (TLS, headers, auth, OpenAPI, secrets incl. AI keys, 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 commit ("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"); 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
-  their own app, staging URL, localhost, repo, dependencies, or agent setup. Do NOT
-  use for targets without explicit authorization.
+  diff). Use when the user asks to scan, audit, harden, fix, or review the security
+  of their own app, staging URL, localhost, repo, dependencies, or agent setup. Do
+  NOT use for targets without explicit authorization.
 license: MIT
 compatibility: Node.js 22+, network access to target, Penthera CLI (npm link or node bin/penthera.js from repo). macOS only for --machine.
 allowed-tools: "Bash(node:*) Bash(npm:*) Bash(penthera:*) Read Write Edit"
 metadata:
   author: danoszz
-  version: 1.7.0
+  version: 1.8.0
   category: security
 ---
 
@@ -70,6 +70,7 @@ All examples below use `penthera`; substitute `node bin/penthera.js` when needed
 | Scan a live URL | `penthera <url> --profile standard -o reports/scan.json` |
 | 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**) |
+| Am I affected by a PHP / nginx / Apache / Node.js / Python / OpenSSL advisory? | `penthera <url>` and `penthera --repo .`; for an advisory newer than the release, add `--rules <signed-pack>` (see docs/runtime-advisories.md). Report "check on server" findings as unknown, never as safe |
 | 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**) |
@@ -253,7 +254,7 @@ penthera <url> --repo . --framework nis2 --audience auditor --markdown reports/a
 penthera <url> --repo . --framework nis2 --evidence reports/evidence-$(date +%F) --sign-key ~/.ssh/id_ed25519
 penthera evidence verify reports/evidence-$(date +%F)
 ```
-   Tell the user to send the public key to the auditor separately (an `allowed_signers` line) and point them to `docs/evidence.md` for the one-command check.
+   Tell the user to send the public key to the auditor separately (an `allowed_signers` line) and point them to [docs/evidence.md](https://github.com/danoszz/penthera/blob/main/docs/evidence.md) for the one-command check.
 4. A house format: write a template with `{{summary.critical}}`, `{{#each findings}}…{{/each}}` and `{{#if x}}…{{/if}}` (no other syntax), then `--report-template reports/template.md --markdown reports/custom.md`.
 5. Summarize what the report says in two or three sentences. Never describe a bundle as an audit or a certification: it is technical evidence.
 
@@ -355,7 +356,7 @@ penthera ui --demo --open                            # fake data, to look around
 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 bar at the bottom of the view starts scans, dependency checks, AI tooling audits and the fix loop for the selected project. 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).
+See [docs/dashboard.md](https://github.com/danoszz/penthera/blob/main/docs/dashboard.md).
 
 ## Examples
 

package/src/agent/git.js

@@ -9,15 +9,40 @@
  *   - GIT_NO_LAZY_FETCH=1, so a partial clone cannot fetch missing objects;
  *   - core.hooksPath=/dev/null, core.fsmonitor=false and commit --no-verify, so
  *     the scanned repo's hooks never run (a repo can ship hooks that do anything);
+ *   - signing off (commit/tag.gpgsign=false, every gpg.*.program and
+ *     gpg.ssh.defaultKeyCommand overridden), so a repo cannot name a signer;
+ *   - no attributes from the user's attributes file (core.attributesFile=/dev/null)
+ *     or, on git >= 2.40, from the work tree (--attr-source=<empty tree>), and
+ *     every filter driver the config defines emptied, so no clean/smudge/process
+ *     filter runs whatever selects it ($GIT_DIR/info/attributes is always read);
+ *   - GIT_LITERAL_PATHSPECS=1, so a file named `[id].js` or `:(glob)x` is only
+ *     ever that file;
  *   - GIT_TERMINAL_PROMPT=0 and an empty credential helper, so nothing asks for
  *     or hands out credentials.
+ * Subcommands that write (checkout, add, commit, reset) also need git >= 2.31
+ * (for GIT_CONFIG_KEY_n, which empties the filters) and are refused while the
+ * repo's own config sets any filter.*, gpg.*, include.* or includeIf.* key.
  */
 import { execFileSync } from "node:child_process";
+import { safeEnv, SAFE_CONFIG } from "../../lib/git.js";
 
 export const ALLOWED_SUBCOMMANDS = Object.freeze([
   "rev-parse", "symbolic-ref", "status", "diff", "log", "show-ref", "checkout", "add", "commit", "config",
+  "check-ignore", "reset",
 ]);
 
+/** Subcommands that change the work tree, the index or refs. */
+export const WRITE_SUBCOMMANDS = Object.freeze(["checkout", "add", "commit", "reset"]);
+
+/** GIT_CONFIG_COUNT/KEY_n/VALUE_n arrived in git 2.31: below it, filters cannot be emptied. */
+export const MIN_WRITE_VERSION = Object.freeze([2, 31]);
+
+/** --attr-source arrived in git 2.40; older git still reads the work tree's .gitattributes. */
+export const ATTR_SOURCE_VERSION = Object.freeze([2, 40]);
+
+/** The empty tree: as an attribute source it means "no .gitattributes anywhere". */
+export const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
 /** Arguments that would make an allowed subcommand reach outside the repo. */
 const FORBIDDEN_ARGS = [
   /^-c$/, /^--config/, /^--git-dir/, /^--work-tree/, /^--exec-path/, /^--upload-pack/, /^--receive-pack/,
@@ -25,10 +50,10 @@ const FORBIDDEN_ARGS = [
 ];
 
 export class GitPolicyError extends Error {
-  constructor(message) {
+  constructor(message, code = "GIT_FORBIDDEN") {
     super(message);
     this.name = "GitPolicyError";
-    this.code = "GIT_FORBIDDEN";
+    this.code = code;
   }
 }
 
@@ -49,15 +74,45 @@ export function assertAllowed(args) {
   if (sub === "config" && !(rest.length === 2 && rest[0] === "--get" && /^[\w.-]+$/.test(rest[1]))) {
     throw new GitPolicyError("git config: only `config --get <key>` is allowed");
   }
+  // `reset` may only unstage paths: no --hard, no commit-ish.
+  if (sub === "reset" && !(rest.length >= 3 && rest[0] === "-q" && rest[1] === "--")) {
+    throw new GitPolicyError("git reset: only `reset -q -- <paths>` is allowed");
+  }
   return true;
 }
 
-const SAFE_CONFIG = [
-  "-c", "protocol.allow=never",
-  "-c", "core.hooksPath=/dev/null",
-  "-c", "core.fsmonitor=false",
-  "-c", "credential.helper=",
-];
+
+/** "git version 2.43.0.windows.1" -> [2, 43], or null. */
+export function parseGitVersion(text) {
+  const m = /git version (\d+)\.(\d+)/.exec(String(text || ""));
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+
+const atLeast = (v, min) => Boolean(v) && (v[0] > min[0] || (v[0] === min[0] && v[1] >= min[1]));
+
+const versionCache = new WeakMap(); // exec -> [major, minor] | null
+
+/** How to get past a GIT_UNSAFE_CONFIG refusal. */
+const WAY_FORWARD = "Move the setting to your global config (`git config --global <key> ...`) and remove it here (`git config --unset <key>`), or apply fixes by hand from the report (`penthera fix --plan` prints each diff). Scans and reports still work.";
+
+/** Keys in the repo's own config that make a write unsafe. */
+const UNSAFE_REPO_KEY = /^(filter|gpg)\.|^include(if)?\./i;
+const FILTER_KEY = /^filter\.(.+)\.(clean|smudge|process|required)$/i;
+
+/**
+ * Parse `git config --show-scope -z --get-regexp` output into [{ scope, key }].
+ * Each record is "scope\0key\nvalue\0" (or "scope\0key\0" for a bare boolean).
+ */
+export function parseScopedConfig(out) {
+  const parts = String(out || "").split("\0");
+  const entries = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const scope = parts[i];
+    const nl = parts[i + 1].indexOf("\n");
+    entries.push({ scope, key: nl < 0 ? parts[i + 1] : parts[i + 1].slice(0, nl) });
+  }
+  return entries;
+}
 
 /**
  * Bind a git runner to a work tree.
@@ -67,19 +122,97 @@ const SAFE_CONFIG = [
  * @returns {{ run(...args: string[]): string, tryRun(...args: string[]): string|null }}
  */
 export function createGit(cwd, { exec = execFileSync, env = process.env } = {}) {
-  const childEnv = { ...env, GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0" };
+  const baseEnv = { ...safeEnv(env), GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" };
+  const opts = (extra = {}) => ({
+    cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 32 * 1024 * 1024, ...extra,
+  });
+
+  const version = () => {
+    if (!versionCache.has(exec)) {
+      let v = null;
+      try { v = parseGitVersion(exec("git", ["--version"], opts({ env: baseEnv, timeout: 10_000 }))); } catch { v = null; }
+      versionCache.set(exec, v);
+    }
+    return versionCache.get(exec);
+  };
+
+  // Read the config git will see (includes followed: reading config runs nothing).
+  // Exit 1 means no key matched; anything else fails closed.
+  const probe = () => {
+    let out;
+    try {
+      out = exec("git", ["config", "--show-scope", "-z", "--get-regexp", "^(filter|gpg|include|includeif)\\."],
+        opts({ env: baseEnv, timeout: 10_000 }));
+    } catch (e) {
+      if (e?.status === 1) out = "";
+      else throw new GitPolicyError(`git: could not read this repo's git config safely (${String(e?.stderr || e?.message || e).trim().split("\n")[0]})`, "GIT_UNSAFE_CONFIG");
+    }
+    const entries = parseScopedConfig(out);
+    const filters = new Set();
+    for (const { key } of entries) {
+      const m = FILTER_KEY.exec(key);
+      if (m) filters.add(m[1]);
+    }
+    const repoKeys = entries.filter((e) => (e.scope === "local" || e.scope === "worktree") && UNSAFE_REPO_KEY.test(e.key)).map((e) => e.key);
+    return { filters: [...filters], repoKeys: [...new Set(repoKeys)] };
+  };
+  let probed = null;
+
+  // Every filter driver any config defines is emptied for this call, through
+  // GIT_CONFIG_KEY_n (a driver name may contain "=", which `-c` cannot carry).
+  const envFor = (filters) => {
+    if (!filters.length) return baseEnv;
+    const childEnv = { ...baseEnv };
+    let n = /^\d+$/.test(String(env.GIT_CONFIG_COUNT || "")) ? Number(env.GIT_CONFIG_COUNT) : 0;
+    for (const name of filters) {
+      for (const [k, v] of [["clean", ""], ["smudge", ""], ["process", ""], ["required", "false"]]) {
+        childEnv[`GIT_CONFIG_KEY_${n}`] = `filter.${name}.${k}`;
+        childEnv[`GIT_CONFIG_VALUE_${n}`] = v;
+        n++;
+      }
+    }
+    childEnv.GIT_CONFIG_COUNT = String(n);
+    return childEnv;
+  };
+
   const run = (...args) => {
     assertAllowed(args);
-    const full = args[0] === "commit" ? ["commit", "--no-verify", ...args.slice(1)] : args;
-    return exec("git", [...SAFE_CONFIG, ...full], {
-      cwd, env: childEnv, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 32 * 1024 * 1024,
-    });
+    const sub = args[0];
+    const v = version();
+    if (WRITE_SUBCOMMANDS.includes(sub)) {
+      probed = probe(); // fresh before every write
+      if (probed.repoKeys.length) {
+        const keys = probed.repoKeys.slice(0, 5).join(", ") + (probed.repoKeys.length > 5 ? ", ..." : "");
+        throw new GitPolicyError(
+          `penthera won't write in this repo: its own git config sets ${keys}, and repo-level git config can run programs during checkout and commit. ${WAY_FORWARD.replaceAll("<key>", probed.repoKeys[0])}`,
+          "GIT_UNSAFE_CONFIG",
+        );
+      }
+      if (!atLeast(v, MIN_WRITE_VERSION)) {
+        throw new GitPolicyError(
+          `penthera won't write in this repo: git ${v ? v.join(".") : "(unknown version)"} is older than ${MIN_WRITE_VERSION.join(".")}, the minimum it needs to switch off filters the repo configures. Upgrade git, or apply fixes by hand from the report (\`penthera fix --plan\` prints each diff). Scans and reports still work.`,
+          "GIT_TOO_OLD",
+        );
+      }
+    } else if (!probed) {
+      probed = probe();
+    }
+    if (probed.filters.length && !atLeast(v, MIN_WRITE_VERSION)) {
+      throw new GitPolicyError(`git: this repo's config defines filter drivers, and git older than ${MIN_WRITE_VERSION.join(".")} cannot switch them off. Upgrade git.`, "GIT_TOO_OLD");
+    }
+    const pre = atLeast(v, ATTR_SOURCE_VERSION) ? [...SAFE_CONFIG, `--attr-source=${EMPTY_TREE}`] : SAFE_CONFIG;
+    const full = sub === "commit" ? ["commit", "--no-verify", ...args.slice(1)] : args;
+    let childEnv = envFor(probed.filters);
+    // check-ignore takes paths, not pathspecs, and rejects the literal flag; callers pass "./<path>".
+    if (sub === "check-ignore") childEnv = { ...childEnv, GIT_LITERAL_PATHSPECS: "0" };
+    return exec("git", [...pre, ...full], opts({ env: childEnv }));
   };
   const tryRun = (...args) => {
     try {
       return run(...args);
     } catch (e) {
-      if (e instanceof GitPolicyError) throw e;
+      // A forbidden call is a bug in the caller; an unreadable config or an old git is just "no answer".
+      if (e instanceof GitPolicyError && e.code === "GIT_FORBIDDEN") throw e;
       return null;
     }
   };