penthera 1.5.0 → 1.6.1

package/docs/use-cases/ai-coding-teams.md

@@ -0,0 +1,81 @@
+# The AI-tooling supply chain: for teams adopting Claude Code or Cursor
+
+## The problem
+
+A coding agent runs with your developer's permissions. What it can do is decided
+by files that rarely get reviewed: `.mcp.json`, `.claude/settings.json`, hooks,
+skills, plugins, `CLAUDE.md`, `AGENTS.md` and `.cursor/` rules. Some of these
+arrive from a teammate's pull request, some from a marketplace, some from a
+blog post. In 2025 and 2026 attackers used exactly these paths: skills with
+instructions hidden from human reviewers, MCP servers launched with `npx -y` on
+whatever version was latest, and npm worms that wrote to `~/.claude` and ran the
+`claude` CLI on the victim's machine.
+
+## What to run
+
+```bash
+npx penthera agents --home         # this repo plus your user-level Claude Code, Cursor and Claude Desktop config
+npx penthera agents ./some-skill   # vet a downloaded skill before you install it
+npx penthera agents --pin          # record hashes in penthera.lock; later runs show what changed
+```
+
+For a team, add the pre-commit hook so agent-config changes are checked before
+they are committed, and the GitHub Action in `agents` mode on pull requests:
+
+```bash
+npx penthera hook install
+```
+
+```yaml
+- uses: danoszz/penthera@<release-commit-sha>
+  with:
+    mode: agents
+```
+
+## What you get
+
+From Penthera's own test fixture of a deliberately bad setup (abridged):
+
+```
+  Grade       F  (0/100)
+  Found      1 skills · 4 MCP servers · 3 hooks · 0 plugins · 1 rule files
+  Lock       none (run with --pin)
+
+  CRIT  MCP server "installer" launches by downloading and running code
+         .mcp.json
+  CRIT  SessionStart hook downloads and runs code
+         .claude/settings.json
+  HIGH  Instructions hidden in an HTML comment
+         skills/helper/SKILL.md
+  HIGH  Text addressed to a security scanner
+         skills/helper/SKILL.md
+  HIGH  PreToolUse (*) hook auto-approves tool calls
+         .claude/settings.json
+  HIGH  Permission allow-list grants `Bash(*)`
+         .claude/settings.json
+  MED   MCP server "filesystem" runs an unpinned package via npx
+         .mcp.json
+```
+
+Each finding names the OWASP MCP Top 10 and Agentic Top 10 ids it maps to, and
+the rule that fired is readable in [`lib/agents/`](../../lib/agents/). The audit
+is offline and read-only: no model judges the skill, so a skill cannot talk its
+way past it. [More on `penthera agents`](../commands/agents.md).
+
+`penthera deps` also flags packages that write to `~/.claude`, `~/.cursor` or
+`.mcp.json`, or run the `claude`, `gemini` or `q` CLIs, which is how the
+s1ngularity attack used local AI tools. [More on `penthera deps`](../commands/deps.md).
+
+## What it does not do
+
+- It reads configuration and files on disk. It does not watch what an agent does
+  at run time, and it does not sandbox anything.
+- It does not know whether a remote MCP server is trustworthy. It checks how the
+  server is launched and configured, not what the service behind it does.
+- It does not check the registries for newly published malicious skills or
+  packages. A registry-watching service such as
+  [Socket](../compare/socket.md) covers that.
+- Its rules cover the patterns in the [methodology](../METHODOLOGY.md). A new
+  trick needs a new rule and a release.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/eu-sme-compliance.md

