@clear-capabilities/agentic-security-scanner 0.124.1 → 0.128.1

package/src/sast/api-authz.js

@@ -34,6 +34,23 @@ function mk(r, kind, api, cwe, why) {
   };
 }
 
+// #9 — CWE-306 missing authentication for a state-changing route.
+function mk306(r) {
+  return {
+    id: `api-authz:missing-auth:${r.file}:${r.line}`,
+    severity: 'high',
+    file: r.file,
+    line: r.line || 0,
+    vuln: `Missing authentication for a state-changing route (${r.method} ${r.path})`,
+    cwe: '306',
+    family: 'broken-access-control',
+    parser: 'API-AUTHZ',
+    subfamily: 'missing-auth',
+    description: `${r.method} ${r.path} performs a destructive/state-changing operation with no authentication, while other routes in this app DO enforce it — so auth-detection demonstrably works here. An unauthenticated ${r.method} lets anyone invoke it (delete/modify another user's data).`,
+    remediation: 'Require authentication on this route (the same middleware/guard the app uses elsewhere) and, for object routes, verify the caller owns the target object.',
+  };
+}
+
 /**
  * Cross-route analysis over the aggregated route inventory (aR).
  * Pure: takes routes[], returns Finding[].
@@ -67,5 +84,24 @@ export function scanApiBrokenAuthz(routes) {
       }
     }
   }
+
+  // #9 — CWE-306 app-level pass. If the app authenticates SOME route (so our
+  // auth-detection works for it), a destructive route left unauthenticated is a
+  // missing-auth bug even when its file-local siblings are also public (the
+  // in-file inconsistency rule above cannot see that case). Scoped to DELETE and
+  // id-taking PUT/PATCH — the least-ambiguous "should never be public" shapes —
+  // so intentionally-public POSTs (login / signup / webhooks) don't false-fire.
+  // `push` dedupes by file:line, so a route already flagged BFLA/BOLA above is
+  // not double-reported here.
+  const appHasAuth = routes.some((r) => r && r.hasAuth);
+  if (appHasAuth) {
+    for (const r of routes) {
+      if (!r || r.hasAuth || !r.file || r.path === '(file-based)') continue;
+      const destructive = r.method === 'DELETE'
+        || ((r.method === 'PUT' || r.method === 'PATCH') && ID_PARAM.test(r.path || ''));
+      if (destructive) push(mk306(r));
+    }
+  }
+
   return findings;
 }

package/src/sast/file-upload.js

@@ -0,0 +1,118 @@
+// CWE-434 — Unrestricted file upload (#6). A whole CWE that had NO detector.
+//
+// Bread-and-butter for the vibecoder stacks (Next.js / Express / Supabase /
+// Firebase / FastAPI / Flask): an upload endpoint that writes an attacker-
+// supplied file without restricting its type/extension/size, or that uses the
+// client-supplied filename as the on-disk destination (also CWE-22 path
+// traversal — `../../x` in the filename escapes the upload dir).
+//
+// Precision is the whole game here (uploads are everywhere). Each rule fires
+// only on a clear unrestricted shape and is suppressed by the standard guard:
+//   - Multer configured with NEITHER fileFilter NOR limits → unrestricted.
+//   - A write whose destination is built from the CLIENT filename
+//     (file.originalname / req.files.*.name / UploadFile.filename) with no
+//     sanitizer (basename / uuid / randomUUID / sanitize / whitelist) nearby.
+// A validated upload (fileFilter+limits, or a generated/sanitized name) does
+// NOT match.
+import { blankComments } from './_comment-strip.js';
+
+const JS_EXT = /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i;
+const PY_EXT = /\.py$/i;
+
+const _lineOf = (raw, idx) => raw.substring(0, idx).split('\n').length;
+const _snip = (raw, line) => (raw.split('\n')[line - 1] || '').trim().slice(0, 200);
+// A sanitizer for the destination filename anywhere in the ±6-line window.
+const NAME_SANITIZER = /\b(?:basename|randomUUID|uuidv4|uuid4|uuid\.v4|nanoid|sanitize[-_]?filename|sanitizeFilename|slugify|crypto\.random|secure_filename|werkzeug)\b/i;
+
+function _window(raw, line, half = 6) {
+  const lines = raw.split('\n');
+  const start = Math.max(0, line - 1 - half);
+  const end = Math.min(lines.length, line - 1 + half);
+  return lines.slice(start, end).join('\n');
+}
+
+function mk(file, raw, line, sub, severity, vuln, description, remediation) {
+  return {
+    id: `file-upload:${sub}:${file}:${line}`,
+    severity, file, line,
+    vuln, cwe: 'CWE-434',
+    family: 'unrestricted-file-upload',
+    parser: 'FILE-UPLOAD',
+    subfamily: sub,
+    snippet: _snip(raw, line),
+    description,
+    remediation,
+  };
+}
+
+function scanJs(file, raw, code, out, seen) {
+  const push = (line, mkr) => { const k = `${line}`; if (seen.has(k)) return; seen.add(k); out.push(mkr); };
+
+  // 1) Multer with neither fileFilter nor limits → unrestricted upload config.
+  //    Matches `multer()` and `multer({ ... })` whose options lack both guards.
+  const multerRe = /\bmulter\s*\(\s*(?:\)|\{([\s\S]*?)\}\s*\))/g;
+  let m;
+  while ((m = multerRe.exec(code))) {
+    const opts = m[1] || '';
+    if (/\bfileFilter\b/.test(opts) || /\blimits\b/.test(opts)) continue; // guarded
+    const line = _lineOf(raw, m.index);
+    push(line, mk(file, raw, line, 'multer-unrestricted', 'medium',
+      'Unrestricted file upload — Multer configured with no fileFilter and no limits',
+      'This Multer instance accepts any file of any size. An attacker can upload an executable, oversized, or malicious file (web shell, zip bomb).',
+      'Add a `fileFilter` that allow-lists MIME types / extensions and a `limits: { fileSize }` cap. Store uploads outside the web root and never serve them with their uploaded name.'));
+  }
+
+  // 2) Write whose destination is built from the CLIENT-supplied filename.
+  //    e.g. path.join(dir, file.originalname) / req.files.x.mv('...'+req.files.x.name)
+  //    Also CWE-22: `../../` in the filename escapes the upload dir.
+  const clientName = /\b(?:\w+\.originalname|req\.files(?:\.\w+|\[[^\]]+\])?\.name)\b/;
+  const writeSinks = [
+    /\.mv\s*\(/,                         // express-fileupload
+    /\b(?:fs\.)?(?:writeFile|writeFileSync|createWriteStream)\s*\(/,
+    /\bpath\.join\s*\(/,                 // building the dest path
+  ];
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!clientName.test(lines[i])) continue;
+    if (!writeSinks.some(re => re.test(lines[i]))) continue;
+    const line = i + 1;
+    if (NAME_SANITIZER.test(_window(raw, line))) continue; // sanitized/generated name → safe
+    push(line, mk(file, raw, line, 'client-filename-dest', 'high',
+      'Unrestricted file upload — client-supplied filename used as the write destination',
+      'The uploaded file is written using its client-controlled name. An attacker can choose the extension (upload `shell.php`) or embed path traversal (`../../etc/x`) to escape the upload directory.',
+      'Never trust the uploaded filename. Generate a server-side name (uuid/nanoid) and validate the extension against an allow-list; write with path.basename() into a fixed directory outside the web root.'));
+  }
+}
+
+function scanPy(file, raw, code, out, seen) {
+  const push = (line, mkr) => { const k = `${line}`; if (seen.has(k)) return; seen.add(k); out.push(mkr); };
+  // Flask: request.files['x'].save(os.path.join(dir, file.filename))
+  // FastAPI: open(file.filename, ...) / shutil.copyfileobj(upload.file, open(upload.filename))
+  const clientName = /\b\w+\.filename\b/;
+  const writeSinks = [/\.save\s*\(/, /\bopen\s*\(/, /\bos\.path\.join\s*\(/, /\bcopyfileobj\s*\(/];
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!clientName.test(lines[i])) continue;
+    if (!writeSinks.some(re => re.test(lines[i]))) continue;
+    const line = i + 1;
+    if (NAME_SANITIZER.test(_window(raw, line))) continue; // secure_filename / uuid → safe
+    push(line, mk(file, raw, line, 'client-filename-dest', 'high',
+      'Unrestricted file upload — client-supplied filename used as the write destination',
+      'The uploaded file is saved under its client-controlled name. An attacker can choose the extension or embed path traversal to escape the upload directory.',
+      'Use werkzeug secure_filename() (Flask) or generate a uuid name; validate the extension against an allow-list and write into a fixed directory outside the web root.'));
+  }
+}
+
+export function scanFileUpload(fp, raw) {
+  if (!raw || raw.length > 500_000) return [];
+  const isJs = JS_EXT.test(fp), isPy = PY_EXT.test(fp);
+  if (!isJs && !isPy) return [];
+  // Cheap relevance gate — skip files with no upload surface.
+  if (!/\b(?:multer|originalname|req\.files|UploadFile|\.filename|createWriteStream|\.mv\s*\()/i.test(raw)) return [];
+  const code = blankComments(raw, isPy ? 'py' : null);
+  const out = [];
+  const seen = new Set();
+  try { if (isJs) scanJs(fp, raw, code, out, seen); } catch { /* per-file best-effort */ }
+  try { if (isPy) scanPy(fp, raw, code, out, seen); } catch { /* per-file best-effort */ }
+  return out;
+}

