@clear-capabilities/agentic-security-scanner 0.185.0 → 0.186.1

package/src/sast/_call-args.js

@@ -0,0 +1,70 @@
+// Argument splitting for guard recognisers that must look at WHAT a call is
+// given, not at the text around it. Quote- and bracket-aware; handles template
+// literal substitutions. Not a parser: it answers "where does each top-level
+// argument start and end" for text that begins right after a call's '('.
+
+const isQuote = (c) => c === '"' || c === "'" || c === '`';
+
+/**
+ * Split the text that follows a call's opening paren into its top-level
+ * arguments (source text, quotes intact). Returns null when the closing paren
+ * is not in the text given, so a caller never reasons about a truncated call.
+ */
+export function callArguments(text) {
+  const args = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (isQuote(c)) {
+      const q = c;
+      i++;
+      while (i < text.length && text[i] !== q) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (q === '`' && text[i] === '$' && text[i + 1] === '{') {
+          let d = 1; i += 2;
+          while (i < text.length && d > 0) { if (text[i] === '{') d++; else if (text[i] === '}') d--; i++; }
+          continue;
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      if (depth === 0) {
+        const last = text.slice(start, i);
+        if (last.trim() !== '' || args.length > 0) args.push(last);
+        return args;
+      }
+      depth--;
+    } else if (c === ',' && depth === 0) {
+      args.push(text.slice(start, i));
+      start = i + 1;
+    }
+    i++;
+  }
+  // The window ended inside the call (a long callback, a wrapped call). The
+  // arguments completed so far are still exactly what the call was given; the
+  // unfinished last one is dropped rather than guessed. `partial` lets a caller
+  // that needs the whole call refuse.
+  if (args.length === 0) return null;
+  args.partial = true;
+  return args;
+}
+
+/**
+ * Find the first call on or just after `line` (1-based) whose callee matches
+ * `calleeRe` (which must end at the opening paren) and return its arguments.
+ * Looks at the finding line and the next three, because a call is routinely
+ * wrapped. Returns null when there is no such call or it is not closed.
+ */
+export function callArgumentsAt(lines, line, calleeRe) {
+  if (!Array.isArray(lines) || !Number.isInteger(line) || line < 1) return null;
+  const text = lines.slice(line - 1, line + 3).join('\n');
+  const m = calleeRe.exec(text);
+  if (!m) return null;
+  return callArguments(text.slice(m.index + m[0].length));
+}

package/src/sast/init-scope.js