@@ -0,0 +1,68 @@
+# Evidence for NIS2 and the CRA: for EU SMEs
+
+## The problem
+
+NIS2 puts a duty of care on in-scope organisations, written into national law
+(the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium). The
+Cyber Resilience Act adds reporting duties for manufacturers of products with
+digital elements, with deadlines measured in hours. Large customers now send
+security questionnaires as part of procurement. A small company has to show
+that it tests, fixes and records, without a compliance team or a budget for a
+platform.
+
+## What to run
+
+```bash
+penthera --assessment-init assessment.json          # once: the organisational measures a scanner cannot test
+penthera https://staging.example.com --repo . \
+  --framework nis2 --readiness --assessment assessment.json \
+  --sbom sbom.cdx.json --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
+```
+
+That run writes the scan, an Article 21(2) coverage table, a readiness report
+with every measure marked met, partial, gap or not applicable, a CycloneDX SBOM,
+and a hashed, SSH-signed evidence bundle an auditor can verify with standard
+tools.
+
+Around it:
+
+```bash
+penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json
+penthera https://example.com --readiness --assessment assessment.json --questionnaire questions.txt
+penthera --cra-init cra.json && penthera --cra cra.json   # CRA Article 14 timeline and drafts
+penthera --repo . --aibom aibom.cdx.json                  # CycloneDX 1.6 AI-BOM
+```
+
+## What you get
+
+The CRA helper prints the deadlines and writes draft reports, marking every fact
+it still needs:
+
+```
+CRA Article 14 report drafts written to cra-reports.md
+  Early warning (24 hours): n/a, set aware_at
+  Vulnerability notification (72 hours): n/a, set aware_at
+  Final report (14 days after a corrective or mitigating measure is available): ...
+  ⚠️ No valid `aware_at` timestamp, so deadlines can't be computed. Set when you became aware (ISO 8601) and re-run.
+```
+
+The questionnaire helper answers each question from your scan and
+self-assessment, cites the evidence, and marks anything it cannot map as
+`NEEDS HUMAN INPUT` instead of guessing. Guides:
+[NIS2](../compliance-nis2.md), [CRA](../compliance-cra.md),
+[evidence bundles](../evidence.md).
+
+## What it does not do
+
+- It is readiness tooling, not a certification and not legal advice. Whether you
+  are in scope, and what is proportionate for you, is for you and your advisers
+  to decide.
+- It covers the technical, testable part of the duty of care. Policies,
+  training, backups and MFA come from your self-assessment; Penthera records
+  what you attest, it cannot check it.
+- It does not file anything. Reports to a CSIRT or ENISA are drafts for you to
+  review and submit.
+- Jurisdiction details ship for the Netherlands today; other member states are
+  configuration still to be added.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/open-source-maintainers.md

@@ -0,0 +1,75 @@
+# For open-source maintainers
+
+## The problem
+
+Your project is someone else's dependency. A compromised maintainer account, a
+malicious contributor pull request that bumps a lockfile, or a leaked publish
+token can turn it into the attack. Most maintainers do this unpaid, without a
+security budget, and many cannot send their dependency list or code to a vendor
+service, or would rather not sign up for one.
+
+## What to run
+
+On every pull request that touches the lockfile, comment what the change lets
+code do:
+
+```yaml
+- uses: danoszz/penthera@<release-commit-sha> # pin to a release commit
+  with:
+    mode: deps
+    fail-on: none
+```
+
+The full workflow, with permissions and a paths filter, is in
+[`docs/examples/pr-dependency-review.yml`](../examples/pr-dependency-review.yml).
+The action runs Penthera from its own checkout: no install from npm and no
+registry lookups. On pull requests from forks the token is read-only, so the
+diff goes to the job summary instead of a comment.
+
+Locally, before you cut a release:
+
+```bash
+npx penthera deps --base origin/main   # what changed in the tree since main
+npx penthera --repo .                  # secrets, including AI provider keys
+npx penthera agents                    # the agent config you ship (CLAUDE.md, .mcp.json, skills/)
+npx penthera hook install              # block secrets and risky config at commit time
+```
+
+## What you get
+
+```
+  ▲ net-helper 1.0.0 → 1.1.0  + network, whole environment
+      node_modules/net-helper/index.js:3  const https = require('https');
+      node_modules/net-helper/index.js:5  const body = JSON.stringify(process.env);
+```
+
+A patch release that starts reading the whole environment next to a network call
+is the shape of most credential-stealing packages. The diff shows it with
+`file:line` evidence, whether or not an advisory exists yet.
+[More on `penthera deps`](../commands/deps.md) and [the action](../commands/action.md).
+
+If your project ships agent skills or MCP configuration, `penthera agents` on
+your own repo is a reasonable release check too: it is what your users' tools
+will load.
+
+## How Penthera handles its own releases
+
+The same practices are worth copying. Penthera releases are published with npm
+provenance through trusted publishing and are staged: each version waits on npm
+until a maintainer approves it with 2FA. CI actions are pinned by SHA, CodeQL
+runs on every push, and the
+[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera)
+is public. See [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml).
+
+## What it does not do
+
+- Dependency analysis covers npm and Python. The install firewall and the
+  `--online` registry checks are npm only for now.
+- It does not track CVEs in your dependencies. Keep Dependabot or a similar
+  service on for that ([how they fit](../compare/github.md)).
+- It does not watch the registry for your package being republished by someone
+  else. Enable 2FA and trusted publishing on npm for that.
+- A capability is what code *can* do, not proof of intent. Many good packages
+  use the network; the diff is there so a person can look.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/solo-founder.md

