penthera 1.7.0 → 1.8.0

package/src/utils/http.js

@@ -9,9 +9,14 @@
  * A scan runs inside an egress context (see `runWithEgress`). The context
  * names the scan target and records every host contacted, every request it
  * refused, and every probe request that failed. Under `offline: true` the
- * client refuses any host other than the target; a redirect may only move to
- * a host on the target's registrable domain. Outside a context (unit tests,
- * library use) requests are unrestricted and nothing is recorded.
+ * client refuses any host (or port) other than the target's; a redirect may
+ * only move to a host on the target's registrable domain. Outside a context
+ * (unit tests, library use) requests are unrestricted and nothing is recorded.
+ *
+ * Response bodies are read through `readBody`, which caps the decoded size
+ * and keeps the request's timeout running until the last byte, so a server
+ * that drips, floods or sends a decompression bomb cannot stall or exhaust a
+ * scan.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { readFileSync } from "node:fs";
@@ -19,6 +24,13 @@ import { registrableDomain } from "./url.js";
 
 const DEFAULT_TIMEOUT = 8_000;
 const MAX_REDIRECTS = 10;
+/** Default cap on a decoded response body (bytes). */
+export const DEFAULT_MAX_BODY = 5 * 1024 * 1024;
+// Set on every Response `request` returns: when its timeout expires, and how
+// to stop that timer once the body has been read.
+const BODY_DEADLINE = Symbol("penthera.bodyDeadline");
+// Request headers that carry credentials; never forwarded to another origin.
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
 const REPO_URL = "https://github.com/danoszz/penthera";
 
 const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8"));