package/src/sast/llm-cost-advisor.js

@@ -0,0 +1,88 @@
+// LLM cost + prompt-cache advisor (PRD CACHE_ECONOMICS_V2 — F1 cache-hygiene +
+// P3 per-provider model/depth recommendation), as a SAST detector over the
+// user's own LLM-calling code.
+//
+// Two rules, both gated on detecting an LLM provider in the file (low FP), both
+// emitted at ADVISORY severity so they never inflate security counts:
+//
+//   1. cache-killer: a non-deterministic value (Date.now / uuid / datetime.now)
+//      interpolated into a prompt/system string — defeats prompt caching for the
+//      whole prefix after it (every provider).
+//   2. over-provisioned: a flagship model used at a high reasoning depth — the
+//      catalog suggests a cheaper model + lower depth WITHIN the same provider.
+//
+// Provider/model/cache facts come from posture/provider-catalog.js (P1/P2).
+import { blankComments } from './_comment-strip.js';
+import { detectProvider, PROVIDERS, modelEntry, cheaperModel, depthAxis, cacheModel, SOURCED_AT } from '../posture/provider-catalog.js';
+
+// How this provider's cache behaves — shapes the cache-killer remediation.
+const CACHE_HINT = {
+  explicit: "Claude's prompt cache (set on a stable prefix via cache_control)",
+  automatic: 'the provider\'s automatic prompt cache (matches a ≥1024-token static prefix)',
+  'implicit-explicit': "Gemini's implicit/explicit context cache",
+};
+
+const NONDET = /\b(?:Date\.now|new\s+Date|datetime\.now|datetime\.utcnow|time\.time|uuid4|uuidv4|crypto\.randomUUID|uuid\.uuid4|secrets\.token_hex|os\.urandom)\s*\(/;
+const PROMPT_CTX = /\b(?:system|instructions?|developer|messages|prompt)\b|["']role["']\s*:\s*["'](?:system|developer)["']/i;
+const EXPENSIVE_DEPTH = /(?:reasoning_effort|["']?effort["']?)\s*[:=]\s*["']?(?:high|xhigh|max)["']?|thinking[_]?budget\s*[:=]\s*\(?\s*(?:[1-9]\d{4,})/i;
+
+const lineOf = (raw, idx) => raw.substring(0, idx).split('\n').length;
+const snippetAt = (raw, line) => (raw.split('\n')[line - 1] || '').trim().slice(0, 200);
+
+export function scanLlmCost(fp, raw) {
+  if (!/\.(?:js|jsx|ts|tsx|mjs|cjs|py|rb)$/i.test(fp)) return [];
+  if (!raw || raw.length > 500_000) return [];
+  const provider = detectProvider(raw);
+  if (!provider) return [];
+  const code = blankComments(raw);
+  const lines = code.split('\n');
+  const findings = [];
+  const seen = new Set();
+  const push = (f) => { if (!seen.has(f.id)) { seen.add(f.id); findings.push(f); } };
+  const pLabel = PROVIDERS[provider].label;
+
+  // ── Rule 1: non-deterministic content in a prompt-building string ──────────
+  for (let i = 0; i < lines.length; i++) {
+    if (!NONDET.test(lines[i])) continue;
+    // Require a prompt-context marker on the SAME line — the volatile value is
+    // being built into a system/prompt/messages string. (Same-line keeps FP low:
+    // a `datetime.now()` in a nearby log line must not trip on a `SYSTEM =` const
+    // three lines up.)
+    if (!PROMPT_CTX.test(lines[i])) continue;
+    const line = i + 1;
+    push({
+      id: `llm-cache-nondeterminism:${fp}:${line}`,
+      file: fp, line,
+      vuln: `Prompt-cache killer (cost advisory) — non-deterministic value in a ${pLabel} prompt prefix`,
+      severity: 'low', cwe: 'CWE-400', family: 'llm-cache', parser: 'LLM-COST', confidence: 0.6,
+      snippet: snippetAt(raw, line),
+      remediation: `A timestamp / UUID / random value in the cached prefix changes its bytes every request, so ${CACHE_HINT[cacheModel(provider)?.kind] || 'the prompt cache'} never hits and you pay full input price every call. Move the volatile value AFTER the stable prefix (or out of the prompt entirely) so the long shared prefix stays byte-identical and cacheable.`,
+    });
+  }
+
+  // ── Rule 2: flagship model at high depth → recommend a cheaper option ──────
+  const expensiveModels = PROVIDERS[provider].models.filter(m => m.tier >= 2);
+  const dax = depthAxis(provider);
+  for (let i = 0; i < lines.length; i++) {
+    const m = expensiveModels.find(em => em.match.test(lines[i]));
+    if (!m) continue;
+    // Look for an expensive depth setting in the same call window (±6 lines).
+    const win = lines.slice(Math.max(0, i - 6), i + 7).join('\n');
+    if (!EXPENSIVE_DEPTH.test(win)) continue;
+    const line = i + 1;
+    const cheaper = cheaperModel(provider, m.id);
+    const alt = cheaper
+      ? `${cheaper.id} at ${dax?.knob}=${dax?.cheap}`
+      : `a lower ${dax?.knob || 'reasoning depth'}`;
+    push({
+      id: `llm-overprovisioned:${fp}:${line}`,
+      file: fp, line,
+      vuln: `Over-provisioned model (cost advisory) — ${pLabel} flagship at high depth`,
+      severity: 'info', cwe: 'CWE-400', family: 'llm-cost', parser: 'LLM-COST', confidence: 0.5,
+      snippet: snippetAt(raw, line),
+      remediation: `This call pairs a flagship model (${m.id}) with a high ${dax?.knob || 'reasoning'} setting — the most expensive combination in ${pLabel}. If the task isn't intelligence-critical, try ${alt} first and measure: it can cut cost several-fold with little quality loss. Keep the flagship+high only where correctness clearly needs it. (Catalog pricing as of ${SOURCED_AT}.)`,
+    });
+  }
+
+  return findings;
+}

package/src/util/untrusted.js

@@ -0,0 +1,148 @@
+// Untrusted-content hardening primitives (addition #4: meta-security —
+// self-hardening the agent surface).
+//
+// Attacker-authored code and finding text reach several LLM prompts, several
+// rendered outputs (issue / PR / ticket bodies), and audit writers. This module
+// is the single, tested place that neutralizes that content before it crosses a
+// trust boundary. See docs/AGENT_THREAT_MODEL.md for the path→CWE map.
+//
+// Design notes:
+//   - Pure + dependency-light (node:crypto, node:fs only). No network, no state.
+//   - Fail-closed: unknown/adversarial input degrades to the safe value ('' or
+//     `false`), never throws.
+//   - Deterministic: fenceUntrusted derives its nonce from the content hash so
+//     the wrapping is reproducible and testable (no Date.now / random source).
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ─── escapeMarkdown ──────────────────────────────────────────────────────────
+// Neutralize markdown/HTML control characters so attacker-controlled finding
+// text cannot inject markup, links, or code spans when interpolated into an
+// issue / PR / ticket body. HTML-dangerous chars (& < >) are entity-encoded so
+// no raw tag can render in any markdown flavour; markdown-structural chars
+// (backtick [ ] ! and backslash) are backslash-escaped.
+//
+// Non-strings collapse to '' (fail-closed — a null vuln never becomes "null").
+//
+// Order is load-bearing: escape `&` before we emit `&amp;`/`&lt;`/`&gt;`, and
+// escape literal `\` before we introduce our own backslashes, so nothing is
+// double-consumed.
+export function escapeMarkdown(s) {
+  if (typeof s !== 'string') return '';
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\[/g, '\\[')
+    .replace(/\]/g, '\\]')
+    .replace(/!/g, '\\!');
+}
+
+// ─── fenceUntrusted ──────────────────────────────────────────────────────────
+// Wrap untrusted text in a clearly-delimited block whose delimiter carries a
+// per-call nonce, so an injected close-delimiter inside the text cannot
+// terminate the fence early (the classic prompt-injection "break out of the
+// data block" move). Intended for the LLM-prompt paths (triage / dedup / fix)
+// where the model must treat the wrapped span as inert data.
+//
+// The nonce is derived deterministically from a sha256 of the content (first 8
+// hex). That makes it (a) reproducible/testable and (b) unguessable by the
+// author of the content — an attacker cannot pre-compute the resulting nonce to
+// forge a matching close-delimiter, because the nonce depends on the very bytes
+// they would have to write.
+//
+// Returns { text, nonce }.
+export function fenceUntrusted(s, label = 'untrusted') {
+  const content = typeof s === 'string' ? s : '';
+  const lbl = String(label || 'untrusted').replace(/[^A-Za-z0-9_-]/g, '');
+  const nonce = createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 8);
+  const open = `<<BEGIN ${lbl} ${nonce}>>`;
+  const close = `<<END ${lbl} ${nonce}>>`;
+  return { text: `${open}\n${content}\n${close}`, nonce };
+}
+
+// ─── isAllowedFetchHost ──────────────────────────────────────────────────────
+// Guard for any outbound fetch whose URL can be influenced by untrusted finding
+// data (e.g. a metadata/advisory URL lifted from a dependency manifest). Blocks
+// SSRF against link-local / loopback / RFC1918 targets AND enforces an explicit
+// allowlist — a host must be BOTH non-internal AND on the allowlist. Empty
+// allowlist ⇒ nothing passes (fail-closed). Malformed URL ⇒ false.
+export function isAllowedFetchHost(url, allowlist = []) {
+  let host;
+  try {
+    host = new URL(String(url)).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (!host) return false;
+  // Strip IPv6 brackets: "[::1]" → "::1".
+  const h = host.replace(/^\[/, '').replace(/\]$/, '');
+
+  // Block internal / link-local / loopback destinations up front — these must
+  // never be reachable even if an operator mistakenly allowlists one.
+  if (h === 'localhost' || h.endsWith('.localhost')) return false;
+  if (h === '::1' || h === '0.0.0.0') return false;
+  if (h === '169.254.169.254' || h.startsWith('169.254.')) return false; // link-local + cloud metadata
+  if (h.startsWith('127.')) return false;                                 // loopback /8
+  if (h.startsWith('10.')) return false;                                  // RFC1918 /8
+  if (h.startsWith('192.168.')) return false;                            // RFC1918 /16
+  const m172 = h.match(/^172\.(\d{1,3})\./);                              // RFC1918 172.16-31/12
+  if (m172) {
+    const oct = Number(m172[1]);
+    if (oct >= 16 && oct <= 31) return false;
+  }
+
+  const allow = Array.isArray(allowlist)
+    ? allowlist.map((a) => String(a).toLowerCase())
+    : [];
+  if (allow.length === 0) return false; // fail-closed: no allowlist ⇒ deny all
+  return allow.includes(h);
+}
+
+// ─── redactSecrets ───────────────────────────────────────────────────────────
+// Mask token-shaped substrings before finding-adjacent text is written to an
+// audit log or handed to an LLM. The provider/scheme prefix is preserved so a
+// human triager can still tell WHAT kind of credential leaked without seeing
+// its value. Non-strings collapse to ''.
+const _REDACTED = '***REDACTED***';
+export function redactSecrets(s) {
+  if (typeof s !== 'string') return '';
+  return s
+    // URL basic-auth: scheme://user:password@ → keep user, mask password.
+    .replace(/(\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+@/gi, `$1${_REDACTED}@`)
+    // Authorization: Bearer <token>
+    .replace(/\b(Authorization\s*:\s*Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, `$1${_REDACTED}`)
+    // ?access_token= / &token= / ?token= / &access_token=
+    .replace(/([?&](?:access_token|token)=)[^&\s#]+/gi, `$1${_REDACTED}`)
+    // Raw provider token prefixes (GitHub PATs, Anthropic keys). Keep prefix.
+    .replace(/\b(ghp_|gho_|ghu_|ghs_|github_pat_|sk-ant-)[A-Za-z0-9_-]+/g, `$1${_REDACTED}`);
+}
+
+// ─── secure filesystem writes ────────────────────────────────────────────────
+// Audit logs, scan state, and any file that may carry finding text or secrets
+// must be owner-only. openSync's mode argument is still masked by the process
+// umask, so writeSecure ALSO chmods explicitly — the file is 0600 regardless of
+// the ambient umask. secureDirMode is the matching 0700 for any parent dir we
+// have to create.
+export const secureFileMode = 0o600;
+export const secureDirMode = 0o700;
+
+export function writeSecure(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: secureDirMode });
+    try { fs.chmodSync(dir, secureDirMode); } catch { /* best-effort */ }
+  }
+  const fd = fs.openSync(filePath, 'w', secureFileMode);
+  try {
+    fs.writeSync(fd, typeof data === 'string' ? data : String(data ?? ''));
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Force the mode down even if umask loosened it at creation time.
+  fs.chmodSync(filePath, secureFileMode);
+  return filePath;
+}