@@ -0,0 +1,65 @@
+# Before launch: for solo founders and vibecoders
+
+## The problem
+
+You built the app in weeks, much of it with an AI assistant. It works. You have
+not had time to check the things that tend to go wrong in AI-written apps: an
+API route that returns any user's data if you change the id, an OpenAI key in a
+client bundle, a missing security header, a CORS policy of `*`, a login with no
+rate limit. Nobody on the team does security, because there is no team.
+
+## What to run
+
+Start the app locally, then:
+
+```bash
+npx penthera http://localhost:3000 --repo .   # the running app and its source, together
+npx penthera fix --plan --repo .              # fixes for what it can fix, as diffs
+npx penthera hook install                     # stop secrets at commit time from now on
+```
+
+Or ask your coding agent, with the [Agent Skill](../commands/skill.md)
+installed: "scan my app on localhost:3000 and fix what you find".
+
+Before you deploy, run the same scan against your preview URL. Only scan systems
+you own.
+
+## What you get
+
+```
+  Findings
+
+  HIGH  IDOR/BOLA: GET /api/users/{user_id}
+         http://localhost:3000/api/users/1 → 200
+  HIGH  OAuth open redirect
+         http://localhost:3000/api/oauth/callback?redirect_uri=... → 302
+  MED   Missing Content-Security-Policy
+  MED   No login rate limiting detected
+         http://localhost:3000/api/login → 401
+  LOW   Missing X-Frame-Options
+  INFO  Missing Referrer-Policy
+
+  ──────────────────────────────────────────────────────────
+  2 high · 5 medium · 2 low · 2 info
+```
+
+`penthera fix --plan` then prints a unified diff per fix it knows (security
+headers, cookie flags, a CORS allowlist, a login rate limit, moving a
+hardcoded secret to an environment variable) for Next.js, Express, Fastify and
+Hono. Nothing is written until you apply a plan by id, and the repo is
+re-scanned afterwards to confirm the finding is gone.
+[More on fixes](../commands/fix.md).
+
+## What it does not do
+
+- It is not a penetration test by a person. It checks known classes of problem;
+  it will not find a flaw in your business logic, such as a coupon that can be
+  applied twice.
+- It does not fix IDOR or auth design for you. It points at the route; the fix
+  is yours.
+- It does not watch production yet. Scheduled checks are on the
+  [roadmap](../../ROADMAP.md).
+- A clean scan is not proof of safety. Every finding has a confidence label, and
+  probes that could not run are listed as inconclusive rather than passed.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/lib/blackbox/email-dns.js

