penthera 1.5.0 → 1.6.0

package/lib/rules/regex-guard.js

@@ -0,0 +1,368 @@
+/**
+ * Static ReDoS guard for regexes that come from data: rule packs, community
+ * Nuclei templates. Rule packs scan hostile input (dependency source, agent
+ * configs, response bodies), so a pack must not be able to hang the scanner
+ * by shipping a pattern that backtracks catastrophically.
+ *
+ * V8's regex engine backtracks, and its linear-time engine (the `l` flag)
+ * refuses ordinary bounded repeats like `{64}`, so the guard is structural:
+ * it parses the pattern and refuses the shapes that blow up.
+ *
+ *   1. Length cap (MAX_LENGTH).
+ *   2. No backreferences and no lookaround. Detection rules do not need them,
+ *      and both defeat simple reasoning about cost.
+ *   3. Star height 1: a quantified group may not contain a quantifier
+ *      (`(a+)+`, `(\w*\s?)*`). The exponential case.
+ *   4. A group under an unbounded quantifier may not contain alternation
+ *      (`(a|aa)+`, `(a|a)*`). The other exponential case.
+ *   5. Bounded repeats are capped at MAX_REPEAT.
+ *   6. An unbounded quantifier that is followed by something mandatory may
+ *      not be reachable from every start position (`\s*x`, `[a-z]+@`): each
+ *      start would rescan the rest of the input. Something mandatory before
+ *      it that cannot occur inside its run (`x\s*:`) breaks the chain.
+ *   7. Two quantifiers that can match the same characters, with nothing
+ *      mandatory between them that the first cannot also match (`.*b.*`,
+ *      `\s*\s*`), multiply their cost. A chain with an unbounded member is
+ *      refused; a bounded chain must stay under CHAIN_BUDGET.
+ *
+ * The guard is conservative: it refuses some safe patterns. That is the right
+ * trade for data that arrives from outside the codebase. tests/rule-packs.test.js
+ * fuzzes it: every pattern it accepts must run in bounded time on adversarial
+ * input.
+ */
+
+export const MAX_LENGTH = 512;
+export const MAX_REPEAT = 256;
+export const CHAIN_BUDGET = 1024;
+export const ALLOWED_FLAGS = /^[imsu]*$/;
+
+// The narrower check for community templates (lib/templates.js, added in
+// v1.1.1 as a regex): refuse a quantifier applied to a group that contains a
+// quantifier, at any depth, or a quantifier stacked on another (`a+*`). It
+// keeps user templates working that the strict checkRegex below would refuse.
+// A linear scan rather than a regex, because a regex inspecting a pattern
+// string is itself open to backtracking on input like "((((((".
+const QUANT_START = (src, i) => src[i] === "*" || src[i] === "+" || (src[i] === "{" && /^\{\d+(,\d*)?\}/.test(src.slice(i, i + 24)));
+
+export function hasNestedQuantifier(pattern) {
+  const src = String(pattern);
+  const groups = []; // per open group: does it contain a quantifier?
+  let prevQuant = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (c === "\\") { i++; prevQuant = false; continue; }
+    if (c === "[") {
+      for (i++; i < src.length && src[i] !== "]"; i++) if (src[i] === "\\") i++;
+      prevQuant = false;
+      continue;
+    }
+    if (c === "(") { groups.push(false); prevQuant = false; continue; }
+    if (c === ")") {
+      const inner = groups.pop() || false;
+      if (inner && QUANT_START(src, i + 1)) return true;
+      if (inner && groups.length) groups[groups.length - 1] = true;
+      prevQuant = false;
+      continue;
+    }
+    if (QUANT_START(src, i) || c === "?") {
+      const isQ = c !== "?" || (i > 0 && src[i - 1] !== "(" && !prevQuant);
+      if (c !== "?" && prevQuant) return true; // a+* / a{2}+
+      if (isQ && c !== "?" && groups.length) groups[groups.length - 1] = true;
+      if (c === "{") i = src.indexOf("}", i);
+      prevQuant = c !== "?" ? true : prevQuant;
+      continue;
+    }
+    prevQuant = false;
+  }
+  return false;
+}
+
+class GuardError extends Error {}
+const refuse = (msg) => { throw new GuardError(msg); };
+
+// ── Parser ────────────────────────────────────────────────────────────────
+// A small parser for the subset of JS regex syntax a detection rule needs.
+// Nodes: { type: "alt", branches: Item[][] }, items are { atom, min, max, src }
+// where atom is { type: "char"|"class"|"any"|"anchor"|"group", src, alt? }.
+
+function parse(src, unicode) {
+  let i = 0;
+  const peek = () => src[i];
+
+  function parseAlt(depth) {
+    if (depth > 8) refuse("groups nested deeper than 8");
+    const branches = [[]];
+    while (i < src.length) {
+      const c = peek();
+      if (c === ")") break;
+      if (c === "|") { i++; branches.push([]); continue; }
+      const start = i;
+      const atom = parseAtom(depth);
+      const q = parseQuantifier(atom);
+      branches[branches.length - 1].push({ atom, ...q, src: src.slice(start, i) });
+    }
+    return { type: "alt", branches };
+  }
+
+  function parseAtom(depth) {
+    const c = src[i];
+    if (c === "(") {
+      i++;
+      if (src.startsWith("?:", i)) i += 2;
+      else if (src.startsWith("?=", i) || src.startsWith("?!", i) || src.startsWith("?<=", i) || src.startsWith("?<!", i)) refuse("lookaround is not allowed");
+      else if (src.startsWith("?<", i)) {
+        const end = src.indexOf(">", i);
+        if (end < 0) refuse("unterminated group name");
+        i = end + 1;
+      } else if (c === "(" && src[i] === "?") refuse("unsupported group syntax");
+      const alt = parseAlt(depth + 1);
+      if (src[i] !== ")") refuse("unterminated group");
+      i++;
+      return { type: "group", alt };
+    }
+    if (c === "[") return parseClass();
+    if (c === "\\") return parseEscape();
+    if (c === ".") { i++; return { type: "any", src: "." }; }
+    if (c === "^" || c === "$") { i++; return { type: "anchor", src: c }; }
+    if (c === "*" || c === "+" || c === "?" || c === "{" && /^\{\d/.test(src.slice(i))) refuse("quantifier with nothing to repeat");
+    if (c === "]" || c === "}") { if (unicode) refuse(`lone ${c}`); }
+    i++;
+    return { type: "char", src: c };
+  }
+
+  function parseEscape() {
+    const start = i;
+    i++;
+    const c = src[i];
+    if (c === undefined) refuse("trailing backslash");
+    if (/[1-9]/.test(c)) refuse("backreferences are not allowed");
+    if (c === "k" && src[i + 1] === "<") refuse("backreferences are not allowed");
+    if (c === "b" || c === "B") { i++; return { type: "anchor", src: src.slice(start, i) }; }
+    if (c === "x") i += 3;
+    else if (c === "u" && src[i + 1] === "{") i = src.indexOf("}", i) + 1 || refuse("bad \\u{} escape");
+    else if (c === "u") i += 5;
+    else if ((c === "p" || c === "P") && src[i + 1] === "{") i = src.indexOf("}", i) + 1 || refuse("bad \\p{} escape");
+    else if (c === "c") i += 2;
+    else i++;
+    const s = src.slice(start, i);
+    return { type: /^\\[dDwWsSpP]/.test(s) ? "class" : "char", src: s };
+  }
+
+  function parseClass() {
+    const start = i;
+    i++;
+    if (src[i] === "^") i++;
+    if (src[i] === "]") i++;
+    while (i < src.length && src[i] !== "]") {
+      if (src[i] === "\\") {
+        if (/[1-9]/.test(src[i + 1] || "")) refuse("backreferences are not allowed");
+        i += 2;
+      } else if (src[i] === "[" && unicode) refuse("nested classes are not allowed");
+      else i++;
+    }
+    if (src[i] !== "]") refuse("unterminated character class");
+    i++;
+    return { type: "class", src: src.slice(start, i) };
+  }
+
+  function parseQuantifier(atom) {
+    let min = 1;
+    let max = 1;
+    const c = src[i];
+    if (c === "*") { min = 0; max = Infinity; i++; }
+    else if (c === "+") { min = 1; max = Infinity; i++; }
+    else if (c === "?") { min = 0; max = 1; i++; }
+    else if (c === "{") {
+      const m = /^\{(\d+)(,(\d*))?\}/.exec(src.slice(i));
+      if (!m) return { min, max };
+      min = Number(m[1]);
+      max = m[2] ? (m[3] === "" ? Infinity : Number(m[3])) : min;
+      if (max < min) refuse("quantifier range out of order");
+      if (min > MAX_REPEAT || (max !== Infinity && max > MAX_REPEAT)) refuse(`repeat count above ${MAX_REPEAT}`);
+      i += m[0].length;
+    } else return { min, max };
+    if (atom.type === "anchor") refuse("quantified anchor");
+    if (src[i] === "?") i++; // lazy: same cost bound as greedy
+    if (src[i] === "*" || src[i] === "+" || src[i] === "?" || (src[i] === "{" && /^\{\d+(,\d*)?\}/.test(src.slice(i)))) refuse("stacked quantifiers");
+    return { min, max };
+  }
+
+  const ast = parseAlt(0);
+  if (i < src.length) refuse("unbalanced parenthesis");
+  return ast;
+}
+
+// ── Character sets ────────────────────────────────────────────────────────
+// Approximated by membership over a sample alphabet: all of ASCII plus
+// representatives of the Unicode classes rules tend to touch. Two atoms
+// "overlap" if some sample character matches both.
+
+const SAMPLE = (() => {
+  const out = [];
+  for (let c = 0; c < 128; c++) out.push(String.fromCharCode(c));
+  out.push(" ", "é", "ß", "İ", "
", "​", "中", "а", "", "\u{1F600}");
+  return out;
+})();
+
+const setCache = new Map();
+function charSet(src, flags) {
+  const key = `${flags}\u0000${src}`;
+  let set = setCache.get(key);
+  if (set) return set;
+  const re = new RegExp(`^(?:${src})$`, flags.replace(/[gy]/g, ""));
+  set = new Uint8Array(SAMPLE.length);
+  for (let k = 0; k < SAMPLE.length; k++) set[k] = re.test(SAMPLE[k]) ? 1 : 0;
+  if (setCache.size > 5000) setCache.clear();
+  setCache.set(key, set);
+  return set;
+}
+const overlaps = (a, b) => a.some((v, k) => v && b[k]);
+const subset = (a, b) => a.every((v, k) => !v || b[k]);
+const union = (sets) => sets.reduce((acc, s) => acc.map((v, k) => v | s[k]), new Uint8Array(SAMPLE.length));
+
+/** Characters an item can consume (any one position), or null for anchors. */
+function itemSet(item, flags) {
+  const a = item.atom;
+  if (a.type === "anchor") return null;
+  if (a.type !== "group") return charSet(a.src, flags);
+  const sets = [];
+  for (const br of a.alt.branches) for (const it of br) { const s = itemSet(it, flags); if (s) sets.push(s); }
+  return union(sets);
+}
+
+function hasQuantifier(alt) {
+  return alt.branches.some((br) => br.some((it) => it.max > 1 || (it.atom.type === "group" && hasQuantifier(it.atom.alt))));
+}
+
+/** Largest max among quantifiers inside a group (Infinity if any unbounded). */
+function innerMax(alt) {
+  let m = 1;
+  for (const br of alt.branches) for (const it of br) {
+    m = Math.max(m, it.max);
+    if (it.atom.type === "group") m = Math.max(m, innerMax(it.atom.alt));
+  }
+  return m;
+}
+
+// ── Rules ─────────────────────────────────────────────────────────────────
+
+function checkStructure(alt) {
+  for (const br of alt.branches) for (const it of br) {
+    if (it.atom.type !== "group") continue;
+    const g = it.atom.alt;
+    if (it.max > 1 && hasQuantifier(g)) refuse(`nested quantifier in \`${it.src}\``);
+    if (it.max === Infinity && g.branches.length > 1) refuse(`alternation under an unbounded quantifier in \`${it.src}\``);
+    checkStructure(g);
+  }
+}
+
+const MAX_PATHS = 256;
+
+/**
+ * Expand a branch into the linear sequences of leaf items it can match.
+ * A group that is not repeated (`(?:a|b)`, `(?:sudo\s+)?`) is inlined once
+ * per alternative, plus a "skipped" path when it is optional, so quantifiers
+ * on either side of it are compared along each real path. A repeated group
+ * becomes one leaf (rule 3 guarantees it holds no quantifier). Past MAX_PATHS
+ * the remaining groups collapse to one conservative leaf each.
+ */
+function expand(branch, flags) {
+  let seqs = [[]];
+  for (const it of branch) {
+    const a = it.atom;
+    if (a.type === "anchor") continue;
+    if (a.type === "group" && it.max <= 1) {
+      const alts = a.alt.branches.flatMap((b) => expand(b, flags));
+      if (it.min === 0) alts.push([]);
+      if (seqs.length * alts.length <= MAX_PATHS) {
+        seqs = seqs.flatMap((s) => alts.map((x) => s.concat(x)));
+        continue;
+      }
+      const leaf = { set: itemSet(it, flags), min: it.min, max: innerMax(a.alt), src: it.src };
+      seqs = seqs.map((s) => s.concat([leaf]));
+      continue;
+    }
+    const leaf = { set: itemSet(it, flags), min: it.min, max: it.max, src: it.src };
+    seqs = seqs.map((s) => s.concat([leaf]));
+  }
+  return seqs;
+}
+
+/**
+ * Rule 6. An unanchored search tries every start position. An unbounded
+ * quantifier followed by something mandatory rescans its run from each start
+ * that can reach it, which is quadratic when everything mandatory before it
+ * can also sit inside that run (`\s*x`, `[^a]{1,40}\S[ab]* ` on "bbbb").
+ * A greedy quantifier with nothing mandatory after it succeeds at once.
+ */
+function checkRescan(seq, anchored) {
+  if (anchored) return;
+  for (let q = 0; q < seq.length; q++) {
+    const it = seq[q];
+    if (it.max !== Infinity) continue;
+    if (!seq.slice(q + 1).some((x) => x.min > 0)) continue;
+    if (seq.slice(0, q).every((x) => x.min === 0 || overlaps(x.set, it.set))) {
+      refuse(q === 0 || seq.slice(0, q).every((x) => x.min === 0)
+        ? `pattern starts with an unbounded quantifier (\`${it.src}\`)`
+        : `unbounded quantifier \`${it.src}\` can be rescanned from every start position`);
+    }
+  }
+}
+
+function checkChains(alt, flags) {
+  for (const br of alt.branches) for (const seq of expand(br, flags)) {
+    checkRescan(seq, br[0]?.atom.type === "anchor" && br[0].atom.src === "^" && !flags.includes("m"));
+    for (let a = 0; a < seq.length; a++) {
+      const head = seq[a];
+      if (head.max <= 1) continue;
+      let cost = head.max;
+      const mids = []; // mandatory atoms between head and the current item
+      for (let b = a + 1; b < seq.length; b++) {
+        const it = seq[b];
+        // The costs multiply when the head can stop inside the item's run:
+        // they share characters, and every mandatory atom in between can sit
+        // in that run too (`.*b.*` on "bbbb"). `[^\n]*\|\s*` stays linear,
+        // because `|` cannot occur inside a run of spaces.
+        if (it.max > 1 && overlaps(head.set, it.set) && mids.every((m) => overlaps(m, it.set))) {
+          cost = cost * it.max;
+          if (cost === Infinity) refuse(`overlapping quantifiers \`${head.src}\` … \`${it.src}\` (polynomial backtracking)`);
+          if (cost > CHAIN_BUDGET) refuse(`overlapping quantifiers \`${head.src}\` … \`${it.src}\` exceed the backtracking budget`);
+        }
+        // A mandatory atom the head cannot match ends the head's reach.
+        if (it.min > 0) {
+          if (!subset(it.set, head.set)) break;
+          mids.push(it.set);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Check a regex from data. Returns { ok: true } or { ok: false, reason }.
+ * Never throws.
+ * @param {string} source pattern source (no slashes)
+ * @param {string} [flags] only i, m, s, u are accepted
+ */
+export function checkRegex(source, flags = "") {
+  try {
+    if (typeof source !== "string" || source.length === 0) refuse("pattern must be a non-empty string");
+    if (typeof flags !== "string" || !ALLOWED_FLAGS.test(flags)) refuse(`flags must be a subset of "imsu" (got "${flags}")`);
+    if (source.length > MAX_LENGTH) refuse(`pattern longer than ${MAX_LENGTH} characters`);
+    try { new RegExp(source, flags); } catch (e) { refuse(`invalid regex: ${e.message}`); }
+    const ast = parse(source, flags.includes("u"));
+    checkStructure(ast);
+    checkChains(ast, flags);
+    return { ok: true };
+  } catch (e) {
+    if (e instanceof GuardError) return { ok: false, reason: e.message };
+    return { ok: false, reason: `guard error: ${e.message}` };
+  }
+}
+
+/** Compile a regex from data, or throw with the guard's reason. */
+export function compileSafe(source, flags = "") {
+  const r = checkRegex(source, flags);
+  if (!r.ok) throw new Error(`unsafe regex /${String(source).slice(0, 80)}/: ${r.reason}`);
+  return new RegExp(source, flags);
+}

package/lib/templates.js

@@ -6,6 +6,7 @@
  */
 import { joinUrl } from "../src/utils/url.js";
 import { request } from "../src/utils/http.js";
+import { hasNestedQuantifier } from "./rules/regex-guard.js";
 
 /**
  * Execute a single template check against a target.
@@ -88,10 +89,11 @@ export async function executeTemplate(baseUrl, template) {
 // the input and the pattern. This is a mitigation, not an immunity proof: real
 // guarantees need a non-backtracking engine or a killable worker.
 const REGEX_INPUT_CAP = 256 * 1024; // 256 KB is far past any real matcher's needs
-const NESTED_QUANTIFIER = /(\([^)]*[+*][^)]*\)|\[[^\]]*\][^)]*)[+*]\s*[+*]|\((?:\?:)?[^)]*[+*]\)[+*]/;
+// hasNestedQuantifier lives in lib/rules/regex-guard.js. Templates from rule
+// packs pass the stricter checkRegex there when the pack loads.
 
 function safeRegexTest(pattern, target, flags = "") {
-  if (NESTED_QUANTIFIER.test(String(pattern))) return false; // refuse the shape that blows up
+  if (hasNestedQuantifier(pattern)) return false; // refuse the shape that blows up
   try {
     const input = target.length > REGEX_INPUT_CAP ? target.slice(0, REGEX_INPUT_CAP) : target;
     return new RegExp(pattern, flags).test(input);
@@ -100,7 +102,7 @@ function safeRegexTest(pattern, target, flags = "") {
   }
 }
 
-function runMatcher(matcher, ctx) {
+export function runMatcher(matcher, ctx) {
   const part = matcher.part || "body";
   const target = part === "header" ? ctx.headers : ctx.body;
 
@@ -142,16 +144,21 @@ function runMatcher(matcher, ctx) {
 /**
  * Run a single extractor against response data.
  */
-function runExtractor(extractor, ctx) {
+export function runExtractor(extractor, ctx) {
   const part = extractor.part || "body";
   const target = part === "header" ? ctx.headers : ctx.body;
 
   switch (extractor.type) {
     case "regex": {
       for (const pattern of extractor.regex || []) {
-        if (NESTED_QUANTIFIER.test(String(pattern))) continue;
+        if (hasNestedQuantifier(pattern)) continue;
         const capped = target.length > REGEX_INPUT_CAP ? target.slice(0, REGEX_INPUT_CAP) : target;
-        const match = capped.match(new RegExp(pattern));
+        let match;
+        try {
+          match = capped.match(new RegExp(pattern));
+        } catch {
+          continue; // invalid pattern in a template must not abort the scan
+        }
         if (match) return match[extractor.group || 0];
       }
       return null;

package/lib/tls.js

@@ -26,6 +26,13 @@ const WEAK_PROTOCOLS = new Set(["TLSv1", "TLSv1.1", "SSLv3"]);
  */
 export function checkTls(hostname, port = 443, timeout = 10_000) {
   return new Promise((resolve) => {
+    // Validation is off on purpose, and only on this socket: the audit has to
+    // complete the handshake with a target whose certificate is expired,
+    // self-signed or for the wrong name, so it can report exactly that. The
+    // verdict comes from socket.authorized / authorizationError below. The
+    // socket only reads the handshake (cert, protocol, cipher) and is closed
+    // straight away; no request or credential is ever sent over it. Every
+    // other connection Penthera makes keeps Node's default validation.
     const socket = tls.connect(
       { host: hostname, port, servername: hostname, rejectUnauthorized: false },
       () => {

package/lib/whitebox/frameworks.js

@@ -1,7 +1,7 @@
 /**
  * Discover API routes in Express, Hono, and Fastify projects.
  */
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { readdirSync, readFileSync, statSync, lstatSync, existsSync } from "node:fs";
 import { join, relative } from "node:path";
 
 const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "vendor"]);
@@ -18,13 +18,16 @@ const ROUTE_RES = [
   /method:\s*['"](GET|POST|PUT|PATCH|DELETE)['"]\s*,\s*url:\s*['"`]([^'"`]+)['"`]/gi,
 ];
 
-function walkCodeFiles(dir, files = []) {
-  if (!existsSync(dir)) return files;
+function walkCodeFiles(dir, files = [], root = dir) {
+  // Nested repos and worktrees are separate projects; symlinks are not followed.
+  if (!existsSync(dir) || (dir !== root && existsSync(join(dir, ".git")))) return files;
   for (const entry of readdirSync(dir)) {
     if (SKIP.has(entry)) continue;
     const full = join(dir, entry);
-    if (statSync(full).isDirectory()) {
-      walkCodeFiles(full, files);
+    const st = lstatSync(full);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) {
+      walkCodeFiles(full, files, root);
     } else if (CODE_EXT.test(entry)) {
       files.push(full);
     }

package/lib/whitebox/secrets.js

@@ -1,7 +1,7 @@
 /**
  * Scan repository source for hardcoded secrets.
  */
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { readdirSync, readFileSync, lstatSync, existsSync } from "node:fs";
 import { join, relative } from "node:path";
 
 const SKIP_DIRS = new Set([
@@ -15,8 +15,10 @@ const SKIP_FILES = /\.(png|jpg|jpeg|gif|webp|ico|woff|woff2|ttf|eot|zip|tar|gz|p
 // dummy/probe credentials that security tooling (Penthera included) hardcodes
 // to test login endpoints, e.g. `password: "invalid-password-12345"`. Matched
 // against the assigned value only, with word boundaries so a real secret that
-// merely contains one of these substrings isn't suppressed.
-const TEST_VALUE = /\b(?:placeholder|example|changeme|dummy|sample|redacted|invalid|fake|test|your)\b|xxx|\*{3,}/i;
+// merely contains one of these substrings isn't suppressed. A value that is
+// only a template placeholder (`"${apiKey}"`, `"{{ api_key }}"`) holds no
+// secret either: it is filled in at runtime.
+const TEST_VALUE = /\b(?:placeholder|example|changeme|dummy|sample|redacted|invalid|fake|test|your)\b|xxx|\*{3,}|^\$\{[^}]+\}$|^\{\{[^}]+\}\}$/i;
 
 const SECRET_PATTERNS = [
   { name: "AWS access key", pattern: /AKIA[0-9A-Z]{16}/, severity: "critical" },
@@ -77,13 +79,24 @@ export function isSecretScanTarget(relPath) {
   return SCAN_EXTENSIONS.has(ext) || entry.startsWith(".env");
 }
 
-function walkFiles(dir, files = []) {
-  if (!existsSync(dir)) return files;
+// A subfolder with its own `.git` (a nested repo, submodule or worktree, such
+// as the ones coding agents create under .claude/worktrees) is a separate
+// project: scanning it would report its secrets as this repo's. Scan it on its
+// own instead. Symlinked folders are not followed, so a link cannot pull files
+// from outside the repo into the scan or loop forever.
+export function isNestedRepo(dir, root) {
+  return dir !== root && existsSync(join(dir, ".git"));
+}
+
+function walkFiles(dir, files = [], root = dir) {
+  if (!existsSync(dir) || isNestedRepo(dir, root)) return files;
   for (const entry of readdirSync(dir)) {
     if (SKIP_DIRS.has(entry)) continue;
     const full = join(dir, entry);
-    if (statSync(full).isDirectory()) {
-      walkFiles(full, files);
+    const st = lstatSync(full);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) {
+      walkFiles(full, files, root);
     } else if (!SKIP_FILES.test(entry)) {
       const ext = entry.includes(".") ? entry.slice(entry.lastIndexOf(".")) : "";
       if (SCAN_EXTENSIONS.has(ext) || entry.startsWith(".env")) files.push(full);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "penthera",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Open-source security for the apps and AI systems you ship. Check it before you deploy, vet what you build with (dependencies, MCP servers, skills), keep watching after you ship. Offline, deterministic, free.",
   "repository": {
@@ -49,10 +49,13 @@
     "validate:report": "node skills/penthera/scripts/validate-report.mjs",
     "package:skill": "bash scripts/package-skill.sh",
     "refresh:popular": "node scripts/refresh-popular-packages.mjs",
+    "refresh:popular-pypi": "node scripts/refresh-popular-pypi.mjs",
     "prepack": "npm test",
     "mock-server": "node tests/fixtures/mock-server.js",
     "bench": "node bench/run.js",
-    "refresh:retire-db": "node scripts/refresh-retire-db.mjs"
+    "docs:numbers": "node scripts/docs-numbers.mjs",
+    "refresh:retire-db": "node scripts/refresh-retire-db.mjs",
+    "audit:internal": "node scripts/audit/run.mjs"
   },
   "keywords": [
     "security",
@@ -78,7 +81,8 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
+    "fast-check": "^4.10.2",
     "vitest": "^5.0.5"
   },
   "dependencies": {

package/skills/penthera/SKILL.md

@@ -4,7 +4,7 @@ description: >
   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?",
+  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
@@ -19,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.5.0
+  version: 1.6.0
   category: security
 ---
 
@@ -80,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
 
@@ -270,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.
 
@@ -325,6 +327,22 @@ penthera hook run       # check what is staged now (exit 1 = blocked)
 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**