@clear-capabilities/agentic-security-scanner 0.140.0 → 0.142.0

package/src/sast/iac-cloud-templates.js

@@ -0,0 +1,346 @@
+// PRD F4.3 — the IaC formats `bench/iac-coverage` measured at zero.
+//
+// That bench scores VERDICT FLIP: a control counts as covered only when the
+// misconfigured variant fires and the hardened variant stays silent. On its
+// first run the engine scored 8/14, and the six failures were not spread
+// evenly — they were whole formats:
+//
+//   terraform       4/4      kubernetes      3/4      dockerfile   1/2
+//   cloudformation  0/2      bicep           0/1      helm         0/1
+//
+// Terraform had `iac-terraform.js` and Kubernetes had `k8s-admission.js`.
+// CloudFormation, Bicep and Helm values had nothing at all, in either the rule
+// set or the file walker — and a CloudFormation template is a `.yaml` that no
+// path predicate recognises, so it was never even read.
+//
+// Every rule here is written to flip. The hardened variant of each control was
+// written first and each rule was checked against it, because a rule that fires
+// on `AccessControl: Private` as well as `PublicRead` is not detecting the
+// control, it is detecting the resource — and a recall-only bench cannot see the
+// difference.
+//
+// Regex over the raw template text, consistent with the rest of this directory:
+// no YAML or Bicep parser is added, because `fast-xml-parser` was already
+// rejected here on bundle-size and audit-surface grounds and the same argument
+// applies. The cost is honest and bounded — deeply nested or heavily
+// intrinsic-function'd templates will be missed, and the bench is where that
+// shows up.
+
+const ADMIN_PORTS = new Set([22, 23, 3389, 3306, 5432, 6379, 27017, 9200, 1433, 5984]);
+const OPEN_CIDRS = /^(?:0\.0\.0\.0\/0|::\/0)$/;
+
+function _line(text, index) { return text.slice(0, index).split('\n').length; }
+
+function _finding(fp, text, index, over) {
+  return {
+    file: fp,
+    line: _line(text, index),
+    parser: 'IAC',
+    ...over,
+  };
+}
+
+// ── CloudFormation ──────────────────────────────────────────────────────────
+
+export function isCloudFormationTemplate(relPath, content) {
+  if (typeof content !== 'string') return false;
+  if (!/\.(?:ya?ml|json)$/i.test(relPath || '')) return false;
+  const head = content.length > 65536 ? content.slice(0, 65536) : content;
+  if (/AWSTemplateFormatVersion/.test(head)) return true;
+  // A template without the (optional) version key is still a template if it
+  // declares resources by AWS type. Both signals are required so an ordinary
+  // config file mentioning "Resources" is not swept in.
+  return /(?:^|\n)\s*Resources\s*:/.test(head) && /Type\s*:\s*["']?AWS::/.test(head);
+}
+
+function scanCloudFormation(fp, raw) {
+  const out = [];
+
+  // Unrestricted ingress. The port and the CIDR are read from the same ingress
+  // block rather than matched independently, so `CidrIp: 0.0.0.0/0` on port 443
+  // — which is what a public web listener looks like and is not a finding —
+  // does not match.
+  // Split the ingress LIST into items, rather than anchoring on `- IpProtocol`.
+  //
+  // YAML mappings are unordered, so `- CidrIp:` first and `- IpProtocol:` first
+  // are the same template — and the anchored form only matched the second.
+  // bench/mutation's `cfn-metamorphic-property-order` case is exactly that
+  // rewrite, and it failed: the rule was keyed on the author's key order, which
+  // is syntax, not meaning.
+  const ingressBlock = /(?:^|\n)([ \t]*)-[ \t]+(?=[\w"']+[ \t]*:)([\s\S]*?)(?=\n[ \t]*-[ \t]|\n[ \t]{0,8}\w[\w.]*[ \t]*:|$)/g;
+  let m;
+  while ((m = ingressBlock.exec(raw))) {
+    const block = m[0];
+    // Only list items that actually describe an ingress rule.
+    if (!/IpProtocol\s*:/.test(block) || !/Cidr(?:Ip|Ipv6)\s*:/.test(block)) continue;
+    const cidr = block.match(/Cidr(?:Ip|Ipv6)\s*:\s*["']?([^\s"',]+)/);
+    if (!cidr || !OPEN_CIDRS.test(cidr[1])) continue;
+    const from = block.match(/FromPort\s*:\s*["']?(\d+)/);
+    const to = block.match(/ToPort\s*:\s*["']?(\d+)/);
+    if (!from || !to) continue;
+    const lo = Number(from[1]), hi = Number(to[1]);
+    const hitsAdmin = [...ADMIN_PORTS].some((p) => p >= lo && p <= hi);
+    if (!hitsAdmin) continue;
+    out.push(_finding(fp, raw, m.index, {
+      id: `cfn-open-ingress:${fp}:${_line(raw, m.index)}`,
+      vuln: `CloudFormation security group allows ${cidr[1]} to port ${lo === hi ? lo : `${lo}-${hi}`}`,
+      severity: 'high', cwe: 'CWE-284', family: 'iac-network-exposure',
+      description: `A SecurityGroupIngress rule opens an administrative port to the whole internet. Anyone who can reach the instance can attempt authentication against it, continuously and from anywhere.`,
+      remediation: `Restrict CidrIp to the VPC or office range, or front the port with a bastion / session manager. If public access is genuinely required, say so in the template with a comment so the next reader does not have to guess.`,
+      snippet: block.split('\n').slice(0, 6).join('\n').trim().slice(0, 200),
+    }));
+  }
+
+  // Public object storage. `AccessControl` is the property that grants it; the
+  // hardened form sets Private and usually adds a PublicAccessBlockConfiguration.
+  const acl = /AccessControl\s*:\s*["']?(PublicRead|PublicReadWrite|AuthenticatedRead)\b/g;
+  while ((m = acl.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `cfn-public-bucket:${fp}:${_line(raw, m.index)}`,
+      vuln: `CloudFormation bucket grants ${m[1]} access`,
+      severity: m[1] === 'PublicReadWrite' ? 'critical' : 'high',
+      cwe: 'CWE-732', family: 'iac-public-storage',
+      description: `The bucket's canned ACL makes its objects readable${m[1] === 'PublicReadWrite' ? ' AND writable' : ''} by anyone. Public buckets are the single most common cause of accidental data exposure in cloud estates.`,
+      remediation: `Set AccessControl: Private and add a PublicAccessBlockConfiguration with BlockPublicAcls and BlockPublicPolicy set to true. Serve public assets through a CDN with an origin access identity instead.`,
+      snippet: m[0],
+    }));
+  }
+
+  // Publicly reachable managed database. The property is unambiguous and the
+  // hardened form is the single-word opposite, which is what makes it a good
+  // control: there is no judgement call for the rule to get wrong.
+  const publicDb = /PubliclyAccessible\s*:\s*["']?true\b/g;
+  while ((m = publicDb.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `cfn-public-db:${fp}:${_line(raw, m.index)}`,
+      vuln: 'CloudFormation database instance is publicly accessible',
+      severity: 'high', cwe: 'CWE-284', family: 'iac-network-exposure',
+      description: 'The instance gets a public endpoint, so its authentication is the only thing between the internet and the data. Encryption at rest does not help here — the attacker arrives as a client.',
+      remediation: 'Set PubliclyAccessible: false and reach the database from inside the VPC, through a bastion or a private endpoint.',
+      snippet: m[0],
+    }));
+  }
+
+  // Wildcard IAM. Matched on the STATEMENT so that `Action: '*'` with a scoped
+  // Resource, or a scoped Action with `Resource: '*'`, do not both have to be
+  // present on the same line — YAML puts them on separate ones.
+  const stmt = /-\s*Effect\s*:\s*["']?Allow["']?[\s\S]{0,300}?(?=\n\s*-\s*Effect|\n\s{0,6}\w+\s*:\s*\n|$)/g;
+  while ((m = stmt.exec(raw))) {
+    const block = m[0];
+    const wildcardAction = /Action\s*:\s*(?:\[\s*)?["']\*["']/.test(block);
+    const wildcardResource = /Resource\s*:\s*(?:\[\s*)?["']\*["']/.test(block);
+    if (!wildcardAction || !wildcardResource) continue;
+    out.push(_finding(fp, raw, m.index, {
+      id: `cfn-iam-wildcard:${fp}:${_line(raw, m.index)}`,
+      vuln: 'CloudFormation IAM statement allows Action "*" on Resource "*"',
+      severity: 'high', cwe: 'CWE-732', family: 'iac-excessive-privilege',
+      description: 'This grants every action on every resource in the account. Any compromise of a principal holding it is a full account compromise, and nothing downstream can constrain it.',
+      remediation: 'Enumerate the actions the workload actually calls and scope Resource to the specific ARNs. If the policy is for a break-glass role, keep it out of the default deployment path.',
+      snippet: block.split('\n').slice(0, 5).join('\n').trim().slice(0, 200),
+    }));
+  }
+
+  return out;
+}
+
+// ── Bicep ───────────────────────────────────────────────────────────────────
+
+function scanBicep(fp, raw) {
+  const out = [];
+  let m;
+
+  const publicBlob = /allowBlobPublicAccess\s*:\s*true\b/g;
+  while ((m = publicBlob.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `bicep-public-blob:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Bicep storage account allows anonymous public blob access',
+      severity: 'high', cwe: 'CWE-732', family: 'iac-public-storage',
+      description: `allowBlobPublicAccess: true lets containers in this account be configured for anonymous read. The account-level flag is the last line of defence — with it enabled, a single container-level mistake exposes data to the internet.`,
+      remediation: `Set allowBlobPublicAccess: false. Grant access with SAS tokens or a managed identity instead; if truly public content is needed, serve it through a CDN endpoint.`,
+      snippet: m[0],
+    }));
+  }
+
+  const plaintextTransit = /supportsHttpsTrafficOnly\s*:\s*false\b/g;
+  while ((m = plaintextTransit.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `bicep-http-allowed:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Bicep storage account permits unencrypted HTTP traffic',
+      severity: 'medium', cwe: 'CWE-319', family: 'iac-transit-encryption',
+      description: `supportsHttpsTrafficOnly: false allows clients to reach the account over plain HTTP, so credentials and data can be read by anything on the path.`,
+      remediation: 'Set supportsHttpsTrafficOnly: true. There is no compatible client left that requires plain HTTP for this service.',
+      snippet: m[0],
+    }));
+  }
+
+  // An inbound Allow rule whose source is `*` (or the Internet service tag) on
+  // an administrative port. Read from the whole rule block so a wildcard source
+  // on port 443 — an ordinary public web listener — does not match.
+  const nsgRule = /\{[^{}]*?direction\s*:\s*'Inbound'[^{}]*?\}|\{[^{}]*?sourceAddressPrefix[\s\S]{0,400}?\}/g;
+  while ((m = nsgRule.exec(raw))) {
+    const block = m[0];
+    if (!/direction\s*:\s*'Inbound'/i.test(block)) continue;
+    if (!/access\s*:\s*'Allow'/i.test(block)) continue;
+    const src = block.match(/sourceAddressPrefix\s*:\s*'([^']*)'/);
+    if (!src || !/^(?:\*|0\.0\.0\.0\/0|Internet)$/i.test(src[1])) continue;
+    const portRange = block.match(/destinationPortRanges?\s*:\s*'?\[?\s*'?([^'\]]*)/);
+    const ports = portRange ? portRange[1] : '';
+    const hitsAdmin = [...ADMIN_PORTS].some((pnum) => {
+      if (new RegExp(`(?:^|[,\\s])${pnum}(?:$|[,\\s])`).test(ports)) return true;
+      const range = ports.match(/(\d+)\s*-\s*(\d+)/);
+      return !!range && pnum >= Number(range[1]) && pnum <= Number(range[2]);
+    });
+    if (!hitsAdmin && ports !== '*') continue;
+    out.push(_finding(fp, raw, m.index, {
+      id: `bicep-nsg-world:${fp}:${_line(raw, m.index)}`,
+      vuln: `Bicep network security rule allows inbound from "${src[1]}" to port ${ports || '*'}`,
+      severity: 'high', cwe: 'CWE-284', family: 'iac-network-exposure',
+      description: 'An inbound Allow rule with a wildcard source exposes an administrative port to the whole internet.',
+      remediation: "Set sourceAddressPrefix to the VNet or an office range, or reach the port through a bastion instead.",
+      snippet: block.split('\n').slice(0, 6).join('\n').trim().slice(0, 200),
+    }));
+  }
+
+  const minTls = /minimumTlsVersion\s*:\s*['"]TLS1_0['"]/g;
+  while ((m = minTls.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `bicep-weak-tls:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Bicep resource accepts TLS 1.0',
+      severity: 'medium', cwe: 'CWE-327', family: 'iac-transit-encryption',
+      description: 'TLS 1.0 is deprecated and vulnerable to several downgrade and padding-oracle attacks.',
+      remediation: "Set minimumTlsVersion: 'TLS1_2'.",
+      snippet: m[0],
+    }));
+  }
+
+  return out;
+}
+
+// ── Helm values ─────────────────────────────────────────────────────────────
+
+// A chart's values.yaml is where a workload's defaults live, and a default is
+// what most installs actually run. `templates/*.yaml` is deliberately NOT
+// handled: it is Go template source, not YAML, and matching text inside `{{ }}`
+// would report the template rather than the configuration.
+function scanHelmValues(fp, raw) {
+  if (!/(?:^|\/)values(?:\.[\w-]+)?\.ya?ml$/i.test(fp)) return [];
+  const out = [];
+  let m;
+
+  const privileged = /(?:^|\n)\s*privileged\s*:\s*true\b/g;
+  while ((m = privileged.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `helm-privileged:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Helm chart defaults the workload to privileged execution',
+      severity: 'high', cwe: 'CWE-250', family: 'iac-privileged-workload',
+      description: `A privileged container has all capabilities and effectively full access to the host. Because this is a chart DEFAULT, every install that does not deliberately override it runs privileged.`,
+      remediation: 'Set privileged: false in values.yaml and let an operator opt in explicitly if a workload genuinely needs it.',
+      snippet: m[0].trim(),
+    }));
+  }
+
+  const hostNet = /(?:^|\n)\s*hostNetwork\s*:\s*true\b/g;
+  while ((m = hostNet.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `helm-host-network:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Helm chart defaults the workload onto the host network',
+      severity: 'high', cwe: 'CWE-668', family: 'iac-privileged-workload',
+      description: 'A pod on the host network sees every interface on the node, can bind privileged ports, and bypasses NetworkPolicy entirely. As a chart DEFAULT it applies to every install that does not override it.',
+      remediation: 'Set hostNetwork: false and expose the workload through a Service.',
+      snippet: m[0].trim(),
+    }));
+  }
+
+  const rootUser = /(?:^|\n)\s*runAsUser\s*:\s*0\b/g;
+  while ((m = rootUser.exec(raw))) {
+    out.push(_finding(fp, raw, m.index, {
+      id: `helm-run-as-root:${fp}:${_line(raw, m.index)}`,
+      vuln: 'Helm chart defaults the workload to UID 0 (root)',
+      severity: 'medium', cwe: 'CWE-250', family: 'iac-privileged-workload',
+      description: 'Running as UID 0 means a container escape starts with root on the node, and any host path mounted into the container is writable.',
+      remediation: 'Set runAsNonRoot: true and a non-zero runAsUser, and make the image support it.',
+      snippet: m[0].trim(),
+    }));
+  }
+
+  return out;
+}
+
+// ── Dockerfile: base-image pinning ──────────────────────────────────────────
+
+// The bench's `docker-unpinned-base` control. Separate from the existing
+// container rules because it is about REPRODUCIBILITY of the supply chain
+// rather than what the image contains: `FROM ubuntu:latest` resolves to
+// different bytes on different days, so a scan result has no shelf life and a
+// compromised upstream tag arrives silently on the next build.
+function scanDockerfileBase(fp, raw) {
+  const base = (fp.split('/').pop() || '');
+  if (!/^(?:Dockerfile|Containerfile)(?:\.[\w.-]+)?$/i.test(base) && !/\.dockerfile$/i.test(base)) return [];
+  const out = [];
+  const from = /(?:^|\n)\s*FROM\s+(\S+)/gi;
+  let m;
+  while ((m = from.exec(raw))) {
+    const ref = m[1];
+    if (/^\$\{?\w/.test(ref)) continue;                    // build-arg indirection
+    if (ref.includes('@sha256:')) continue;                // pinned by digest — the hardened form
+    if (/^scratch$/i.test(ref)) continue;                  // the empty image has no tag
+    const tag = ref.includes(':') ? ref.slice(ref.lastIndexOf(':') + 1) : '';
+    // A named build stage (`FROM builder`) is an internal reference, not a
+    // registry pull.
+    if (!tag && !ref.includes('/') && /^[a-z][\w-]*$/i.test(ref) && new RegExp(`AS\\s+${ref}\\b`, 'i').test(raw)) continue;
+    const unpinned = !tag || /^latest$/i.test(tag);
+    if (!unpinned) continue;
+    out.push(_finding(fp, raw, m.index, {
+      id: `docker-unpinned-base:${fp}:${_line(raw, m.index)}`,
+      vuln: `Base image "${ref}" is not pinned to an immutable reference`,
+      severity: 'medium', cwe: 'CWE-1104', family: 'iac-unpinned-base',
+      description: `A mutable tag resolves to different bytes over time, so this build is not reproducible and a scan of it has no shelf life. If the upstream tag is ever republished — accidentally or maliciously — the change arrives on the next build with nothing to notice it.`,
+      remediation: `Pin by digest: FROM ${ref.split(':')[0]}@sha256:<digest>. Keep the human-readable tag in a comment so the next reader knows which release it is.`,
+      snippet: m[0].trim(),
+    }));
+  }
+  return out;
+}
+
+// ── Kubernetes: a literal credential in an env value ────────────────────────
+
+// `k8s-admission.js` covers the pod security surface; this is the one control
+// the bench found it silent on. A manifest is committed to a repository and
+// copied into CI logs and cluster state, so a literal value here is exposed
+// several times over.
+function scanK8sLiteralSecret(fp, raw) {
+  if (!/\.ya?ml$/i.test(fp)) return [];
+  if (!/(?:^|\n)\s*kind\s*:/.test(raw)) return [];
+  const out = [];
+  // `- name: DB_PASSWORD` followed by `value:` — as opposed to `valueFrom:`,
+  // which is the hardened form and must not match.
+  const envPair = /-\s*name\s*:\s*["']?([A-Z0-9_]*(?:PASSWORD|PASSWD|SECRET|TOKEN|APIKEY|API_KEY|PRIVATE_KEY|CREDENTIAL)[A-Z0-9_]*)["']?\s*\n\s*value\s*:\s*["']?([^\s"'#]{6,})/g;
+  let m;
+  while ((m = envPair.exec(raw))) {
+    const value = m[2];
+    // A reference or an obvious placeholder is not a leak.
+    if (/^\$[({]/.test(value)) continue;
+    if (/^(?:changeme|placeholder|example|your[-_]|todo|replace)/i.test(value)) continue;
+    out.push(_finding(fp, raw, m.index, {
+      id: `k8s-literal-secret:${fp}:${_line(raw, m.index)}`,
+      vuln: `Kubernetes manifest sets ${m[1]} to a literal value`,
+      severity: 'high', cwe: 'CWE-798', family: 'iac-literal-credential',
+      description: `The credential is committed to the repository, copied into CI logs, and stored in cluster state in plaintext. Rotating it means editing and redeploying the manifest, which is why it usually does not happen.`,
+      remediation: 'Use valueFrom.secretKeyRef and keep the value in a Secret managed outside the repository. Rotate the exposed credential — treat it as compromised.',
+      snippet: `- name: ${m[1]}\n  value: ${value.slice(0, 4)}••••`,
+    }));
+  }
+  return out;
+}
+
+/** All template-format IaC rules for one file. */
+export function scanCloudTemplates(fp, raw) {
+  if (!fp || typeof raw !== 'string' || !raw) return [];
+  const out = [];
+  if (/\.bicep$/i.test(fp)) out.push(...scanBicep(fp, raw));
+  if (isCloudFormationTemplate(fp, raw)) out.push(...scanCloudFormation(fp, raw));
+  out.push(...scanHelmValues(fp, raw));
+  out.push(...scanDockerfileBase(fp, raw));
+  out.push(...scanK8sLiteralSecret(fp, raw));
+  return out;
+}

package/src/sast/k8s-admission.js

@@ -38,6 +38,33 @@
 
 import { blankComments } from './_comment-strip.js';
 
+// The finding families this module can emit (F10.2 producer registry).
+//
+// Declared HERE, next to the rules, because no external method enumerates them:
+// this module passes `family` POSITIONALLY (`_shape(file, line, ruleId, vuln,
+// fam, ...)`), so a textual search for `family:` finds nothing, and a corpus
+// sweep only ever reports a LOWER BOUND -- it sees whichever families a fixture
+// happened to trigger. This list is the union of both, and
+// `test/family-registry.test.js` fails if a scan produces a family from this
+// module that is not listed.
+//
+// Add the family here in the same edit that adds the rule.
+export const EMITS = [
+  'k8s-pod-security-allow-privesc',
+  'k8s-pod-security-capabilities-broad',
+  'k8s-pod-security-hostnetwork',
+  'k8s-pod-security-hostpath',
+  'k8s-pod-security-hostpid',
+  'k8s-pod-security-privileged',
+  'k8s-pod-security-run-as-root',
+  'k8s-rbac-anonymous',
+  'k8s-rbac-cluster-admin',
+  'k8s-rbac-overbroad-binding',
+  'k8s-rbac-wildcard',
+  'k8s-webhook-bypass',
+  'k8s-webhook-sideeffects',
+];
+
 const _IS_K8S_FILE = /\.(?:yaml|yml)$/i;
 
 function _line(raw, idx) { return raw.slice(0, idx).split('\n').length; }

package/src/sast/ml-supply-chain.js

@@ -30,6 +30,28 @@
 
 import { blankComments } from './_comment-strip.js';
 
+// The finding families this module can emit (F10.2 producer registry).
+//
+// Declared HERE, next to the rules, because no external method enumerates them:
+// this module passes `family` POSITIONALLY (`_shape(file, line, ruleId, vuln,
+// fam, ...)`), so a textual search for `family:` finds nothing, and a corpus
+// sweep only ever reports a LOWER BOUND -- it sees whichever families a fixture
+// happened to trigger. This list is the union of both, and
+// `test/family-registry.test.js` fails if a scan produces a family from this
+// module that is not listed.
+//
+// Add the family here in the same edit that adds the rule.
+export const EMITS = [
+  'gradio-auth',
+  'hf-datasets-rce',
+  'hf-endpoint-override',
+  'mlflow-untrusted-uri',
+  'model-format',
+  'onnx-providers',
+  'prompt-integrity',
+  'streaming-dataset-url',
+];
+
 const _SCAN_EXT_RE = /\.(?:py|ipynb)$/i;
 const _NONPROD_PATH_RE = /(?:^|\/)(?:tests?|__tests__|spec|fixtures?|examples?|docs?|stories|codefixes|node_modules)\//i;
 

package/src/sast/ruby.js

@@ -144,3 +144,135 @@ export function scanRuby(fp, raw) {
   }
   return findings;
 }
+
+// ── PRD F1.3 — `File.join(<root>, …, <untrusted>)` ──────────────────────────
+//
+// The dominant Ruby CWE-22 shape on real code, and the one
+// `pathTraversalStructural` above cannot reach: that rule needs a STRING
+// LITERAL as the first component (`File.read("/data/" + name)`), and the real
+// advisories join variables.
+//
+//   File.join(adapter.document_root, request.path_info.sub(/\.html$/,'') + '.html')
+//     — lsegal/yard, GHSA-pxcc-8665-phx8; the fix rejects `..` segments
+//   File.join(root, tenant, folder_for(key), key)
+//     — basecamp/activerecord-tenanted, GHSA-pmwx-rm49-xv39; the fix raises on
+//       `key.split("/").intersect?(%w[. ..])`
+//
+// Measured baseline before this rule: 23 cached Ruby CWE-22/CWE-79 entries,
+// 0 localized hits, 18 of them producing no finding of any kind.
+//
+// PRECISION IS THE WHOLE DESIGN. The F1.2 attempt at Ruby resource-exhaustion
+// was reverted because it fired on `File.read(File.join(__dir__, "…/data.json"))`
+// — a path built entirely from constants. So:
+//
+//   · the LAST component must be a variable-ish expression, never a literal;
+//   · a join rooted at `__dir__` / `Rails.root` / `File.dirname(__FILE__)` /
+//     `Dir.pwd` is a project-relative constant path and is skipped outright;
+//   · the join must actually reach a filesystem operation, either wrapped
+//     directly or through a variable used by one nearby;
+//   · any containment guard in the enclosing window silences it — that is the
+//     whole vulnerability, so a guard means there is nothing to report.
+//
+// A single `if path.include?("..")` silences this, which is exactly the fix
+// each of these advisories shipped.
+
+// Trailing (?!\w) rather than \b: Ruby predicate methods end in \, and a
+// word boundary after a non-word character never matches, so \
+// silently failed to count as a filesystem operation — the miss that made this
+// rule silent on lsegal/yard's static_caching.rb, one of the two advisories it
+// was written from.
+// Trailing (?!\w) rather than \b. Ruby predicate methods end in `?`, and a word
+// boundary after a non-word character can never match — so `File.file?(x)` did
+// not count as a filesystem operation, and this rule was silent on
+// lsegal/yard's static_caching.rb, one of the two advisories it was written
+// from. The rule looked correct in isolation and found nothing; the bug was one
+// character of regex.
+const RB_FS_OP = /\b(?:File|IO|FileUtils|Dir)\s*\.\s*(?:read|open|new|readlines|binread|binwrite|write|foreach|delete|unlink|mkdir_p|rm_rf|cp|mv|file\?|exist\?|directory\?|entries|glob)(?!\w)/;
+// Constant roots: a path assembled from these is not attacker-reachable.
+const RB_CONST_ROOT = /\b(?:__dir__|__FILE__|Rails\.root|Dir\.pwd|Gem\.dir|File\.dirname\s*\(\s*__FILE__)/;
+// Any of these in the enclosing window means containment was considered.
+const RB_PATH_GUARD = /\b(?:expand_path[\s\S]{0,200}?start_with\?|start_with\?[\s\S]{0,200}?expand_path|include\?\s*\(\s*['"]\.\.|\.\.\s*['"]\s*\)|intersect\?\s*\(\s*%w\[|cleanpath|realpath|File\s*\.\s*basename|sanitize_filename|secure_filename|ValidPath|absolute_path\?)/;
+// A literal argument — the thing that must NOT be the last component.
+const RB_LITERAL_ARG = /^\s*(?:['"][^'"]*['"]|:[A-Za-z_]\w*)\s*$/;
+
+function _splitArgs(s) {
+  const out = [];
+  let depth = 0, cur = '';
+  for (const ch of s) {
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+    if (ch === ',' && depth === 0) { out.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}
+
+/** File.join(...) whose last component is variable and which reaches the filesystem. */
+export function scanRubyPathJoin(fp, raw) {
+  if (!/\.rb$/i.test(fp)) return [];
+  if (!raw || raw.length > 500_000) return [];
+  const code = blankComments(raw, 'py');
+  const lines = code.split('\n');
+  const out = [];
+  const seen = new Set();
+
+  const JOIN = /\bFile\s*\.\s*join\s*\(/g;
+  let m;
+  while ((m = JOIN.exec(code))) {
+    // Balanced scan for the closing paren of this call.
+    let i = m.index + m[0].length, depth = 1;
+    for (; i < code.length && depth > 0; i++) {
+      if (code[i] === '(') depth++;
+      else if (code[i] === ')') depth--;
+    }
+    if (depth !== 0) continue;
+    const inner = code.slice(m.index + m[0].length, i - 1);
+    const args = _splitArgs(inner);
+    if (args.length < 2) continue;
+    const last = args[args.length - 1];
+    if (RB_LITERAL_ARG.test(last)) continue;                 // File.join(root, "index.html")
+    if (RB_CONST_ROOT.test(inner)) continue;                 // project-relative constant path
+
+    const line = code.slice(0, m.index).split('\n').length;
+
+    // The join must reach the filesystem: wrapped directly, or assigned to a
+    // variable that a nearby filesystem call uses.
+    const before = code.slice(Math.max(0, m.index - 120), m.index);
+    let reaches = RB_FS_OP.test(before);
+    let assigned = null;
+    if (!reaches) {
+      const am = before.match(/([A-Za-z_@][\w]*)\s*=\s*$/);
+      if (am) {
+        assigned = am[1];
+        const after = lines.slice(line, line + 12).join('\n');
+        const use = new RegExp(`${assigned.replace('@', '@')}\\b`);
+        reaches = RB_FS_OP.test(after) && use.test(after);
+      }
+    }
+    if (!reaches) continue;
+
+    // Containment guard anywhere in the enclosing window — that IS the fix.
+    const windowText = lines.slice(Math.max(0, line - 15), line + 15).join('\n');
+    if (RB_PATH_GUARD.test(windowText)) continue;
+
+    const id = `ruby-pathJoinUnguarded:${fp}:${line}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({
+      id, file: fp, line,
+      vuln: 'Path Traversal: File.join builds a filesystem path from a variable component with no containment check',
+      severity: 'high', cwe: 'CWE-22', family: 'path-traversal',
+      parser: 'RUBY', confidence: 0.7,
+      description:
+        `The last component of this File.join is a variable, the result reaches a filesystem operation, and nothing in ` +
+        `the surrounding code rejects \`..\` segments or asserts the resolved path stays under the base. A value ` +
+        `containing \`../\` walks out of the intended directory.`,
+      remediation:
+        'Reject traversal segments before joining — `raise if key.split("/").intersect?(%w[. ..])` — or canonicalize ' +
+        'and assert containment: `path = File.expand_path(File.join(base, name)); raise unless path.start_with?(base)`.',
+      snippet: (raw.split('\n')[line - 1] || '').trim().slice(0, 200),
+    });
+  }
+  return out;
+}

package/src/sast/web3-advanced.js

@@ -39,6 +39,32 @@
 
 import { blankComments } from './_comment-strip.js';
 
+// The finding families this module can emit (F10.2 producer registry).
+//
+// Declared HERE, next to the rules, because no external method enumerates them:
+// this module passes `family` POSITIONALLY (`_shape(file, line, ruleId, vuln,
+// fam, ...)`), so a textual search for `family:` finds nothing, and a corpus
+// sweep only ever reports a LOWER BOUND -- it sees whichever families a fixture
+// happened to trigger. This list is the union of both, and
+// `test/family-registry.test.js` fails if a scan produces a family from this
+// module that is not listed.
+//
+// Add the family here in the same edit that adds the rule.
+export const EMITS = [
+  'ecdsa-malleability',
+  'erc4337-validation',
+  'fee-on-transfer-vault',
+  'multicall-delegatecall',
+  'nft-receiver-reentrancy',
+  'oracle-staleness',
+  'read-only-reentrancy',
+  'signature-replay',
+  'solana-anchor-no-owner',
+  'upgradeable-init',
+  'upgradeable-storage',
+  'vyper-raw-call',
+];
+
 function _line(raw, idx) { return raw.slice(0, idx).split('\n').length; }
 function _snip(raw, line) { return (raw.split('\n')[line - 1] || '').trim().slice(0, 200); }
 

package/src/sca/CLAUDE.md

@@ -16,7 +16,7 @@ This directory holds the seven specialized modules called from there.
 | `index.js` | Re-exports six public symbols from `../engine.js` so external consumers can `import { parseManifests, queryOSV, … } from '@…/sca'`. |
 | `binary-metadata.js` | **Opt-in via `AGENTIC_SECURITY_BINARY_SCA=1`.** Reads dependency metadata from compiled artifacts: JAR `META-INF/MANIFEST.MF` + `pom.properties`, Go binary `go.buildinfo`. Never executes the binary. JAR extraction uses `fs.mkdtemp` for an isolated scratch dir (premortem-derived: shared `/tmp` lets a hostile JAR plant a symlinked manifest that escapes the scratch). |
 | `container.js` | Dockerfile parser. Detects EOL `FROM` base images (alpine/debian/ubuntu/node/python) against `base-images.json`, and synthesizes lightweight SCA components from `apt-get install` / `apk add` package lists. No Docker daemon required. |
-| `dep-confusion.js` | Two related detectors. **Typosquat:** Levenshtein distance ≤ 2 against `popular-packages.json` — **188 packages (115 npm + 73 pypi), not "top-1000"** as this row previously said; re-derive the count from the file rather than trusting a hardcoded number here again. **Dependency confusion:** internal-scoped names (declared in `.agentic-security/internal-scopes.yml`) appearing on the public registry. Local-first; **this module does not itself call OSV** — it reads a flag set by an earlier, separate OSV/queryRegistries pass upstream (whether a dep "resolved by OSV"), which is different from "OSV consulted [by this module] to confirm confusion findings" as previously stated. |
+| `dep-confusion.js` | Two related detectors. **Typosquat:** Damerau-Levenshtein distance against `popular-packages.json`, accepted only when `distance / min(nameLen, popularLen) ≤ 0.25` — **188 packages (115 npm + 73 pypi), not "top-1000"** as this row previously said; re-derive the count from the file rather than trusting a hardcoded number here again. **Dependency confusion:** internal-scoped names (declared in `.agentic-security/internal-scopes.yml`) appearing on the public registry. Local-first; **this module does not itself call OSV** — it reads a flag set by an earlier, separate OSV/queryRegistries pass upstream (whether a dep "resolved by OSV"), which is different from "OSV consulted [by this module] to confirm confusion findings" as previously stated. |
 | `llm-function-extract.js` | **Opt-in via `AGENTIC_SECURITY_LLM_SCA=1`.** LLM-assisted extraction of vulnerable function names for CVEs that lack OSV `ecosystem_specific.vulnerable_functions` data. Cached per CVE under `~/.config/agentic-security/llm-sca-cache/`. Endpoint-dependent — degrades to no-op when unreachable. |
 | `py-package-functions.js` | **Opt-in via `AGENTIC_SECURITY_DEEP=1`** (Python only). Locates installed Python packages via `site-packages` and parses them with the CPython `ast` module (subprocess) to *validate* that an OSV-named vulnerable function exists in the installed version. Closes the "OSV says this function is vulnerable, but the version you installed actually removed it" false-positive class. |
 | `vendor-detect.js` | Detects libraries copied into `src/` (lodash, jQuery, Angular, React, etc.) via characteristic version strings and function signatures. Catches the case where a vulnerable library bypasses the lockfile because someone vendored it directly. |
@@ -130,9 +130,26 @@ if a detector forgets to set them.
 - **EOL base-image detection has a hand-curated cutoff.** `base-images.json`
   is updated periodically; an alpine-3.16 today might not appear EOL until
   the file is refreshed. Bias is toward false negatives.
-- **Typosquat threshold is a single distance.** Levenshtein ≤ 2 against
-  the popular-packages.json list (188 entries, not top-1000). Increasing the threshold blows up the FP rate;
-  decreasing it loses real typosquats. This is the calibrated default.
+- **Typosquat similarity is RELATIVE, and that is load-bearing.** The rule is
+  Damerau-Levenshtein ≤ 2 *and* `distance / min(len) ≤ 0.25` against
+  popular-packages.json (188 entries, not top-1000).
+
+  The absolute `Levenshtein ≤ 2` this used to be was measured by
+  `bench/sca-replay` over 13 real repositories and produced **166 findings at
+  critical/high, of which zero were typosquats** — `ms ~ ws`, `acorn ~ cors`,
+  `ajv ~ ava`, `six ~ tox`, `arg ~ yargs`, `bail ~ babel`. All short names: two
+  edits on a four-character name changes half of it, and every two-character
+  package is one edit from every other. The ratio gate is what removes them.
+
+  Damerau rather than plain Levenshtein because a TRANSPOSITION (`lodahs` for
+  `lodash`) is the most common real typo, and plain distance scores it 2 — the
+  same as two unrelated substitutions. Under the ratio gate that would have
+  thrown the genuine cases out along with the noise.
+
+  The FP budget is pinned in `test/dep-confusion.test.js` using the actual
+  names the bench surfaced. Widening the reference list is safe *because* of
+  the ratio gate; widening it under the old rule would have multiplied the
+  noise.
 
 ## Adding a new detector here