@@ -13,6 +13,7 @@
  * live DNS.
  */
 import { resolveTxt as dnsResolveTxt, resolveMx as dnsResolveMx } from "node:dns/promises";
+import { currentEgress } from "../../src/utils/http.js";
 
 const DEFAULT_RESOLVER = { resolveTxt: dnsResolveTxt, resolveMx: dnsResolveMx };
 
@@ -98,6 +99,10 @@ export function evaluateDmarc(txtRecords) {
  * @param {object} opts - { resolver }
  */
 export async function probeEmailDns(domain, opts = {}) {
+  // DNS queries go to resolvers, not the target: --offline forbids them.
+  if (currentEgress()?.offline) {
+    return { domain, spf: null, dmarc: null, dmarcPolicy: null, mxCount: 0, findings: [], skipped: "offline" };
+  }
   const resolver = opts.resolver || DEFAULT_RESOLVER;
   const findings = [];
 

package/lib/compliance/questionnaire.js

@@ -10,6 +10,8 @@
  * not a certification, and the owner must review every answer before sending.
  */
 
+import { mdInline } from "../../src/report/md-escape.js";
+
 // Keyword -> NIS2 measure. First match wins; order specific before general.
 const RULES = [
   { re: /\b(mfa|multi.?factor|two.?factor|2fa)\b/i, measure: "j" },
@@ -99,14 +101,14 @@ export function formatQuestionnaireMarkdown(result) {
     const basis = a.measure
       ? `(${a.measure}) ${a.status || "?"}${a.evidence?.length ? `: ${a.evidence.slice(0, 3).join(", ")}` : ""}`
       : "unmapped";
-    L.push(`| ${a.question.replace(/\|/g, "\\|")} | ${a.answer} | ${basis.replace(/\|/g, "\\|")} |`);
+    L.push(`| ${mdInline(a.question)} | ${mdInline(a.answer)} | ${mdInline(basis)} |`);
   }
   L.push("");
   const gaps = result.answers.filter((a) => a.answer === "NEEDS HUMAN INPUT").map((a) => a.question);
   if (gaps.length) {
     L.push("## Needs human input");
     L.push("");
-    gaps.forEach((q) => L.push(`- ${q}`));
+    gaps.forEach((q) => L.push(`- ${mdInline(q)}`));
     L.push("");
   }
   return L.join("\n");

package/lib/deps/capabilities.js

@@ -48,8 +48,30 @@ export const CAPABILITIES = {
     why: "Runs an AI coding CLI (claude, gemini, q), the pattern used by the s1ngularity attack to search the disk for secrets." },
   "token-harvest": { label: "GitHub token harvesting", severity: "critical", confidence: "likely",
     why: "Reads GitHub credentials: runs the gh CLI to print its token, reads gh's hosts file or git's credential store, or matches token-shaped strings next to network code." },
+  // Python only (lib/deps/python): code that runs whenever the interpreter starts, and unpickling.
+  "startup-hook": { label: "runs at Python startup", severity: "high", confidence: "confirmed",
+    why: "Ships a .pth file with an import line, or writes one. Python runs those lines on every interpreter start in that environment, a known persistence trick." },
+  deserialize: { label: "unpickles data", severity: "low", confidence: "likely",
+    why: "Loads pickle, marshal or unsafe YAML data, which runs code if the data is attacker-controlled." },
 };
 
+/** Python wording for capabilities whose npm description names npm or Node APIs. */
+const PY_WHY = {
+  "install-scripts": "Runs code at install time: a setup.py with custom commands, or an in-tree build backend, executes when pip builds the package from source.",
+  shell: "Can run arbitrary programs (subprocess, os.system, os.popen, pty).",
+  network: "Can open network connections (socket, urllib, requests, httpx, aiohttp and similar).",
+  env: "Reads os.environ.",
+  "env-bulk": "Serialises or enumerates all of os.environ, which holds tokens and keys.",
+  eval: "Builds code at runtime with eval, exec or compile.",
+  "dynamic-require": "Imports modules whose names are computed at runtime (__import__, importlib).",
+  native: "Ships native extensions (.so, .pyd) or loads libraries with ctypes, which this scanner cannot read.",
+  obfuscated: "Code looks deliberately hidden (encoded blobs or compressed payloads handed to exec, escape-heavy strings, PyArmor).",
+  "ai-cli-invoke": "Runs an AI coding CLI (claude, gemini, q) through a subprocess, the pattern used by the s1ngularity attack to search the disk for secrets.",
+};
+
+/** Why a capability matters, worded for the package's ecosystem. */
+export const capabilityWhy = (id, ecosystem) => (ecosystem === "pypi" && PY_WHY[id]) || CAPABILITIES[id]?.why || id;
+
 /** Stable display order. */
 export const CAPABILITY_ORDER = Object.keys(CAPABILITIES);
 
@@ -193,20 +215,25 @@ const GH_TOKEN_CMD_RE = new RegExp(j("\\bgh\\s+auth\\s+", "token\\b"));
 const GH_CRED_FILE_RE = new RegExp(`(?:${j("\\.git-", "credentials")}|${j("gh[/\\\\\\\\]", "hosts\\.yml")})`);
 const GH_TOKEN_REGEX_RE = new RegExp(`(?:${j("gh", "p_")}|${j("gh", "o_")}|${j("github", "_pat_")}|${j("gh", "\\[pousr")}|${j("gh", "\\[ps")})`);
 
+/** Attack-indicator patterns shared with the Python scanner (lib/deps/python). */
+export const INDICATORS = {
+  AI_CONFIG_RE, DESKTOP_CONFIG_RE, AI_CLIS, AI_CLI_FLAG_RE, GH_TOKEN_CMD_RE, GH_CRED_FILE_RE, GH_TOKEN_REGEX_RE,
+};
+
 const DECODE_RE = /\batob\s*\(|\bBuffer\.from\([^)]*['"`](?:base64|hex)['"`]|String\.fromCharCode\s*\(|\bdecodeURIComponent\s*\(\s*escape\s*\(/;
 
 const SUSPICIOUS_INSTALL_CMD = /\b(?:curl|wget|powershell|Invoke-WebRequest|iwr)\b|\|\s*(?:ba)?sh\b|base64\s+(?:-d|--decode)/i;
-const RISKY_FOR_INSTALL = ["network", "eval", "obfuscated", "env-bulk", "ai-config-write", "ai-cli-invoke", "token-harvest"];
+export const RISKY_FOR_INSTALL = ["network", "eval", "obfuscated", "env-bulk", "ai-config-write", "ai-cli-invoke", "token-harvest"];
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
-function snippet(line, idx) {
+export function snippet(line, idx) {
   const start = Math.max(0, idx - 40);
   const s = line.slice(start, start + 120).trim();
   return (start > 0 ? "…" : "") + s + (start + 120 < line.length ? "…" : "");
 }
 
-function add(caps, id, ev) {
+export function add(caps, id, ev) {
   const list = caps[id] || (caps[id] = { count: 0, evidence: [] });
   list.count++;
   if (list.evidence.length < MAX_EVIDENCE) list.evidence.push(ev);
@@ -228,7 +255,7 @@ export function entropy(s) {
  * Obfuscation signals for one file (comment-blanked code).
  * Returns { flagged, signals: string[], line }.
  */
-export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
+export function obfuscationSignals(code, { hasDynamicCode = false, evalRes = P.eval, decodeRe = DECODE_RE, strongEscapes = true } = {}) {
   const signals = [];
   let line = 1;
   let strong = 0;
@@ -243,7 +270,7 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   // Printable characters only: ANSI colour codes (\x1b) and control bytes are normal.
   const hexEsc = code.match(/\\x[2-7][0-9a-fA-F]/g);
   if (hexEsc && hexEsc.length >= 50 && (hexEsc.length * 4) / code.length >= 0.05) {
-    strong++;
+    if (strongEscapes) strong++;
     signals.push(`\\x escape density ${Math.round(((hexEsc.length * 4) / code.length) * 100)}%`);
     if (line === 1) line = lineOf(code, code.indexOf("\\x"));
   }
@@ -273,8 +300,8 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   let payload = null;
   if (blobs.length && hasDynamicCode) {
     const offsets = (res) => res.flatMap((re) => [...code.matchAll(new RegExp(re.source, "g"))].map((m) => m.index));
-    const evals = offsets(P.eval);
-    const decodes = offsets([DECODE_RE]);
+    const evals = offsets(evalRes);
+    const decodes = offsets([decodeRe]);
     const near = (b, list) => list.some((o) => o >= b.index - PAYLOAD_WINDOW && o <= b.end + PAYLOAD_WINDOW);
     payload = blobs.find((b) => near(b, evals) && near(b, decodes)) || null;
   }
@@ -287,14 +314,14 @@ export function obfuscationSignals(code, { hasDynamicCode = false } = {}) {
   return { flagged, signals, line };
 }
 
-function lineOf(code, idx) {
+export function lineOf(code, idx) {
   if (idx <= 0) return 1;
   let n = 1;
   for (let i = 0; i < idx; i++) if (code.charCodeAt(i) === 10) n++;
   return n;
 }
 
-function findLine(text, needle) {
+export function findLine(text, needle) {
   const lines = text.split("\n");
   for (let i = 0; i < lines.length; i++) if (lines[i].includes(needle)) return i + 1;
   return 1;
@@ -393,7 +420,7 @@ export function scanSource(src, file) {
   return { caps, exfil, aiConfigProject };
 }
 
-function mergeCaps(into, from) {
+export function mergeCaps(into, from) {
   for (const [id, v] of Object.entries(from)) {
     const t = into[id] || (into[id] = { count: 0, evidence: [] });
     t.count += v.count;
@@ -426,7 +453,9 @@ export function nodeScriptTargets(cmd) {
  * Scan a package through a source (see source.js).
  * @param {{ files(): string[], read(rel): Buffer, size(rel): number }} source
  * @param {{ prefix?: string }} opts prefix is prepended to evidence paths (e.g. node_modules/foo/)
- * @returns {{ name, version, capabilities, installScripts, exfil, filesScanned, skipped }}
+ * @returns {{ name, version, capabilities, installScripts, exfil, filesScanned, skipped, unscanned }}
+ *   unscanned: why the package could not be fully read (archive anomaly, no
+ *   package.json), else null. Callers must not treat such a package as clean.
  */
 export function scanPackage(source, opts = {}) {
   const prefix = opts.prefix || "";
@@ -434,10 +463,17 @@ export function scanPackage(source, opts = {}) {
   const files = source.files();
   let pkg = {};
   let pkgText = "";
+  // Install scripts come only from package.json, so a package whose archive or
+  // manifest could not be read is unscanned, never clean (fail closed).
+  let unscanned = source.anomaly || null;
   try {
     pkgText = source.read("package.json").toString("utf-8");
     pkg = JSON.parse(pkgText);
-  } catch { /* no or broken package.json */ }
+    if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) throw new Error("not an object");
+  } catch {
+    pkg = {};
+    unscanned = unscanned || "package.json is missing or not valid JSON, so its install scripts are unknown";
+  }
 
   const installScripts = {};
   for (const hook of INSTALL_HOOKS) {
@@ -519,5 +555,6 @@ export function scanPackage(source, opts = {}) {
     exfil,
     filesScanned,
     skipped,
+    unscanned,
   };
 }