@@ -47,9 +59,11 @@ export class EgressBlockedError extends Error {
  * @param {string[]} [opts.allowHosts] - extra hosts to allow under offline
  */
 export function createEgressContext(opts = {}) {
-  const targetHost = opts.target ? new URL(opts.target).hostname.toLowerCase() : null;
+  const target = opts.target ? new URL(opts.target) : null;
+  const targetHost = target ? target.hostname.toLowerCase() : null;
   return {
     targetHost,
+    targetPort: target ? effectivePort(target) : null,
     targetDomain: targetHost ? registrableDomain(targetHost) : null,
     offline: opts.offline === true,
     userAgent: opts.userAgent || DEFAULT_USER_AGENT,
@@ -85,18 +99,44 @@ function isThirdParty(ctx, host) {
  */
 export function checkEgress(url, opts = {}, ctx = currentEgress()) {
   if (!ctx || !ctx.offline) return { allowed: true };
-  let host;
+  let parsed;
   try {
-    host = new URL(url).hostname.toLowerCase();
+    parsed = new URL(url);
   } catch {
     return { allowed: false, reason: "unparseable URL" };
   }
-  if (host === ctx.targetHost || ctx.allowHosts.has(host)) return { allowed: true };
+  const host = parsed.hostname.toLowerCase();
+  if (ctx.allowHosts.has(host)) return { allowed: true };
+  const sameHost = host === ctx.targetHost;
   // A redirect may move within the target's registrable domain (apex -> www).
-  if (opts.redirect && ctx.targetDomain && !isIpLike(host) && registrableDomain(host) === ctx.targetDomain) {
+  const sameSite = opts.redirect && ctx.targetDomain && !isIpLike(host) && registrableDomain(host) === ctx.targetDomain;
+  if (!sameHost && !sameSite) {
+    return { allowed: false, reason: `${host} is not the scan target (${ctx.targetHost})` };
+  }
+  // Same host is not enough: another port is another service. The one
+  // exception is the scheme's default port on both sides (http -> https).
+  const port = effectivePort(parsed);
+  if (ctx.targetPort == null || port === ctx.targetPort || (isDefaultPort(port) && isDefaultPort(ctx.targetPort))) {
     return { allowed: true };
   }
-  return { allowed: false, reason: `${host} is not the scan target (${ctx.targetHost})` };
+  return { allowed: false, reason: `${host}:${port} is not the scan target (${ctx.targetHost}:${ctx.targetPort})` };
+}
+
+function effectivePort(u) {
+  if (u.port) return Number(u.port);
+  return u.protocol === "https:" ? 443 : u.protocol === "http:" ? 80 : null;
+}
+
+function isDefaultPort(port) {
+  return port === 80 || port === 443;
+}
+
+function sameOrigin(a, b) {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
 }
 
 function isIpLike(host) {
@@ -145,6 +185,10 @@ export async function request(url, opts = {}) {
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
+  const deadline = Date.now() + timeout;
+  // The timer keeps running after the headers arrive so the body is covered
+  // too; it is cleared here on failure or by readBody once the body is read.
+  let handedOff = false;
   const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
 
   let current = String(url);
@@ -164,25 +208,116 @@ export async function request(url, opts = {}) {
 
       const location = res.headers.get("location");
       const isRedirect = res.status >= 300 && res.status < 400 && location;
-      if (redirect !== "follow" || !isRedirect) return res;
+      const next = isRedirect ? new URL(location, current).toString() : null;
+      const crossOrigin = next && !sameOrigin(current, next);
+      // A 307/308 replays the method and body; never replay a body to
+      // another origin, hand the redirect back to the caller instead.
+      const replaysBody = (res.status === 307 || res.status === 308) && init.body != null;
+      if (redirect !== "follow" || !isRedirect || (crossOrigin && replaysBody)) {
+        handedOff = true;
+        timer.unref?.();
+        res[BODY_DEADLINE] = { at: deadline, release: () => clearTimeout(timer) };
+        return res;
+      }
       if (hop >= MAX_REDIRECTS) throw new Error(`too many redirects (${MAX_REDIRECTS})`);
 
       // Follow by hand so every hop passes the egress check.
       await res.body?.cancel().catch(() => {});
-      current = new URL(location, current).toString();
+      current = next;
       const method = (init.method || "GET").toUpperCase();
       if (res.status === 303 || ((res.status === 301 || res.status === 302) && method === "POST")) {
         init = { ...init, method: "GET", body: undefined };
       }
+      if (crossOrigin) {
+        // Credentials belong to the origin they were set for.
+        const headers = new Headers(init.headers);
+        for (const name of CREDENTIAL_HEADERS) headers.delete(name);
+        init = { ...init, headers };
+      }
     }
   } catch (err) {
     recordError(ctx, probe, current, err instanceof EgressBlockedError ? err.message : describeError(err, timeout));
     throw err;
+  } finally {
+    if (!handedOff) clearTimeout(timer);
+  }
+}
+
+/** Thrown by readBody when a body is too large or too slow. */
+export class BodyLimitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BodyLimitError";
+    this.code = "BODY_LIMIT";
+  }
+}
+
+/**
+ * Read a response body as text with a size cap and a deadline.
+ *
+ * Counts decoded bytes (after Content-Encoding), so a small compressed body
+ * that inflates past the cap is stopped as soon as it crosses it. The
+ * deadline defaults to the one `request` set from its `timeout`, so headers
+ * and body share one budget. Rejects with BodyLimitError on either limit and
+ * cancels the stream.
+ *
+ * @param {Response} res
+ * @param {{ maxBytes?: number, deadline?: number, timeout?: number, binary?: boolean }} [opts]
+ *   deadline: absolute epoch ms; timeout: ms from now. The earliest wins.
+ *   binary: return the raw bytes as a Buffer instead of text.
+ * @returns {Promise<string|Buffer>}
+ */
+export async function readBody(res, opts = {}) {
+  const { maxBytes = DEFAULT_MAX_BODY, binary = false } = opts;
+  const attached = res?.[BODY_DEADLINE];
+  let at = Infinity;
+  if (attached) at = attached.at;
+  if (opts.deadline != null) at = Math.min(at, opts.deadline);
+  if (opts.timeout != null) at = Math.min(at, Date.now() + opts.timeout);
+
+  let timer;
+  let reader;
+  try {
+    if (!res?.body) return binary ? Buffer.alloc(0) : "";
+    const declared = Number(res.headers?.get("content-length"));
+    if (!res.headers?.get("content-encoding") && declared > maxBytes) {
+      throw new BodyLimitError(`response body exceeds ${maxBytes} bytes`);
+    }
+    reader = res.body.getReader();
+    const expired = new Promise((_, reject) => {
+      if (at === Infinity) return;
+      timer = setTimeout(() => reject(new BodyLimitError("response body timed out")), Math.max(0, at - Date.now()));
+    });
+    expired.catch(() => {});
+
+    const decoder = new TextDecoder();
+    const parts = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await Promise.race([reader.read(), expired]);
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) throw new BodyLimitError(`response body exceeds ${maxBytes} bytes`);
+      parts.push(binary ? value : decoder.decode(value, { stream: true }));
+    }
+    if (binary) return Buffer.concat(parts);
+    parts.push(decoder.decode());
+    return parts.join("");
+  } catch (err) {
+    if (reader) reader.cancel().catch(() => {});
+    else res?.body?.cancel?.().catch(() => {});
+    throw err;
   } finally {
     clearTimeout(timer);
+    attached?.release();
   }
 }
 
+/** readBody, then JSON.parse. */
+export async function readJson(res, opts) {
+  return JSON.parse(await readBody(res, opts));
+}
+
 function safeHost(url) {
   try {
     return new URL(url).hostname.toLowerCase();
@@ -202,6 +337,20 @@ export async function safeFetch(url, opts = {}) {
   }
 }
 
+/**
+ * Fetch and parse JSON, never throwing: null on a network error, a non-2xx
+ * status, a body over `maxBytes`, or JSON that does not parse.
+ */
+export async function fetchJson(url, { maxBytes, ...opts } = {}) {
+  const res = await safeFetch(url, opts);
+  if (!res || !res.ok) return null;
+  try {
+    return await readJson(res, { maxBytes });
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Fetch helper that always returns status, body text, and headers
  * (null on failure).
@@ -210,7 +359,7 @@ export async function probeFetch(url, opts = {}) {
   const res = await safeFetch(url, opts);
   if (!res) return null;
 
-  const body = await res.text().catch(() => "");
+  const body = await readBody(res).catch(() => "");
   const headers = Object.fromEntries(res.headers.entries());
 
   return {
@@ -231,7 +380,7 @@ export async function fetchText(url, opts = {}) {
   const start = Date.now();
   try {
     const res = await request(url, opts);
-    const body = await res.text().catch(() => "");
+    const body = await readBody(res).catch(() => "");
     return {
       status: res.status,
       body,

package/docs/METHODOLOGY.md

@@ -1,375 +0,0 @@
-# Methodology
-
-## Abstract
-
-Penthera is an open-source, offline security scanner for web applications,
-their dependencies, and the AI tooling used to build them. This document
-specifies its method. It states the threat model, separates what black-box
-(HTTP) and white-box (repository) analysis can and cannot observe, and defines
-a four-level confidence model that distinguishes deterministic evidence from
-heuristic signals. It describes the false-positive controls built into each
-probe (randomized canaries, context-aware payload selection, baseline
-comparison, and repeated timing measurement) and the non-destructive defaults
-that follow from fail-safe design. Detection rules are distributed only in
-reviewed, versioned releases, never through a live feed, which removes an
-update channel from the attack surface. Each design choice is tied to prior
-research or a published standard. On a bundled benchmark of labelled local
-targets, Penthera reaches a precision of 0.86 and a recall of 0.90. Because the
-same authors wrote the scanner and the targets, these figures measure
-regressions, not accuracy on arbitrary applications.
-
-## How to cite
-
-If you use Penthera or this methodology in research or a report, cite the
-software. The metadata are in [CITATION.cff](../CITATION.cff), which GitHub
-renders as "Cite this repository".
-
-```text
-van der Zwaag, D. (2026). Penthera: An offline security scanner for web apps and AI-built code (Version 1.7.0) [Computer software]. https://github.com/danoszz/penthera
-```
-
-```bibtex
-@software{vanderzwaag2026penthera,
-  author  = {van der Zwaag, Daan},
-  title   = {Penthera: An Offline Security Scanner for Web Apps and {AI}-Built Code},
-  year    = {2026},
-  version = {1.7.0},
-  license = {MIT},
-  url     = {https://github.com/danoszz/penthera}
-}
-```
-
-Citations in this document follow APA 7th edition. Each one resolves to an
-entry in [references.md](references.md), generated from
-[references.bib](references.bib); a test fails if a citation has no entry or an
-entry is never cited. Measured accuracy is in
-[bench/RESULTS.md](../bench/RESULTS.md), and the method behind those numbers is
-in [bench/README.md](../bench/README.md).
-
-## Contents
-
-- [Threat model](#threat-model)
-- [Black-box and white-box: what each can find](#black-box-and-white-box-what-each-can-find)
-- [Confidence model](#confidence-model)
-- [False-positive controls](#false-positive-controls)
-- [Non-destructive by default](#non-destructive-by-default)
-- [Offline and no telemetry](#offline-and-no-telemetry)
-- [How new attack techniques are adopted](#how-new-attack-techniques-are-adopted)
-- [Citations in reports](#citations-in-reports)
-- [Known limitations](#known-limitations)
-
-## Threat model
-
-Penthera is built for small teams that ship web apps and APIs, often with AI
-coding tools, and need a first line of evidence before a human review or a paid
-penetration test. The threat model follows the four questions of Shostack
-(2014): what are we building, what can go wrong, what are we going to do about
-it, and did we do a good job.
-
-**Assets.** User data behind the API; credentials and API keys, including AI
-provider keys; the session and identity layer; and the integrity of the code and
-dependencies that get deployed.
-
-**Adversaries in scope.**
-
-1. A remote, unauthenticated attacker on the internet who can send arbitrary
-   HTTP requests to the deployed app. The black-box scan models this attacker.
-2. An authenticated user who tries to reach another user's data. Broken object
-   level authorization is the first item in the OWASP API Security Top 10
-   (OWASP Foundation, 2023). Penthera tests for it when given credentials.
-3. Anyone who obtains a copy of the source: a leaked repository, a public fork,
-   or a compromised CI log. Meli et al. (2019) found secrets leaked in over
-   100,000 public GitHub repositories, with thousands of new, unique secrets
-   leaked every day. The white-box secret scan models this adversary.
-4. A supply-chain attacker who publishes or compromises a dependency (Ladisa et
-   al., 2023; Ohm et al., 2020; Zimmermann et al., 2019), including packages
-   that code-generating models invent and attackers then register (Spracklen
-   et al., 2025).
-
-**Out of scope.** Physical access, insiders with production access, denial of
-service, social engineering, and anything that needs exploitation beyond a
-single benign probe. Penthera does not try to replace a human tester. It tries
-to find the issues a scanner can find reliably, and to say clearly which ones
-it cannot judge.
-
-**Penthera itself is in the threat model.** A security tool runs with the
-user's credentials and network position, so a compromised scanner is a
-compromised machine. Thompson (1984) showed that you cannot fully trust code you
-did not build yourself; the argument applies to scanners and their rule feeds.
-This is why Penthera fetches no rules at run time
-([below](#how-new-attack-techniques-are-adopted)).
-
-STRIDE, the threat taxonomy that Shostack's book builds on, originates at
-Microsoft (Kohnfelder & Garg, 1999). Penthera's probes map onto it as follows:
-
-| STRIDE category | Penthera coverage |
-|---|---|
-| Spoofing | Authentication, JWT, OAuth, email SPF and DMARC |
-| Tampering | Injection, CORS |
-| Repudiation | Not tested |
-| Information disclosure | Exposed files, secrets, verbose errors |
-| Denial of service | Not tested; only rate limiting is checked |
-| Elevation of privilege | IDOR/BOLA, client-side-only authorization |
-
-## Black-box and white-box: what each can find
-
-Penthera runs two kinds of analysis and reports them together.
-
-### Black-box (URL scan)
-
-The scanner sees only HTTP responses. Its tests are those of the OWASP Web
-Security Testing Guide (OWASP Foundation, n.d.-b); each probe's WSTG IDs are
-listed in [owasp-wstg-coverage.md](owasp-wstg-coverage.md).
-
-Black-box testing finds three kinds of issue well: properties visible in every
-response (missing security headers, TLS configuration, cookie flags, CORS
-policy), files and interfaces that should not be public, and injection flaws
-whose effect shows in the response or its timing. Protocol checks follow the
-relevant specifications: HSTS (Hodges et al., 2012), JWT (Jones et al., 2015;
-Sheffer et al., 2020), and OAuth redirect and PKCE handling (Fett et al., 2016;
-Lodderstedt et al., 2025; Sakimura et al., 2015).
-
-Two classic evaluations of black-box scanners show what this approach misses.
-Bau et al. (2010) tested eight commercial scanners against a custom vulnerable
-application and older versions of real ones. As a group the tools did
-reasonably well, but many of them missed second-order flaws such as stored XSS
-and stored SQL injection. Doupé et al. (2010) tested eleven commercial and
-open-source scanners against WackoPicko, a realistic purpose-built app with
-sixteen planted flaws. Every scanner missed eight of the sixteen, among them
-stored SQL injection, multi-step stored XSS, forceful browsing, and a business
-logic flaw. They concluded that crawling matters as much as detection: a
-scanner cannot test a page it never reaches, and losing track of state (logins,
-multi-step forms) is a main reason it does not reach it.
-
-Penthera's design responds to each point:
-
-- **Crawl coverage.** Endpoint discovery uses a wordlist plus the app's own
-  OpenAPI document when one is exposed, and records exactly which probes ran.
-  The WSTG coverage table in every report lists each test as run or not run, so
-  a missing check is never presented as a pass.
-- **State and logic.** Penthera does not claim to find business logic flaws,
-  which no scanner in the study by Doupé et al. (2010) found either. IDOR/BOLA
-  results are labelled `needs-human-review` because a scanner cannot know
-  whether user A is allowed to read object B.
-- **Stored and second-order flaws.** Not tested. They need a write followed by
-  a read elsewhere, which conflicts with the non-destructive default.
-
-### White-box (repository scan)
-
-The scanner reads source files. It finds hardcoded secrets, route handlers and
-their authentication boundaries, and risky code patterns.
-
-Secret detection uses provider-specific prefixes (for example `AKIA` for AWS
-and `sk-ant-` for Anthropic) plus a small number of assignment patterns such as
-`api_key = "..."` with a placeholder filter. Meli et al. (2019) took the same
-conservative route and restricted detection to private keys and API keys with
-distinctive formats. The cost is recall: a secret with no recognisable format
-is invisible to this approach. SecretBench, a labelled dataset of real secrets
-across many formats, is the natural yardstick for that gap (Basak et al.,
-2023). The bundled benchmark includes an unprefixed signing key that Penthera
-misses for this reason.
-
-White-box scanning cannot see runtime configuration (headers added by a CDN, a
-WAF in front of the app), secrets injected at deploy time, or anything in
-dependencies that is only known from a vulnerability database.
-
-### Combining them
-
-Running both against the same app catches cases neither sees alone: a route
-the repository marks as public that the black-box scan confirms is reachable,
-or a header the code sets that the edge strips. The report keeps the origin of
-each finding (`source`, `method`) so a reader can tell which side produced it.
-
-## Confidence model
-
-Severity says how bad a finding would be if real. Confidence says how likely it
-is to be real. Penthera reports both and never lets a heuristic look like a
-fact. The labels are defined in [lib/provenance.js](../lib/provenance.js):
-
-| Label | Meaning | Typical sources |
-|---|---|---|
-| `confirmed` | Deterministic evidence. The header is absent, the certificate expired, the key matches a provider format. | Header audit, TLS check, cookie audit, secret scan, OpenAPI exposure |
-| `likely` | A strong signal with a small false-positive chance. | Injection probes with a verified canary, auth and JWT probes, framework checks |
-| `potential` | A heuristic or one-shot signal that needs corroboration. | Fuzzer, adaptive probes |
-| `needs-human-review` | Exploitability cannot be judged from outside. | IDOR/BOLA, client-side-only auth |
-
-Every finding also carries `source`, `method`, and `collected_at`. These travel
-into SARIF, so the label survives into GitHub code scanning.
-
-The benchmark reports precision per confidence label, which tests whether the
-labels mean what they say. On the current run, all `likely` and
-`needs-human-review` findings were true positives and the one `potential`
-finding was a false positive. The two `confirmed` false positives are cases
-where the evidence is real but the judgement is wrong: a health endpoint that
-is public by design, and AWS's published example key. See
-[bench/RESULTS.md](../bench/RESULTS.md).
-
-## False-positive controls
-
-A black-box scanner loses trust through false positives faster than through
-misses. The probes apply these controls:
-
-- **Randomized canaries.** The SSTI probe multiplies two random four-digit
-  numbers and looks for the seven- or eight-digit product, and only when
-  neither the raw payload nor the literal expression appears in the response
-  ([lib/injections.js](../lib/injections.js), `buildSstiProbes`). The common
-  fixed canary `7*7 = 49` fires on any page that happens to contain "49". XSS
-  probes use a random reflection marker per probe (`makeCanary`).
-- **Context before payload.** The XSS probe first checks where its marker is
-  reflected (HTML body, attribute, or script), sends only payloads that would
-  execute in that context, and then checks that they came back unencoded.
-  Context-aware tools such as Dalfox take the same approach.
-- **Baseline comparison.** Error-based SQL injection is reported only when the
-  database error appears in the injected response and not in the baseline.
-- **Timing re-sampling.** A single slow response proves nothing: garbage
-  collection, cold starts, and network jitter all look like an injected sleep.
-  Time-based SQL and command injection candidates are re-sent and reported only
-  when the median delay holds (`confirmTimingDelay`). Crosby et al. (2009)
-  showed that network jitter dominates single remote timing measurements and
-  that filtering over many samples is what makes them usable, building on the
-  original timing attacks of Kocher (1996). Penthera's injected delays are
-  seconds, not microseconds, so a median of three samples is enough.
-- **Host-checked redirects.** An open redirect is reported only when the
-  `Location` header resolves to the attacker host, not when the payload merely
-  appears in the query string of a same-site redirect.
-- **Context-aware suppression.** On localhost and private hosts, findings that
-  do not apply there (no HTTPS, missing `Secure` on cookies) are suppressed.
-
-The benchmark's decoy target exercises each control with an endpoint built to
-fool a naive scanner. Writing it exposed one real flaw in the decoy itself: a
-"safe" redirect that accepted `/\evil.com`, which browsers treat as
-`//evil.com`. Penthera reported it correctly.
-
-## Non-destructive by default
-
-The `quick` and `standard` profiles send only requests a normal browser or API
-client would send: `GET`, `OPTIONS`, and invalid login attempts. They do not
-send attack payloads, create or modify data, or exploit anything they find.
-
-Payload-based testing (`--deep`, `--fuzz`, `--adaptive`, or `--profile deep`)
-is opt-in and gated behind a confirmation prompt. Even then, each probe sends a
-benign marker (a random string, an arithmetic expression, a short sleep, `id`)
-rather than a working exploit, and stops at the first confirmation per
-endpoint. The adaptive engine may send unexpected HTTP methods, including
-`DELETE`, to routes with placeholder IDs, so it is never part of a default run.
-
-This follows the principles of fail-safe defaults and least privilege set out by
-Saltzer and Schroeder (1975): the default does the least that is still useful,
-and anything riskier needs an explicit decision. NIST SP 800-115 draws the same
-line between non-intrusive assessment and penetration testing, and recommends
-written rules of engagement before the latter (Scarfone et al., 2008).
-
-## Offline and no telemetry
-
-Penthera does not phone home. It sends no usage data, analytics, or crash
-reports, and it has no accounts. Reports are written to local files.
-
-Network traffic goes to the target you name, with two documented exceptions:
-
-1. `--recon` (and the `deep` profile) queries public OSINT sources (crt.sh, the
-   Wayback Machine, AlienVault OTX) with the target domain. It is skipped for
-   localhost.
-2. The Retire.js check downloads the public Retire.js vulnerability database
-   from GitHub and compares JavaScript library versions locally. Outdated
-   client-side libraries are common on the web and often carry known
-   vulnerabilities (Lauinger et al., 2017). The database is data, not code: it
-   is parsed as JSON and never executed. It is the one place a detection input
-   arrives at run time. Under `--offline`, and whenever the download fails,
-   Penthera uses the snapshot vendored in the release instead.
-
-The benchmark enforces offline operation mechanically. It wraps `fetch` so any
-request to a non-loopback host is refused and counted, and it fails if the
-count is not zero.
-
-These choices follow the principles of economy of mechanism and complete
-mediation (Saltzer & Schroeder, 1975): fewer network paths mean fewer things to
-audit, and a tool that talks only to its target is easy to reason about in a
-regulated environment.
-
-## How new attack techniques are adopted
-
-Attack techniques change quickly. Recent examples include indirect prompt
-injection against LLM-integrated applications (Greshake et al., 2023; Liu et
-al., 2023; Perez & Ribeiro, 2022), package hallucination and slopsquatting
-(Spracklen et al., 2025), and attacks on agent tooling and MCP servers,
-catalogued by OWASP (OWASP Foundation, 2024, 2025a, 2025b) and in MITRE ATLAS
-(The MITRE Corporation, n.d.-b). A scanner that does not keep up gives a false
-sense of security.
-
-Penthera keeps up through reviewed releases, not live updates:
-
-- **Rules ship as code in a release.** New probes, patterns, and templates are
-  added by pull request, reviewed, tested against the benchmark, and published
-  in a versioned release with a CHANGELOG entry. There is no rule server, no
-  background update, and no command that fetches rules from the internet.
-- **Every new rule carries a source and a date.** A rule added after v1.2.0
-  records where the technique comes from (a paper, an advisory, an OWASP or
-  ATLAS entry, an incident write-up) and the date it was added. Finding
-  categories are already linked to their sources in
-  [lib/references.json](../lib/references.json); the built-in rules that
-  predate this policy are being backfilled.
-- **Every new rule comes with a benchmark case.** A detection rule is added
-  together with a labelled true positive and, where a false positive is
-  plausible, a decoy in [bench/](../bench/). The CI floor in the benchmark
-  stops a rule that adds false positives.
-- **Your own templates stay local.** `--nuclei <path>` and `--templates <dirs>`
-  load YAML templates from directories you choose. Penthera does not download
-  them.
-
-Why not update automatically? A rule feed is a code path from someone else's
-server into a tool that runs with your network access and often your
-credentials. Supply-chain research shows that update channels and package
-registries are exactly where attackers insert themselves (Ladisa et al., 2023;
-Ohm et al., 2020; Zimmermann et al., 2019), and that securing an update channel
-needs signed metadata, key rotation, and explicit trust delegation (Samuel et
-al., 2010; Torres-Arias et al., 2019). Shipping rules inside the signed,
-versioned package reuses the trust you already place in the release, and gives
-a clear audit trail: the rules you ran are the rules in the version you
-installed.
-
-## Citations in reports
-
-Each finding category maps to one to three references in
-[lib/references.json](../lib/references.json), chosen to explain why the
-finding matters. Besides the sources discussed above, these include the
-empirical work behind specific header and policy checks: Content Security
-Policy (Weichselbaum et al., 2016), cookie handling and cross-site request
-forgery (Barth et al., 2008), and CORS misconfiguration
-(Chen et al., 2018). Email authentication findings cite the SPF and DMARC
-specifications (Kitterman, 2014; Kucherawy & Zwicky, 2015). Injection,
-exposure, and configuration findings cite the OWASP Top 10 (OWASP Foundation,
-2021, 2025c), code-pattern findings cite the Common Weakness Enumeration (The
-MITRE Corporation, n.d.-a), and license findings use the identifiers of the
-SPDX License List (SPDX Workgroup, The Linux Foundation, n.d.).
-
-The references appear in two places:
-
-- in the Markdown report, as a "Why this matters / Sources" line under each
-  finding and a "Sources" line under each action-plan item;
-- in SARIF (Fanning & Golding, 2023), as the rule's `helpUri` (first source)
-  and `help` text (all sources), and as `properties.references` (the BibTeX
-  keys).
-
-[references.md](references.md) and the `sources` block of `references.json`
-are generated from [references.bib](references.bib) by
-`node scripts/build-references.mjs`, and a test fails if they drift.
-
-## Known limitations
-
-- No authenticated crawling beyond the bearer token or cookie you pass, so
-  pages behind multi-step flows are not reached (Doupé et al., 2010).
-- No stored or second-order injection testing (Bau et al., 2010).
-- No DOM-based XSS analysis, because Penthera does not run JavaScript (Lekies et
-  al., 2013; Stock et al., 2014).
-- No business logic testing. IDOR/BOLA findings need a human to confirm them.
-- Secret detection is pattern-based and skips Markdown and other documentation
-  files, so unprefixed secrets and secrets in notes are missed.
-- The bundled benchmark was written by the same people as the scanner. Its
-  numbers measure regressions and the false-positive controls, not accuracy on
-  arbitrary applications. Independent benchmarks such as the OWASP Benchmark
-  (OWASP Foundation, n.d.-a) and the benchmarking approach of Antunes and Vieira
-  (2010, 2015) are the model for a fairer comparison. Scoring against labelled
-  third-party targets (Juice Shop, crAPI) is the next step.
-- Compliance output for the NIS2 Directive (European Parliament and Council of
-  the European Union, 2022) is evidence toward a duty of care, not a
-  certification.

package/docs/commands/README.md

@@ -1,24 +0,0 @@
-# Commands
-
-One page per command, with every flag that matters and an example. The
-[README](../../README.md) has the short version; `penthera <command> --help`
-has the full flag list.
-
-| Command | Page | What it does |
-|---|---|---|
-| `penthera`, `penthera init` | [init.md](init.md) | Set up in one command: detect, check, then hook, workflow and dashboard |
-| `penthera <url>`, `--repo .` | [scan.md](scan.md) | Scan a running app and its source: modes, profiles, outputs, exit codes, CI |
-| `penthera agents` | [agents.md](agents.md) | Audit skills, MCP servers, hooks, plugins and rule files |
-| `penthera deps` | [deps.md](deps.md) | What each package can do, the upgrade diff, typosquats, license policy |
-| `penthera install` | [install.md](install.md) | Check a new package before any install script runs |
-| `penthera fix`, `penthera agent --loop` | [fix.md](fix.md) | Deterministic fix recipes and the local scan, fix, verify loop |
-| `penthera hook` | [hook.md](hook.md) | Pre-commit hook for secrets, agent config and dependency changes |
-| GitHub Action | [action.md](action.md) | The capability diff as a pull-request comment, plus SARIF |
-| Agent Skill | [skill.md](skill.md) | Let Claude Code, Cursor and other agents drive Penthera |
-| `penthera ui` | [dashboard.md](../dashboard.md) | The local dashboard: one view with projects, findings, side cards, and the fix loop from the page |
-
-Compliance flags (`--framework nis2`, `--readiness`, `--cra`, `--aibom`, ...)
-are covered in [compliance-nis2.md](../compliance-nis2.md) and
-[compliance-cra.md](../compliance-cra.md). Reports and evidence bundles are in
-[evidence.md](../evidence.md). Network use and `--offline` are in
-[privacy.md](../privacy.md).