@@ -0,0 +1,87 @@
+// Is a source position inside a function body, or at module/initialisation
+// level? Some hazards exist only while the process is serving work: a blocking
+// call made once at module load (reading a TLS key, a config file) delays
+// startup once, and nothing is waiting on the event loop yet. The same call in
+// a request callback stalls every connection.
+//
+// A position is inside a function when it is inside
+//   * a `{ ... }` block opened by `=>`, a `function` header, a method or class
+//     member header (`name(params) {`), or an async/generator form,
+//   * the body of an expression-bodied arrow (`(p) => fs.readFileSync(p)`),
+//     which runs when the arrow is CALLED, not where it is written, or
+//   * a class body (field initialisers run per instance).
+// Plain blocks (`if`, `for`, `try`, `else`) and object literals are not function scopes.
+//
+// Operates on a comment- and string-blanked view so braces in strings or
+// comments never count. It is a lexical approximation (no parse). The one error
+// that matters is calling a function body "module level", because that hides a
+// finding, so a block is classed as a function unless it is positively a control
+// block or a literal, and parameter lists are matched by bracket depth, not by a
+// pattern that stops at a fixed nesting.
+
+const CONTROL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'with', 'else', 'try', 'finally', 'do']);
+const CLASS_HEAD = /\bclass\b\s*[\w$]*(?:\s+extends\s+[\w$.()]+)?\s*$/;
+
+/** Index of the '(' matching the ')' at `closeIdx`, scanning backwards; -1 if unbalanced. */
+function matchingOpenParen(text, closeIdx) {
+  let depth = 0;
+  for (let i = closeIdx; i >= 0; i--) {
+    const c = text[i];
+    if (c === ')') depth++;
+    else if (c === '(') { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+function opensFunction(text, braceIdx) {
+  let end = braceIdx;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  const before = text.slice(Math.max(0, end - 400), end);
+  if (/=>$/.test(before)) return true;
+  if (CLASS_HEAD.test(before)) return true;
+  // `else {`, `try {`, `finally {`, `do {`, `catch {` carry no parenthesised head
+  const bare = /(?:^|[^\w$.])([A-Za-z_$][\w$]*)$/.exec(before);
+  if (bare && CONTROL_KEYWORDS.has(bare[1])) return false;
+  // find the ')' that ends a parameter list, allowing a return type annotation `): Type {`
+  let closeIdx = end - 1;
+  if (text[closeIdx] !== ')') {
+    const m = /\)\s*:\s*[^(){};=]*$/.exec(before);
+    if (!m) return false;
+    closeIdx = end - before.length + m.index;
+  }
+  const openIdx = matchingOpenParen(text, closeIdx);
+  if (openIdx < 0) return true; // cannot match the head: keep findings, so call it a function
+  const head = text.slice(Math.max(0, openIdx - 80), openIdx).replace(/\s+$/, '');
+  const word = /([A-Za-z_$][\w$]*)$/.exec(head);
+  if (word) return !CONTROL_KEYWORDS.has(word[1]); // `if (` `while (` ...: control; any other name( ... ) { is a function or method
+  if (/\bfunction\s*\*?$/.test(head)) return true; // `function (` and `function* (`
+  return false;
+}
+
+/**
+ * @param {string} blanked  source with comments and string bodies blanked
+ * @param {number} offset   index into `blanked`
+ * @returns {boolean} true when `offset` is lexically inside a function body
+ */
+export function insideFunctionBody(blanked, offset) {
+  // entries: 'F' function block, 'B' other block, 'P' paren/bracket, 'A' expression-bodied arrow
+  const stack = [];
+  const end = Math.min(offset, blanked.length);
+  for (let i = 0; i < end; i++) {
+    const c = blanked[i];
+    if (c === '{') stack.push(opensFunction(blanked, i) ? 'F' : 'B');
+    else if (c === '(' || c === '[') stack.push('P');
+    else if (c === '}' || c === ')' || c === ']') {
+      while (stack.length && stack[stack.length - 1] === 'A') stack.pop(); // an arrow body ends where its enclosing bracket closes
+      stack.pop();
+    } else if ((c === ',' || c === ';') && stack[stack.length - 1] === 'A') {
+      stack.pop(); // ... or at a separator at its own nesting level
+    } else if (c === '=' && blanked[i + 1] === '>') {
+      let j = i + 2;
+      while (j < blanked.length && /\s/.test(blanked[j])) j++;
+      if (blanked[j] !== '{') stack.push('A');
+      i++;
+    }
+  }
+  return stack.some((e) => e === 'F' || e === 'A');
+}

package/src/sast/listen-bind-address.js

@@ -0,0 +1,49 @@
+// The `address` a `listen` callback receives.
+//
+//   server.listen({ port }, (err, address) => console.log(`listening on ${address}`))
+//
+// `address` here is the socket address the server just bound (host and port),
+// handed to the callback by the server. It is not a person's postal address, so a
+// rule that classifies a value by the NAME `address` must not treat this binding
+// as personal data. The rule is about the binding site, not about the word: the
+// same name bound anywhere else (a form field, a column, a request property) is
+// unaffected.
+
+/** Index just past the paren that closes the one opened at `openIdx`, or -1 when the text ends first. */
+function closeOfParen(text, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'" || c === '`') {
+      const q = c; i++;
+      while (i < text.length && text[i] !== q) { if (text[i] === '\\') i++; i++; }
+    } else if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i + 1; }
+  }
+  return -1;
+}
+
+/**
+ * Is the identifier at `idx` in `raw` a parameter declared by a callback passed
+ * to a `.listen(` call? `idx` is any position at or after the callback header
+ * (the use site); the header is searched backwards within a bounded window, and
+ * must sit inside the listen call's own parentheses, so a function declared after
+ * the call has closed does not count.
+ */
+export function isListenCallbackParam(raw, idx, name) {
+  if (typeof raw !== 'string' || !name) return false;
+  const from = Math.max(0, idx - 800);
+  const at = raw.slice(from, idx).lastIndexOf('.listen(');
+  if (at < 0) return false;
+  const start = from + at;
+  const openIdx = start + '.listen'.length;
+  const windowEnd = idx + name.length + 80;
+  const close = closeOfParen(raw.slice(start, windowEnd), openIdx - start);
+  // the call closed before the use site: the use is not inside the callback
+  if (close !== -1 && start + close <= idx) return false;
+  const after = raw.slice(start, close === -1 ? windowEnd : Math.min(windowEnd, start + close));
+  const id = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const arrow = new RegExp(String.raw`\([^)]*\b${id}\b[^)]*\)\s*=>|\b${id}\s*=>`);
+  const fn = new RegExp(String.raw`\bfunction\b[^(]*\([^)]*\b${id}\b[^)]*\)`);
+  return arrow.test(after) || fn.test(after);
+}

package/src/sast/redirect-target.js

@@ -0,0 +1,106 @@
+// Open-redirect target shape (CWE-601): can the part of a redirect target the
+// program does not control change the ORIGIN the browser is sent to?
+//
+// A redirect target is attacker-steerable to another origin only if the
+// attacker controls the authority (scheme, host, port) of the resulting URL.
+// A target that begins with a literal which already fixes the authority cannot
+// be moved off-origin by whatever is appended after it:
+//
+//   '/user/' + id                   path-absolute, second character is a name
+//                                   character: same origin, whatever `id` is
+//   'https://app.example.com/' + p  the whole authority is in the literal and a
+//                                   '/' closes it, so `p` is only path/query
+//
+// and these are NOT pinned, because the dynamic part decides the authority:
+//
+//   '/' + x                x = '/evil.example'  gives '//evil.example'
+//   '//' + x, '/\\' + x    protocol-relative (browsers treat '\' as '/')
+//   'https://app.example.com' + x   x = '.evil.example' or '@evil.example'
+//   '' + x, x, x + '/path'          no literal prefix at all
+//
+// This is deliberately the ONLY thing decided here. It reads the text of the
+// redirect call's first argument; it does not decide whether the dynamic part
+// is attacker-controlled (that is the taint layer's question) and it never
+// reads a file name, a fixture name or a label.
+
+import { callArgumentsAt } from './_call-args.js';
+
+const REDIRECT_CALL_RE = /\b(?:redirect|sendRedirect|Redirect|redirect_to|HttpResponseRedirect|RedirectResponse|redirectTo|permanentRedirect)\s*\(/;
+
+/**
+ * Leading literal text of an expression, and whether anything dynamic follows.
+ * Handles 'a' + x, "a" + x + y, `a${x}`, and a lone literal.
+ * `literal` is the decoded-enough prefix (escapes kept verbatim, which is safe
+ * here because the checks below only look at slashes and the first characters).
+ */
+export function leadingLiteral(expr) {
+  const s = String(expr).trim();
+  let i = 0;
+  let prefix = '';
+  let dynamic = false;
+  for (;;) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    const c = s[i];
+    if (c === '"' || c === "'") {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== c) { if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; } else body += s[j++]; }
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      prefix += body; i = j + 1;
+    } else if (c === '`') {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== '`') {
+        if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; continue; }
+        if (s[j] === '$' && s[j + 1] === '{') { dynamic = true; break; }
+        body += s[j++];
+      }
+      prefix += body;
+      if (dynamic) return { literal: prefix, dynamic: true, closed: true };
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      i = j + 1;
+    } else {
+      return { literal: prefix, dynamic: true, closed: true };
+    }
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) return { literal: prefix, dynamic, closed: true };
+    if (s[i] === '+') { i++; continue; }
+    // anything else after a literal (a call suffix, `.concat`, `%`, ...): not a plain literal
+    return { literal: prefix, dynamic: true, closed: true };
+  }
+  return { literal: prefix, dynamic, closed: true };
+}
+
+/** A literal prefix that fixes the origin of the URL it begins. */
+export function prefixPinsOrigin(prefix) {
+  // Path-absolute: '/' then a character that is neither '/' nor '\' (both are
+  // read as a second slash, turning the reference into a network-path one).
+  if (/^\/[^\/\\\s]/.test(prefix)) return true;
+  // Absolute URL whose authority is complete: scheme://authority/ .
+  if (/^[A-Za-z][A-Za-z0-9+.\-]*:\/\/[^\/?#\\\s]+\//.test(prefix)) return true;
+  return false;
+}
+
+/**
+ * Does the redirect argument keep the destination on a fixed origin?
+ * `arg` is the first argument of the redirect call. A numeric first argument
+ * (`res.redirect(302, url)`) is skipped by the caller, not here.
+ */
+export function redirectArgumentPinsOrigin(arg) {
+  const { literal, dynamic, closed } = leadingLiteral(arg);
+  if (!closed) return false;
+  if (!dynamic) return literal.length > 0; // a fully static target
+  return prefixPinsOrigin(literal);
+}
+
+/**
+ * Inspect source lines starting at `line` (1-based) for a redirect call and
+ * decide whether its target pins the origin. Returns null when no redirect
+ * call is found (no opinion), else true/false.
+ */
+export function redirectTargetPinsOriginAt(lines, line) {
+  const args = callArgumentsAt(lines, line, REDIRECT_CALL_RE);
+  if (!args || args.length === 0) return null;
+  // res.redirect(302, '/x'): the status code is not the target
+  const target = args.length > 1 && /^\s*\d{3}\s*$/.test(args[0]) ? args[1] : args[0];
+  return redirectArgumentPinsOrigin(target);
+}

package/src/sast/reflected-input.js

@@ -0,0 +1,76 @@
+// What a response-writing call actually reflects.
+//
+// A reflected-XSS shape needs two things on the same call: a value the REQUEST
+// supplied, and that value reaching the response without HTML encoding. Matching
+// the text `req.` anywhere in the arguments gets both wrong:
+//
+//   * `req` carries framework and application state next to the request's own
+//     input. `req.session.count`, `req.user.name`, `req.app.locals.title` and
+//     `req.pet.id` are server-side values (a session store, a database row an
+//     earlier middleware loaded, the app's configuration). They are second-order
+//     data at most, not something the current request typed. Only the properties
+//     that carry the request's input count (REQUEST_INPUT_PROPS).
+//   * `escapeHtml(req.params.id)` has the request value, but it is encoded before
+//     it is written. A value inside an HTML-escaper call is not reflected raw.
+//
+// This decides ONLY "does the call reflect raw request input". It does not model
+// a variable assigned earlier; callers that match only the call text use it as a
+// precision gate, and a flow through a variable is the taint layer's job.
+
+import { callArgumentsAt } from './_call-args.js';
+
+/** Properties of the request object that hold what the client sent. */
+const REQUEST_INPUT_PROPS = [
+  'body', 'query', 'params', 'headers', 'header', 'get', 'param', 'cookies', 'signedCookies',
+  'hostname', 'host', 'subdomains', 'path', 'url', 'originalUrl', 'baseUrl', 'files', 'file',
+  'rawBody', 'ip', 'ips', 'vhost', 'rawHeaders', 'trailers',
+];
+
+const REQ_INPUT_RE = new RegExp(
+  String.raw`\breq(?:uest)?\s*(?:\.\s*(?:${REQUEST_INPUT_PROPS.join('|')})\b|\[\s*['"](?:${REQUEST_INPUT_PROPS.join('|')})['"]\s*\])`
+  + String.raw`|\.(?:body|query|params)\s*\.`,
+);
+
+// HTML output encoders whose result is safe to place in HTML text.
+const ESCAPER_CALL_RE = /\b(?:escapeHtml|escape_html|escapeHTML|sanitizeHtml|sanitize_html|DOMPurify\s*\.\s*sanitize|he\s*\.\s*(?:encode|escape)|_\s*\.\s*escape|validator\s*\.\s*escape|xss|striptags|escape)\s*\(/g;
+
+/** Remove every balanced `escaper(...)` call from an expression. */
+export function stripHtmlEscaperCalls(expr) {
+  let out = String(expr);
+  for (let guard = 0; guard < 50; guard++) {
+    ESCAPER_CALL_RE.lastIndex = 0;
+    const m = ESCAPER_CALL_RE.exec(out);
+    if (!m) return out;
+    let i = m.index + m[0].length;
+    let depth = 1;
+    while (i < out.length && depth > 0) {
+      const c = out[i];
+      if (c === '"' || c === "'" || c === '`') {
+        const q = c; i++;
+        while (i < out.length && out[i] !== q) { if (out[i] === '\\') i++; i++; }
+      } else if (c === '(') depth++;
+      else if (c === ')') depth--;
+      i++;
+    }
+    if (depth !== 0) return out; // unbalanced: leave it, the caller keeps the finding
+    out = out.slice(0, m.index) + '/*escaped*/' + out.slice(i);
+  }
+  return out;
+}
+
+/** Does this expression text contain raw (unescaped) request input? */
+export function reflectsRawRequestInput(exprText) {
+  return REQ_INPUT_RE.test(stripHtmlEscaperCalls(exprText));
+}
+
+const RESPONSE_WRITE_RE = /\bres(?:ponse)?\s*\.\s*(?:send|write|end)\s*\(/;
+
+/**
+ * For a response-write call on or just after `line`: does it reflect raw
+ * request input? Returns null when no such call is found (no opinion).
+ */
+export function responseReflectsRequestInputAt(lines, line) {
+  const args = callArgumentsAt(lines, line, RESPONSE_WRITE_RE);
+  if (!args || args.length === 0) return null;
+  return reflectsRawRequestInput(args.join(','));
+}

package/src/sast/send-file-root.js

@@ -0,0 +1,27 @@
+// File-serving calls that confine the path to a root directory.
+//
+// `res.sendFile(p, { root: DIR })` and `res.download(p, name, { root: DIR })`
+// resolve `p` relative to DIR and reject a path that climbs above it (the
+// underlying file sender answers 403 for a path with a `..` segment when `root`
+// is set). With `root` the user-controlled part is a path inside DIR, not an
+// arbitrary filesystem path, so it is not a traversal sink. Without `root` the
+// path must be absolute and the caller owns containment, so the finding stays.
+//
+// Only a literal `root:` property in an inline options object is recognised.
+// `{ ...opts }`, a variable `opts`, or `root` only set elsewhere is not seen and
+// leaves the finding in place: unknown stays conservative.
+
+import { callArgumentsAt } from './_call-args.js';
+
+const SEND_FILE_CALL_RE = /\b(?:sendFile|download)\s*\(/;
+
+/**
+ * Is the file-serving call at `line` given an options object with a `root`?
+ * Returns null when no such call is found, else true/false.
+ */
+export function sendFileConfinedToRootAt(lines, line) {
+  const args = callArgumentsAt(lines, line, SEND_FILE_CALL_RE);
+  if (!args) return null;
+  if (args.length < 2) return false;
+  return args.slice(1).some((a) => /^\s*\{[^]*?\broot\s*:/.test(a));
+}

package/src/sast/sensitive-data-logging.js

@@ -4,10 +4,45 @@
 // Covers JS (console/winston/pino/bunyan), Python (logging/print),
 // Go (log/fmt.Printf).
 
+import { isListenCallbackParam } from './listen-bind-address.js';
+
 const PII_CONTEXT = /\b(email|ssn|password|phone|dob|date_of_birth|credit_card|card_number|social_security|passport|medical_record|ip_address|first_name|last_name|address|zip_code|bank_account)\b/i;
 
 function _line(raw, idx) { return raw.slice(0, idx).split('\n').length; }
 
+// The detector is about a VARIABLE with a PII-ish name being logged, so a PII word
+// that only appears as prose inside a string literal is not evidence of anything.
+// Keep identifiers and the expressions inside template substitutions and f-string
+// fields; drop the text of plain string literals and the literal parts of template
+// strings.
+function _codeOnly(text) {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const fString = (c === '"' || c === "'") && /(?:^|[^\w])[rRbB]?[fF][rR]?$/.test(text.slice(Math.max(0, i - 3), i));
+    if ((c === '"' || c === "'") && !fString) {
+      const q = c; i++;
+      while (i < text.length && text[i] !== q) { if (text[i] === '\\') i++; i++; }
+      out += ' ';
+    } else if (c === '`' || fString) {
+      // template literal (JS) or f-string (Python): the literal text is prose, `${...}` / `{...}` is code
+      const q = c; i++;
+      while (i < text.length && text[i] !== q) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if ((q === '`' && text[i] === '$' && text[i + 1] === '{') || (fString && text[i] === '{' && text[i + 1] !== '{')) {
+          let d = 1; i += q === '`' ? 2 : 1; out += ' ';
+          while (i < text.length && d > 0) { if (text[i] === '{') d++; else if (text[i] === '}') { d--; if (d === 0) break; } out += text[i]; i++; }
+          i++;
+          continue;
+        }
+        i++;
+      }
+      out += ' ';
+    } else out += c;
+  }
+  return out;
+}
+
 const LANG_SINKS = {
   js: {
     ext: /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i,
@@ -51,7 +86,9 @@ export function scanSensitiveDataLogging(fp, raw) {
       const lineNum = _line(raw, m.index);
       const lineEnd = raw.indexOf('\n', m.index);
       const lineText = raw.slice(m.index, lineEnd > 0 ? lineEnd : m.index + 200);
-      if (!PII_CONTEXT.test(lineText)) continue;
+      const piiWords = [..._codeOnly(lineText).matchAll(new RegExp(PII_CONTEXT.source, 'gi'))].map((w) => w[1].toLowerCase());
+      const bindAddr = piiWords.includes('address') && isListenCallbackParam(raw, m.index, 'address');
+      if (!piiWords.some((w) => !(w === 'address' && bindAddr))) continue;
       // Skip if the line contains redaction/masking
       if (/\b(?:redact|mask|sanitize|censor|scrub|\*{3,}|\.{3}|slice\s*\(\s*0\s*,\s*\d\s*\))\b/i.test(lineText)) continue;
       findings.push({