@clear-capabilities/agentic-security-scanner 0.137.0 → 0.139.0

package/src/sast/rbac-consistency.js

@@ -14,7 +14,7 @@
 
 // Inline role checks — on the route's OWN registration line (middleware args).
 const INLINE_PATTERNS = [
-  /\b(?:requireRole|hasRole|hasAnyRole|checkRole|ensureRole|restrictTo|requireScope|hasAuthority|hasPermission|requirePermission)\s*\(\s*\[?\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
+  /\b(?:requireRole|hasRole|hasAnyRole|checkRole|ensureRole|restrictTo|requireScope|hasAuthority|hasPermission|hasAnyPermission|requirePermission|checkPermission|checkAnyPermission)\s*\(\s*\[?\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
   /\brole\s*(?:===?|==)\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
 ];
 // Decorator/attribute role checks — on the line(s) directly ABOVE the handler.

package/src/sast/redirect-toctou.js

@@ -0,0 +1,167 @@
+// PRD T4.4 + T4.5 — redirect/header-forwarding semantics, and validate-then-
+// resolve TOCTOU. 11 of the 96 root-caused real-world misses between them.
+//
+// WHY THESE ARE NOT ALREADY COVERED. Every existing "redirect" rule in this
+// codebase is CWE-601 open-redirect — the app sends an attacker-controlled
+// Location header. These are the OPPOSITE direction: the app is the CLIENT,
+// and the danger is what its own outbound request does when the SERVER
+// redirects it.
+//
+//   T4.4a (CWE-200) — credential headers survive an origin-changing redirect.
+//       `httpx.get(url, headers=auth_headers, follow_redirects=True)` replays
+//       Authorization to whatever host the first server names.
+//       (GHSA-r5vv-ff45-prp2, GHSA-4jc5-g844-4x33)
+//   T4.4b (CWE-918) — a validated URL is followed into redirect space with no
+//       per-hop re-validation, so the allow-list is checked once and bypassed
+//       on hop 2. (GHSA-c9hr-64h3-gxpc)
+//   T4.5  (CWE-367) — the value CHECKED and the value USED are resolved
+//       separately, so they can differ: DNS rebinding between an IP check and
+//       the connect, or a re-resolved path after a containment check.
+//       (GHSA-ch52-px8q-f22j, GHSA-vx7x-vcc2-c44g)
+//
+// Precision comes from requiring the mitigation to be ABSENT: each rule names
+// the specific control the real fix added, and stays silent when it is present.
+import { blankComments } from './_comment-strip.js';
+
+const SRC_RE = /\.(?:py|js|jsx|ts|tsx|mjs|cjs)$/i;
+
+/** An outbound HTTP call that can be told to follow redirects. */
+const CLIENT_CALL_RE =
+  /\b(?:requests|httpx|session|client|axios|got|fetch|urlopen|request)\b[\w.]{0,40}\s{0,4}\(([^;]{0,400})/gi;
+
+/** Redirect-following turned on (explicitly, or by a library that defaults to it). */
+const FOLLOWS_REDIRECTS_RE = /\b(?:follow_redirects\s{0,4}=\s{0,4}True|allow_redirects\s{0,4}=\s{0,4}True|maxRedirects\s{0,4}:\s{0,4}[1-9]|redirect\s{0,4}:\s{0,4}['"]follow['"])/;
+
+/** Credential-bearing headers handed to that call. */
+const CREDENTIAL_HEADER_RE = /\b(?:headers|auth|Authorization|Cookie|api_?key|bearer|token)\b/i;
+
+/** The T4.4a mitigation: headers stripped or rescoped across the hop. */
+const HEADER_STRIP_RE =
+  /\b(?:_?redirect_headers|strip_?(?:auth|headers)|rebuild_auth|same_?origin|origin\s{0,4}[!=]==?|del\s+headers|headers\.pop|headers\.delete|drop_?headers)\b/i;
+
+/** The T4.4b mitigation: the target is re-checked per hop, not once up front. */
+const PER_HOP_CHECK_RE =
+  /\b(?:on_?redirect|beforeRedirect|redirect_?hook|validate_?redirect|check_?redirect|per_?hop|for\s+hop\b)/i;
+
+/** A one-time URL/host validation — the thing that gets bypassed. */
+const URL_VALIDATION_RE =
+  /\b(?:validate_?url|check_?url|is_?allowed|allow_?list|allowlist|deny_?list|is_?private|is_?internal|ssrf|_validate_url_for_fetch)\w{0,20}\s{0,4}\(/i;
+
+/** T4.5: a resolution whose result is checked. */
+const RESOLVE_RE = /\b(?:getaddrinfo|gethostbyname|resolve|\w*[dD]ns\w*\.lookup|socket\.getaddrinfo|realpath|os\.path\.realpath|resolve\(\))\b/i;
+
+/** T4.5 mitigation: the checked result is PINNED and reused, not re-resolved. */
+const PIN_RE = /\b(?:pin|pinned|resolved_?ip|cached_?ip|use_?resolved|connect_?to_?ip|sock\.connect\(\s*\(?\s*resolved)/i;
+
+/**
+ * T4.5's OTHER mitigation shape, found via GHSA-ch52-px8q-f22j: instead of
+ * pinning the checked value, the fix installs a custom resolver/lookup hook so
+ * the SAME resolution used to connect is the one that gets validated — a
+ * connect-time revalidation gate rather than a cache. Window-scoped like PIN_RE
+ * would miss this: the hook is typically a sibling function, not adjacent to
+ * the original resolve-and-check call it supersedes. File-scoped is safe here
+ * because assignment to `.lookup`/`.resolveLookup`/an http(s) agent's `lookup`
+ * option is a specific code shape, not a word that appears in prose or pattern
+ * tables the way "resolve" or "getaddrinfo" do.
+ */
+const CONNECT_TIME_REVALIDATION_RE = /\.\s{0,2}(?:lookup|resolveLookup)\s{0,4}=\s{0,4}(?:async\s{1,4})?\(/;
+
+const _lineOf = (raw, i) => raw.slice(0, i).split('\n').length;
+const _win = (raw, line, half = 14) => {
+  const l = raw.split('\n');
+  return l.slice(Math.max(0, line - 1 - half), Math.min(l.length, line - 1 + half)).join('\n');
+};
+
+function mk(file, line, sub, severity, cwe, vuln, description, remediation, checkedFor) {
+  return {
+    id: `redirect-toctou:${sub}:${file}:${line}`,
+    file, line, vuln, severity, cwe,
+    family: sub === 'toctou-resolve' ? 'toctou' : 'redirect-forwarding',
+    parser: 'REDIRECT-TOCTOU',
+    subfamily: sub,
+    confidence: 0.5,
+    description, remediation, checkedFor,
+  };
+}
+
+export function scanRedirectToctou(file, raw) {
+  if (!raw || typeof raw !== 'string' || raw.length > 500_000) return [];
+  if (!SRC_RE.test(file)) return [];
+  if (!/redirect|getaddrinfo|gethostbyname|realpath|resolve/i.test(raw)) return [];
+  const code = blankComments(raw, /\.py$/i.test(file) ? 'py' : null);
+  const out = [];
+  const seen = new Set();
+  const push = (f) => { const k = `${f.subfamily}:${f.line}`; if (!seen.has(k)) { seen.add(k); out.push(f); } };
+
+  CLIENT_CALL_RE.lastIndex = 0;
+  let m;
+  while ((m = CLIENT_CALL_RE.exec(code))) {
+    const argsText = m[1] || '';
+    const line = _lineOf(code, m.index);
+    const win = _win(raw, line);
+    if (!FOLLOWS_REDIRECTS_RE.test(argsText) && !FOLLOWS_REDIRECTS_RE.test(win)) continue;
+
+    // T4.4a — credentials handed to a redirect-following request, with no
+    // evidence anywhere nearby that headers are dropped when the origin changes.
+    if (CREDENTIAL_HEADER_RE.test(argsText) && !HEADER_STRIP_RE.test(win)) {
+      push(mk(file, line, 'credential-across-redirect', 'medium', 'CWE-200',
+        'Credential headers forwarded across an origin-changing redirect',
+        'This request carries credential headers AND follows redirects, and nothing in the surrounding code drops '
+        + 'those headers when the redirect changes origin. Most HTTP clients only strip Authorization and Cookie by '
+        + 'default, so a custom header (X-Api-Key, X-Auth-Token) is replayed verbatim to whatever host the first '
+        + 'server names — handing the caller\'s credentials to a third party that merely had to answer with a 302.',
+        'Drop every credential header when the redirect target\'s origin differs from the original request\'s, or '
+        + 'disable redirect-following and handle each hop explicitly.',
+        'a header-stripping / same-origin check within 14 lines'));
+    }
+
+    // T4.4b — the URL was validated once, then followed wherever it leads.
+    if (URL_VALIDATION_RE.test(win) && !PER_HOP_CHECK_RE.test(win)) {
+      push(mk(file, line, 'unvalidated-redirect-hop', 'medium', 'CWE-918',
+        'URL allow-list checked once, then redirects followed without re-validation',
+        'The target URL is validated before the request, but redirects are followed and nothing re-validates the '
+        + 'destination of each hop. An allowed host can answer with a 302 to an internal address, so the check '
+        + 'protects only the first hop — the classic SSRF allow-list bypass.',
+        'Re-run the same host validation on every redirect hop (a redirect hook / per-hop callback), or follow '
+        + 'redirects manually so each Location can be checked before it is fetched.',
+        'a per-hop redirect hook or re-validation within 14 lines'));
+    }
+  }
+
+  // T4.5 — resolve, check the result, then let the consumer resolve again.
+  //
+  // LOCALITY IS REQUIRED. The first draft asked whether the file ANYWHERE
+  // contained a resolve, a validation, and no pin — and immediately fired on
+  // two of this project's own detector modules, whose rule tables mention
+  // getaddrinfo/is_allowed as pattern DATA rather than performing either. A
+  // real TOCTOU has the resolve and the check in the same handful of lines,
+  // so the window is the unit, not the file.
+  // The resolved value must be BOUND to a name and that same name checked —
+  // window co-occurrence alone was still too loose (it fired on catalog.js and
+  // two structural detectors, whose rule tables merely mention these APIs).
+  const RESOLVE_BIND_RE = /\b(\w{1,60})\s{0,4}=\s{0,4}[^\n]{0,120}\b(?:getaddrinfo|gethostbyname|\w*[dD]ns\w*\.lookup|realpath)\b/g;
+  let rmm;
+  while ((rmm = RESOLVE_BIND_RE.exec(code))) {
+    const bound = rmm[1];
+    const line = _lineOf(code, rmm.index);
+    const win = _win(raw, line, 10);
+    // That exact name must be what the validation looks at.
+    const checked = new RegExp(`${URL_VALIDATION_RE.source.replace(/^\\b/, '\\b')}[^)]{0,80}\\b${bound}\\b`, 'i');
+    if (!checked.test(win)) continue;             // the resolved value is not what is checked
+    if (PIN_RE.test(win)) continue;               // the checked value is reused — the fix
+    if (CONNECT_TIME_REVALIDATION_RE.test(code)) continue; // a custom lookup hook revalidates at connect time — the other fix
+    push(mk(file, line, 'toctou-resolve', 'medium', 'CWE-367',
+      'Validated address is re-resolved before use (TOCTOU / DNS rebinding)',
+      'A name is resolved and the result is validated, but the resolved value is not pinned — the connection (or '
+      + 'file open) resolves the name a second time. Between the two resolutions the answer can change, so the '
+      + 'address that was checked is not the address that is used. For DNS this is rebinding: the attacker answers '
+      + 'once with a public IP to pass the check and once with an internal one to be connected to.',
+      'Pin the validated result and use it directly (connect to the checked IP, open the checked realpath) instead '
+      + 'of re-resolving the original name.',
+      'evidence that the validated result is pinned and reused rather than re-resolved'));
+    break;   // one finding per file is enough to act on
+  }
+  return out;
+}
+
+export const _internals = { FOLLOWS_REDIRECTS_RE, HEADER_STRIP_RE, PER_HOP_CHECK_RE, URL_VALIDATION_RE, PIN_RE, CONNECT_TIME_REVALIDATION_RE };

package/src/sast/resource-exhaustion.js

@@ -0,0 +1,217 @@
+// PRD T4.2 — resource exhaustion from an unbounded, externally-influenced size.
+//
+// The largest unimplemented class in the evidence table: 14 of the 96
+// root-caused real-world misses. Distinct from ReDoS (redos-nfa.js covers
+// regex backtracking only, and correctly returned "safe" for a real
+// polynomial-split() DoS) and from injection — nothing is escaped or
+// concatenated here. The bug is that a value which the caller controls is used
+// as an ALLOCATION or ITERATION size with no upper bound on any path.
+//
+// Shapes drawn from the real entries:
+//   pypdf   — a /W CID-width array's start..stop range expanded into a dict,
+//             one key per index, with no cap (CWE-834).
+//   pypdf   — a CMap token length with no ceiling (CWE-400).
+//   thumbor — `new_width = source_width * value` from a URL filter argument
+//             with no upper bound (CWE-400).
+//   mermaid — an unbounded `ticks` from parsed diagram text driving render
+//             geometry (CWE-606).
+//
+// PRECISION IS THE WHOLE GAME. "A number is used as a size" describes most
+// code ever written, so this fires only when ALL of the following hold:
+//   1. the size derives from a recognised EXTERNAL surface (a request/params
+//      object, a parsed document field, or a function parameter that reaches
+//      the operation unmodified) — never a local constant;
+//   2. the value reaches a bounded-cost operation (range/repeat/allocation);
+//   3. no comparison against an upper bound appears anywhere in the enclosing
+//      window.
+// Condition 3 is what keeps it quiet: a single `if (n > MAX)` silences it, and
+// that is exactly the fix each of these advisories shipped — so the detector
+// discriminates the fixed revision from the vulnerable one by construction.
+import { blankComments } from './_comment-strip.js';
+
+const PY_RE = /\.py$/i;
+const JS_RE = /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i;
+
+/** External surfaces whose values a caller can choose. */
+const EXTERNAL_RE = /\b(?:request|req|params|query|body|args|argv|options|opts|payload|form|headers|data|spec|config|input|user_input|kwargs)\b/;
+
+/**
+ * An upper-bound check that actually applies to the size-controlling
+ * identifier — the mitigation. GHSA-phj3-59pf-cp83's PRE revision already
+ * contains `if new_width < 1 or new_height < 1: return`, a lower-bound
+ * sanity check on the DERIVED value, not a ceiling on the source `value`.
+ * An identifier-agnostic `[<>]=?\s{0,4}\d` match treated that as the fix and
+ * silenced the finding on both pre/ and post/. The comparison-based
+ * alternatives now require the identifier itself; the keyword-based ones
+ * (min/max/clamp/raise/...) stay window-scoped — those tokens are
+ * distinctive enough on their own that binding them to one identifier would
+ * just miss the common `n = min(n, MAX)` reassignment shape.
+ */
+const BOUND_KEYWORDS_RE = new RegExp([
+  '\\bmin\\s{0,4}\\(', '\\bMath\\.min\\s{0,4}\\(',
+  '\\bmax_\\w{1,40}\\b', '\\bMAX_\\w{1,40}\\b', '\\blimit\\b', '\\bcap\\b',
+  '\\bclamp\\b', '\\bslice\\s{0,4}\\(', '\\bislice\\s{0,4}\\(',
+  '\\braise\\b', '\\bthrow\\b',
+].join('|'), 'i');
+function _isBounded(id, win) {
+  if (BOUND_KEYWORDS_RE.test(win)) return true;
+  if (!id) return false;
+  const esc = String(id).split('.')[0].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const named = new RegExp(
+    `\\b${esc}\\b\\s{0,4}[<>]=?\\s{0,4}(?:\\d|[A-Z_]{2,40}\\b)|(?:\\d+|[A-Z_]{2,40})\\s{0,4}[<>]=?\\s{0,4}\\b${esc}\\b`,
+    'i');
+  return named.test(win);
+}
+
+/**
+ * Bounded-cost operations: allocate or iterate proportional to a value.
+ *
+ * `candidates` returns every identifier the match could be sized from, when
+ * more than one is plausible (a multiplication's two operands). Without it,
+ * only the FIRST non-empty capture group was ever tested — GHSA-phj3-59pf-cp83
+ * (`new_width = source_width * value`) happened to pass anyway because
+ * `source_width`'s own assignment line mentions `request`, but a version with
+ * the constant on the left (`n = CONSTANT * value`) would have silently
+ * skipped `value`, the actual caller-controlled operand, forever.
+ */
+const PY_SIZE_OPS = [
+  { re: /\brange\s*\(([^)]{1,200})\)/g, what: 'range()' },
+  { re: /\b(\w{1,60})\s*\*\s*(\w{1,60})\b(?=\s*(?:\)|,|$|\n))/g, what: 'multiplication used as a size', candidates: m => [m[1], m[2]] },
+  { re: /\[\s*[^\]]{0,60}\s*\]\s*\*\s*(\w{1,60})/g, what: 'list repetition' },
+  { re: /\bbytearray\s*\(([^)]{1,120})\)/g, what: 'bytearray()' },
+];
+/**
+ * A loop bounded by an input's OWN `.length`/`.size` iterates exactly what
+ * the process already holds in memory — it allocates nothing beyond that, so
+ * it isn't the CWE-400 shape this rule targets. Every parser in existence
+ * loops `for (i = 0; i < input.length; i++)`; flagging that would make the
+ * rule fire on essentially all parsing code. Exposed by the identifier-scoped
+ * `_isBounded` fix above no longer being coincidentally silenced by an
+ * unrelated comparison elsewhere in the window.
+ */
+const LENGTH_BOUND_RE = /\.(?:length|size|len|byteLength)$/i;
+const JS_SIZE_OPS = [
+  { re: /\bnew\s+Array\s*\(([^)]{1,120})\)/g, what: 'new Array()' },
+  { re: /\.repeat\s*\(([^)]{1,120})\)/g, what: '.repeat()' },
+  { re: /\bBuffer\.alloc\w{0,10}\s*\(([^)]{1,120})\)/g, what: 'Buffer.alloc()' },
+  { re: /for\s*\([^;]{0,80};[^;]{0,80}<\s*([\w.]{1,60})\s*;/g, what: 'loop bound', skip: expr => LENGTH_BOUND_RE.test(expr.trim()) },
+];
+
+const _lineOf = (raw, idx) => raw.slice(0, idx).split('\n').length;
+const _window = (raw, line, half = 12) => {
+  const l = raw.split('\n');
+  return l.slice(Math.max(0, line - 1 - half), Math.min(l.length, line - 1 + half)).join('\n');
+};
+
+/**
+ * A generic (non-staticmethod/property/etc.) decorator marks a function as
+ * invoked BY something else across a trust boundary — a route, a filter, a
+ * task queue, a validator. Its parameters are as externally-influenced as a
+ * literal `req`/`params` name, without needing to guess a naming convention.
+ * GHSA-phj3-59pf-cp83's `value` (a `@filter_method`-decorated parameter) is
+ * the case this exists for; EXTERNAL_RE's fixed vocabulary cannot express it.
+ */
+const NON_HANDLER_DECORATOR_RE = /^@(?:staticmethod|classmethod|property|dataclass|lru_cache|cached_property|abstractmethod|overload|wraps|final|override)\b/i;
+/** Cheap top-level gate: any indented `@decorator` line at all. */
+const HAS_DECORATOR_RE = /^[ \t]{0,20}@[A-Za-z_]/m;
+const _handlerDefRe = () => /@([\w.]+)[^\n]{0,200}\n\s{0,20}(?:async\s{1,4})?def\s{1,4}\w{1,60}\s{0,4}\(([^)]{0,400})\)/g;
+function _isHandlerParam(name, code, idx) {
+  if (!name || /^(?:self|cls)$/.test(name)) return false;
+  const re = _handlerDefRe();
+  let last = null, m;
+  while ((m = re.exec(code)) && m.index < idx) last = m;
+  if (!last) return false;
+  if (NON_HANDLER_DECORATOR_RE.test('@' + last[1])) return false;
+  const params = String(last[2]).split(',').map(p => p.trim().split(/[:=]/)[0].replace(/^\*{1,2}/, '').trim());
+  return params.includes(name);
+}
+
+/**
+ * Does this size expression trace to something a caller chooses, within the
+ * enclosing window? Deliberately window-scoped rather than flow-sensitive:
+ * this is a structural detector, and the taint engine already owns real flow.
+ */
+function _externallyInfluenced(sizeExpr, win, code, matchIdx) {
+  const idents = String(sizeExpr).match(/[A-Za-z_$][\w$.]{0,60}/g) || [];
+  for (const id of idents) {
+    if (/^\d+$/.test(id)) continue;
+    // A BARE (unqualified) 'headers' is as likely to be a local variable —
+    // a table's column headers, a config section name — as an HTTP request's
+    // headers; scripts/nist-compliance/scan.py's ASCII-table renderer has
+    // exactly this shape (`for i in range(len(headers))`). Requiring
+    // qualification (`req.headers`) keeps the word useful without matching
+    // every unrelated local var that happens to share its name.
+    if (id !== 'headers' && EXTERNAL_RE.test(id)) return id;   // params.count / req.headers
+    // Assigned from an external surface nearby: `n = data["count"]`
+    const bare = id.split('.')[0];
+    const assigned = new RegExp(`\\b${bare.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\s{0,4}=[^=]{0,120}`, 'g');
+    for (const m of win.match(assigned) || []) if (EXTERNAL_RE.test(m)) return id;
+    if (code && _isHandlerParam(bare, code, matchIdx)) return id;
+  }
+  return null;
+}
+
+function _scan(file, raw, code, ops) {
+  const out = [];
+  const seen = new Set();
+  for (const { re, what, candidates, skip } of ops) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(code))) {
+      const exprCandidates = candidates ? candidates(m) : [m[1] || m[2] || ''];
+      if (skip && exprCandidates.some(skip)) continue;
+      const line = _lineOf(code, m.index);
+      const key = `${line}`;
+      if (seen.has(key)) continue;
+      const win = _window(raw, line);
+      let source = null;
+      for (const sizeExpr of exprCandidates) {
+        if (!sizeExpr || /^['"]/.test(sizeExpr.trim())) continue;
+        source = _externallyInfluenced(sizeExpr, win, code, m.index);
+        if (source) break;
+      }
+      if (!source) continue;                                    // not caller-chosen
+      // Bounding EITHER operand bounds the product/size, so check every
+      // candidate identifier, not just the one that proved external. GHSA-
+      // phj3-59pf-cp83's fix caps `value`, but `source_width` (checked first
+      // above, since its own assignment line visibly mentions `request`) is
+      // what got identified as the external source — checking only that one
+      // identifier for a bound would miss a fix applied to its sibling.
+      const allIdents = exprCandidates.flatMap(c => String(c).match(/[A-Za-z_$][\w$.]{0,60}/g) || []);
+      if (allIdents.some(id => _isBounded(id, win))) continue; // already bounded — the fix
+      seen.add(key);
+      out.push({
+        id: `resource-exhaustion:unbounded-size:${file}:${line}`,
+        file, line,
+        vuln: `Unbounded resource allocation — ${what} sized from caller-controlled '${source}' with no upper bound`,
+        severity: 'medium',
+        cwe: 'CWE-400',
+        family: 'resource-exhaustion',
+        parser: 'RESOURCE',
+        confidence: 0.5,
+        description:
+          `The size of ${what} derives from '${source}', which a caller can choose, and no upper-bound check ` +
+          'appears in the surrounding code. A large value forces proportional memory or CPU use, so a single ' +
+          'request can exhaust the process — a denial of service that needs no injection and no malformed input, ' +
+          'just a big number.',
+        remediation:
+          `Clamp the value before it is used as a size (e.g. \`n = min(n, MAX_${String(what).replace(/\\W/g, '').toUpperCase().slice(0, 12)})\`) ` +
+          'or reject it with an explicit error when it exceeds the documented maximum.',
+        checkedFor: 'an upper-bound comparison, min()/clamp, or an explicit raise/throw within 12 lines',
+      });
+    }
+  }
+  return out;
+}
+
+export function scanResourceExhaustion(file, raw) {
+  if (!raw || typeof raw !== 'string' || raw.length > 500_000) return [];
+  const isPy = PY_RE.test(file), isJs = JS_RE.test(file);
+  if (!isPy && !isJs) return [];
+  if (!EXTERNAL_RE.test(raw) && !(isPy && HAS_DECORATOR_RE.test(raw))) return []; // cheap relevance gate
+  const code = blankComments(raw, isPy ? 'py' : null);
+  try { return _scan(file, raw, code, isPy ? PY_SIZE_OPS : JS_SIZE_OPS); }
+  catch { return []; }
+}
+
+export const _internals = { EXTERNAL_RE, BOUND_KEYWORDS_RE, _isBounded, _externallyInfluenced, _isHandlerParam, NON_HANDLER_DECORATOR_RE };

package/src/sast/sibling-guard.js

@@ -0,0 +1,176 @@
+// Sibling-guard omission — CWE-22.
+//
+// THE SHAPE, taken from a real advisory rather than from prose. GHSA-95cv-r8x4-vh75
+// (alist): a batch-rename handler reads two fields off the same request object
+// and passes only one of them through the project's own path guard.
+//
+//     for _, renameObject := range req.RenameObjects {
+//         err := checkRelativePath(renameObject.NewName)   // guarded
+//         if err != nil { ... return }
+//         filePath := fmt.Sprintf("%s/%s", reqPath, renameObject.SrcName)  // NOT guarded
+//         fs.Rename(ctx, filePath, renameObject.NewName)
+//     }
+//
+// The upstream fix adds `checkRelativePath(renameObject.SrcName)` above the
+// existing call. Two lines, one sibling field.
+//
+// WHY THIS IS HIGH PRECISION BY CONSTRUCTION. The rule never decides what a
+// guard is. It OBSERVES the codebase applying some function to one field and
+// then finds a sibling field of the SAME receiver, in the SAME function, that
+// reaches a path-ish operation without it. The claim is therefore always
+// "this file guards X and forgets Y" — falsifiable by a reviewer looking at one
+// screen of code, with the guard name and both fields carried on the finding.
+// It is the intra-function form of the argument `convention-deviation.js` makes
+// at project scope.
+//
+// Deliberately NOT modelled:
+//   · guards applied through a wrapper or in a callee — a cross-function version
+//     needs the taint engine's summaries, and inflating this rule to guess at it
+//     would trade the property that makes it credible.
+//   · languages beyond Go. The shape is general, but the measured need is Go
+//     (0/72 on the independent population), and each language needs its own
+//     field-access and sink vocabulary verified against real code first.
+//
+// Found via the F1.1 root-cause histogram: this entry was one of 12 of 25 Go
+// entries where the vulnerable file produced NO finding of any kind.
+
+const GO_FILE_RE = /\.go$/i;
+
+// `ident.Field` / `ident.Field.Sub` — a receiver and at least one field.
+// Anchored on a word boundary so `a.b` inside a longer chain still resolves to
+// its own receiver rather than to a substring.
+const FIELD_ACCESS = /\b([A-Za-z_]\w*)\.([A-Z]\w*)\b/g;
+
+// A call of the form `name(<receiver>.<Field>)`, single argument. The single
+// argument matters: a multi-argument call is far more likely to be the
+// operation itself (`fsRename(path, name)`) than a validator.
+const GUARD_CALL = /\b([A-Za-z_]\w*)\s*\(\s*([A-Za-z_]\w*)\.([A-Z]\w*)\s*\)/g;
+
+// Callees that are never guards even when called with one field argument —
+// these consume a value, they do not validate it. Without this the rule reads
+// `log.Printf(req.Name)` as establishing a convention.
+const NOT_A_GUARD = /^(?:print|println|printf|sprintf|fprintf|log|logf|append|len|cap|new|make|string|byte|error|errorf|wrap|wrapf|panic|recover|close|delete|copy)$/i;
+
+// Operations where an unvalidated relative path is a traversal. Kept narrow and
+// literal: every entry is either a filesystem call or the string-building step
+// that feeds one.
+const PATH_SINK = new RegExp([
+  // "%s/%s" style path joins. FORWARD slash only, deliberately.
+  //
+  // This originally accepted `/` OR `\`, and that produced a false positive on
+  // real code (rclone `cmd/bisync/help.go:72`): a help-text formatter
+  // `fmt.Sprintf("- %s - (%s) %s  \n", …)` contains a BACKSLASH as part of the
+  // `\n` escape, which read as a path separator. A Go format string that builds
+  // a path uses `/`; a backslash in one is nearly always an escape sequence.
+  // Found on real code rather than by a fixture, which is the argument for
+  // measuring a new rule against the independent population before trusting it.
+  String.raw`\bfmt\.Sprintf\s*\(\s*"[^"]*/[^"]*"`,
+  String.raw`\bfilepath\.(?:Join|Clean|Abs|Walk)\s*\(`,
+  String.raw`\bpath\.Join\s*\(`,
+  String.raw`\bos\.(?:Open|OpenFile|Create|Remove|RemoveAll|Rename|ReadFile|WriteFile|Stat|Mkdir|MkdirAll)\s*\(`,
+  String.raw`\bioutil\.(?:ReadFile|WriteFile)\s*\(`,
+  String.raw`\b\w*[Ff]s\.(?:Rename|Remove|Copy|Move|Open|Create|Link)\s*\(`,
+  String.raw`\b(?:fsRename|fsRemove|fsCopy|fsMove)\s*\(`,
+].join('|'));
+
+/** Split a Go source file into top-level function bodies by brace matching. */
+function goFunctions(src) {
+  const out = [];
+  const re = /\bfunc\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)\s*\(/g;
+  let m;
+  while ((m = re.exec(src))) {
+    const open = src.indexOf('{', m.index);
+    if (open < 0) continue;
+    let depth = 0, end = open;
+    for (let i = open; i < src.length; i++) {
+      const ch = src[i];
+      if (ch === '{') depth++;
+      else if (ch === '}') { depth--; if (depth === 0) { end = i; break; } }
+    }
+    if (end <= open) continue;
+    out.push({ name: m[1], body: src.slice(open, end + 1), offset: open });
+    re.lastIndex = end;
+  }
+  return out;
+}
+
+const lineOf = (src, index) => src.slice(0, index).split('\n').length;
+
+export function scanSiblingGuard(fp, raw) {
+  if (!raw || !GO_FILE_RE.test(String(fp || ''))) return [];
+  if (raw.length > 500_000) return [];
+
+  const findings = [];
+  for (const fn of goFunctions(raw)) {
+    // 1. Which (receiver, field) pairs does some single-arg call validate?
+    //    receiver -> Map<field, guardName>
+    const guarded = new Map();
+    let g;
+    const guardRe = new RegExp(GUARD_CALL.source, 'g');
+    while ((g = guardRe.exec(fn.body))) {
+      const [, callee, recv, field] = g;
+      if (NOT_A_GUARD.test(callee)) continue;
+      if (!guarded.has(recv)) guarded.set(recv, new Map());
+      guarded.get(recv).set(field, callee);
+    }
+    if (!guarded.size) continue;
+
+    // 2. Every (receiver, field) the function touches, at EVERY offset.
+    //
+    // Recording only the first occurrence was the first version's bug and it
+    // made the rule silent on the very advisory it was written from: the first
+    // mention of `renameObject.SrcName` is the `if … == ""` emptiness check,
+    // several lines above the `fmt.Sprintf` that actually builds the path. A
+    // field is interesting wherever it reaches a sink, not where it debuts.
+    const touched = new Map();
+    let a;
+    const accessRe = new RegExp(FIELD_ACCESS.source, 'g');
+    while ((a = accessRe.exec(fn.body))) {
+      const [, recv, field] = a;
+      if (!touched.has(recv)) touched.set(recv, new Map());
+      const byField = touched.get(recv);
+      if (!byField.has(field)) byField.set(field, []);
+      byField.get(field).push(a.index);
+    }
+
+    for (const [recv, fields] of touched) {
+      const guards = guarded.get(recv);
+      if (!guards || !guards.size) continue;           // no convention on this receiver
+      for (const [field, offsets] of fields) {
+        if (guards.has(field)) continue;               // this field IS guarded
+        // 3. Does the unguarded sibling reach a path-ish operation at ANY of
+        //    its uses? Field and sink must share a line — the shape the advisory
+        //    shows, and the one a reviewer confirms without tracing dataflow.
+        const at = offsets.find((off) => {
+          const lineStart = fn.body.lastIndexOf('\n', off) + 1;
+          const lineEnd = fn.body.indexOf('\n', off);
+          return PATH_SINK.test(fn.body.slice(lineStart, lineEnd < 0 ? undefined : lineEnd));
+        });
+        if (at === undefined) continue;
+
+        const [guardedField, guardName] = [...guards.entries()][0];
+        findings.push({
+          id: `sibling-guard:${fp}:${recv}.${field}`,
+          severity: 'high',
+          file: fp,
+          line: lineOf(fn.body, at) + lineOf(raw, fn.offset) - 1,
+          vuln: `Path traversal — \`${recv}.${field}\` skips the \`${guardName}\` guard its sibling \`${recv}.${guardedField}\` uses`,
+          cwe: 'CWE-22',
+          family: 'sibling-guard-omission',
+          parser: 'SIBLING-GUARD',
+          description:
+            `\`${fn.name}\` validates \`${recv}.${guardedField}\` with \`${guardName}\`, then builds a filesystem `
+            + `path from the sibling field \`${recv}.${field}\` without applying the same check. A relative path in `
+            + `\`${field}\` therefore escapes the intended directory.`,
+          remediation: `Apply \`${guardName}(${recv}.${field})\` before using it, exactly as the sibling field does.`,
+          // T2.2 — an absence-claim must record what it looked for, so a
+          // reviewer (or a refutation lens) can contradict it mechanically.
+          checkedFor: guardName,
+          evidenceGuardedSibling: `${recv}.${guardedField}`,
+          evidenceUnguardedField: `${recv}.${field}`,
+        });
+      }
+    }
+  }
+  return findings;
+}

package/src/sast/zip-slip.js

@@ -77,6 +77,57 @@ export function scanZipSlip(fp, raw) {
     // filter="data" / filter=tarfile.data_filter in the same call. File-level
     // suppression was too aggressive — a safe function later in the file would
     // hide an unsafe one earlier.
+    /**
+     * The OTHER real mitigation: intercept per-member extraction and refuse
+     * any destination outside the target directory. Both halves are required —
+     * GHSA-f42x-p2mx-hm8r's VULNERABLE revision also patched `_extract_member`,
+     * but only to add a write bit, with no path validation. Recognising the
+     * patch alone would therefore silence the vulnerable code too.
+     *
+     * `filter="data"` needs Python 3.12; this interception form is what
+     * codebases supporting older Pythons actually ship, so treating it as
+     * exotic left the finding surviving its own fix.
+     */
+    // Resolved through the ASSIGNED FUNCTION'S OWN BODY, never a text window.
+    // A window is useless here: penelope.py is 5000+ lines, and any window
+    // wide enough to reach the interceptor also sweeps up unrelated
+    // os.path.realpath calls, which silenced the VULNERABLE revision too.
+    const CONTAINMENT_RE = /\b(?:commonpath|realpath|abspath)\s*\(|\w{0,20}(?:is_?within|inside_?dir|safe_?path|within_?dir)\w{0,20}\s*\(|\.startswith\s*\(/i;
+    const MEMBER_PATCH_RE = /\b_extract_member\s*=\s*([A-Za-z_]\w*)/g;
+    /** Body of a Python `def name(...)`, by indentation. */
+    const _pyBody = (name) => {
+      const d = new RegExp(`^([ \\t]*)def\\s+${name}\\s*\\(`, 'm').exec(code);
+      if (!d) return null;
+      const indent = d[1].length;
+      // Start at the line AFTER the signature. Slicing at the end of the
+      // matched `def name(` leaves the rest of that same line as element 0
+      // with zero indentation, which ends the body before it begins.
+      const nl = code.indexOf('\n', d.index);
+      if (nl === -1) return null;
+      const rest = code.slice(nl + 1).split('\n');
+      const body = [];
+      for (const ln of rest) {
+        if (ln.trim() && (ln.length - ln.trimStart().length) <= indent) break;
+        body.push(ln);
+      }
+      return body.join('\n');
+    };
+    const _isContainmentGuardedExtract = () => {
+      MEMBER_PATCH_RE.lastIndex = 0;
+      let a;
+      while ((a = MEMBER_PATCH_RE.exec(code))) {
+        const body = _pyBody(a[1]);
+        if (!body) continue;
+        // The interceptor must REFUSE, not merely observe. penelope's
+        // vulnerable revision also patched _extract_member — to add a write
+        // bit (`args[0].mode |= 0o200`) with no validation and no early
+        // return — so requiring a conditional refusal is what separates the
+        // two revisions.
+        const refuses = /\bif\b[\s\S]{0,400}?\b(?:return|raise|continue)\b/.test(body);
+        if (refuses && CONTAINMENT_RE.test(body)) return true;
+      }
+      return false;
+    };
     const _isFilteredExtract = (afterIdx) => {
       let depth = 0;
       let inS = null;
@@ -101,7 +152,7 @@ export function scanZipSlip(fp, raw) {
       let m;
       while ((m = reA.exec(code))) {
         const openParen = m.index + m[0].length - 1; // position of '('
-        if (_isFilteredExtract(openParen)) continue;
+        if (_isFilteredExtract(openParen) || _isContainmentGuardedExtract()) continue;
         const line = _lineOf(raw, m.index);
         push({
           id: `zip-slip:${fp}:${line}:py-tarfile`,
@@ -119,7 +170,7 @@ export function scanZipSlip(fp, raw) {
       const reB = new RegExp(PY_TARFILE_EXTRACTALL_SHORT_RE.source, PY_TARFILE_EXTRACTALL_SHORT_RE.flags);
       while ((m = reB.exec(code))) {
         const openParen = m.index + m[0].length - 1;
-        if (_isFilteredExtract(openParen)) continue;
+        if (_isFilteredExtract(openParen) || _isContainmentGuardedExtract()) continue;
         const line = _lineOf(raw, m.index);
         push({
           id: `zip-slip:${fp}:${line}:py-tarfile-bare`,