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

package/src/dataflow/catalog.js

@@ -163,6 +163,41 @@ export const CATALOG = [
   // `dict.get(...)`/`config.get(...)` elsewhere in the file does not also
   // fire.
   { kind: 'source', id: 'py-flask-args-get',       language: 'py', framework: 'flask',   match: { type: 'call', callee: 'get', receiver: '^(?:args|form|values|headers|cookies|json|data|GET|POST|FILES|META)$', receiverBase: '^(?:request|req)$' }, label: 'request.args/form/values/headers/cookies/json/data.get() (Flask/Django)', provenance: 'url-param' },
+  // PRD F2.2 — the MULTI-VALUE accessors, which were missing entirely.
+  //
+  // `getlist` is the standard Flask/Werkzeug and Django QueryDict API for a
+  // repeated query parameter (`?host=a&host=b`), and `getall` is its
+  // multidict equivalent. Only `get` was modelled, so every repeated-parameter
+  // flow was invisible to the taint engine.
+  //
+  // This is worth recording because the PRD attributed the miss to Python
+  // COMPREHENSIONS (`[x for x in request.args.getlist(...)]`) and proposed
+  // modelling them. Comprehensions already flow — verified with the same shape
+  // over `request.args.get()`, which the engine tracks end to end. The example
+  // failed on its SOURCE, not on its loop, and modelling comprehensions would
+  // have changed nothing while looking like a fix.
+  { kind: 'source', id: 'py-flask-args-getlist',   language: 'py', framework: 'flask',   match: { type: 'call', callee: 'getlist', receiver: '^(?:args|form|values|headers|cookies|json|data|GET|POST|FILES|META)$', receiverBase: '^(?:request|req)$' }, label: 'request.args/form/values.getlist() (Flask/Django)', provenance: 'url-param' },
+  { kind: 'source', id: 'py-flask-args-getall',    language: 'py', framework: 'flask',   match: { type: 'call', callee: 'getall',  receiver: '^(?:args|form|values|headers|cookies|json|data|GET|POST|FILES|META)$', receiverBase: '^(?:request|req)$' }, label: 'request.args/form/values.getall() (multidict)', provenance: 'url-param' },
+
+  // PRD F2.3 — NETWORK-RESPONSE sources.
+  //
+  // Only two existed, both C++ (`recv`, `recvfrom`), so a response body from an
+  // external service was trusted input everywhere else. It is not: the upstream
+  // may be compromised, attacker-influenced (the far end of an SSRF), or simply
+  // a third party whose output this code renders, executes or shells out with.
+  // This is the same trust boundary as an HTTP request arriving — the direction
+  // is reversed, not the trust.
+  //
+  // Kept under its OWN provenance ('network') rather than folded into
+  // http-body, so a report can say where the value came from and a team that
+  // genuinely trusts its own internal API can filter on it. Collapsing them
+  // would remove exactly the fact needed to triage these.
+  { kind: 'source', id: 'js-fetch-json',   language: 'js', framework: 'fetch', match: { type: 'call', callee: 'json', receiverBase: '^(?:res|resp|response|r)$' }, label: 'HTTP response .json() [fetch]', provenance: 'network' },
+  { kind: 'source', id: 'js-fetch-text',   language: 'js', framework: 'fetch', match: { type: 'call', callee: 'text', receiverBase: '^(?:res|resp|response|r)$' }, label: 'HTTP response .text() [fetch]', provenance: 'network' },
+  { kind: 'source', id: 'js-axios-data',   language: 'js', framework: 'axios', match: { type: 'member', object: 'response', prop: 'data' }, label: 'axios response.data', provenance: 'network' },
+  { kind: 'source', id: 'py-requests-text', language: 'py', framework: 'requests', match: { type: 'member', object: 'resp', prop: 'text' }, label: 'requests response .text', provenance: 'network' },
+  { kind: 'source', id: 'py-requests-json', language: 'py', framework: 'requests', match: { type: 'call', callee: 'json', receiverBase: '^(?:resp|response|r)$' }, label: 'requests response .json()', provenance: 'network' },
+  { kind: 'source', id: 'py-urlopen-read',  language: 'py', framework: 'urllib',   match: { type: 'call', callee: 'read', receiverBase: '^(?:resp|response|r|f)$' }, label: 'urlopen read() [urllib]', provenance: 'network' },
   { kind: 'source', id: 'py-fastapi-request-query',language: 'py', framework: 'fastapi', match: { type: 'call',   callee: 'Query'                  }, label: 'fastapi.Query()' },
   { kind: 'source', id: 'py-fastapi-request-body', language: 'py', framework: 'fastapi', match: { type: 'call',   callee: 'Body'                   }, label: 'fastapi.Body()' },
   { kind: 'source', id: 'py-fastapi-form',         language: 'py', framework: 'fastapi', match: { type: 'call',   callee: 'Form'                   }, label: 'fastapi.Form()' },
@@ -228,6 +263,32 @@ export const CATALOG = [
   { kind: 'source', id: 'py-mcp-tool', language: 'py', framework: 'mcp', match: { type: 'annotation', name: 'mcp.tool' }, label: '@mcp.tool() parameter', provenance: 'agent-tool' },
   { kind: 'source', id: 'py-mcp-server-tool', language: 'py', framework: 'mcp', match: { type: 'annotation', name: 'server.tool' }, label: '@server.tool() parameter', provenance: 'agent-tool' },
 
+  // PRD F5.3 — the SAME trust boundary in JavaScript/TypeScript.
+  //
+  // The agent-tool boundary was modelled for Python only, while the
+  // TypeScript SDK (@modelcontextprotocol/sdk) is the dominant implementation.
+  // A tool argument is attacker-influenced in exactly the way an HTTP body is:
+  // whatever the model was persuaded to pass, by a web page it read, a file it
+  // opened, or another tool's output. Treating it as trusted because "the model
+  // sent it" is the confused-deputy assumption this whole feature exists to
+  // reject.
+  //
+  // `request.params.arguments` is the CallToolRequest shape every SDK server
+  // handler receives; `extra.arguments` covers the newer callback signature.
+  { kind: 'source', id: 'js-mcp-call-args', language: 'js', framework: 'mcp', match: { type: 'member', object: 'params', prop: 'arguments' }, label: 'MCP tool call arguments', provenance: 'agent-tool' },
+  { kind: 'source', id: 'js-mcp-request-params', language: 'js', framework: 'mcp', match: { type: 'member', object: 'request', prop: 'params' }, label: 'MCP request.params', provenance: 'agent-tool' },
+  { kind: 'source', id: 'js-mcp-extra-args', language: 'js', framework: 'mcp', match: { type: 'member', object: 'extra', prop: 'arguments' }, label: 'MCP tool callback arguments', provenance: 'agent-tool' },
+
+  // TOOL OUTPUT is the other half of F5.3's shape (tool output -> model context
+  // -> tool invocation). Content returned by ANOTHER tool or an MCP resource is
+  // not the agent's own reasoning — it is third-party text that reached the
+  // context window. A server that reads a resource and passes it onward is the
+  // indirect-injection path, and it was invisible while only tool INPUT was a
+  // source.
+  { kind: 'source', id: 'js-mcp-tool-result', language: 'js', framework: 'mcp', match: { type: 'member', object: 'result', prop: 'content' }, label: 'MCP tool result content', provenance: 'agent-tool' },
+  { kind: 'source', id: 'js-mcp-resource-contents', language: 'js', framework: 'mcp', match: { type: 'member', object: 'resource', prop: 'contents' }, label: 'MCP resource contents', provenance: 'agent-tool' },
+  { kind: 'source', id: 'py-mcp-tool-result', language: 'py', framework: 'mcp', match: { type: 'member', object: 'result', prop: 'content' }, label: 'MCP tool result content', provenance: 'agent-tool' },
+
   // ─── SOURCES (Go) ─────────────────────────────────────────────────────────
   { kind: 'source', id: 'go-r-form',     language: 'go', framework: 'net/http', match: { type: 'member', object: 'r', prop: 'Form' },     label: 'r.Form' },
   { kind: 'source', id: 'go-r-postform', language: 'go', framework: 'net/http', match: { type: 'member', object: 'r', prop: 'PostForm' }, label: 'r.PostForm' },

package/src/dataflow/engine.js

@@ -572,6 +572,62 @@ function _matchCallCatalog(calleeExpr, argExprs, state, callContext) {
 // labels the finding, and the proof gate demotes it. Recall-preserving, same
 // precedent as falsification.js / proof-gate.js: never removed, never
 // severity-touched.
+// Calls that UNDO an encoding. The catalog has no entry for these — it models
+// sanitizers, and a decoder is the opposite — so they would never be recorded
+// on the path and `sanitizer-gate.js` could not see them.
+//
+// Measured by bench/mutation: `he.decode(escapeHtml(req.query.name))` reaching
+// an HTML sink was labelled SANITIZED. The decode puts back exactly what the
+// escape removed, so that was a missed XSS reported as clean.
+//
+// Deliberately a NAME list rather than a catalog kind: these are not analysis
+// entries with families and effects, they are a short list of well-known
+// inverses, and the gate maps them to the family they reverse.
+const _UNSANITIZER_CALLEES = new Set([
+  'unescape', 'unescapeHtml', 'unescapeHtml3', 'unescapeHtml4',
+  'StringEscapeUtils.unescapeHtml3', 'StringEscapeUtils.unescapeHtml4',
+  'he.decode', 'entities.decode', 'html.decode', 'decodeHTML',
+  'decodeHTMLStrict', 'decodeEntities', 'html.unescape',
+  'html_entity_decode', 'htmlspecialchars_decode', '_.unescape', 'lodash.unescape',
+  'decodeURI', 'decodeURIComponent', 'unquote', 'unquote_plus',
+  'URLDecoder.decode', 'urldecode', 'querystring.unescape',
+]);
+
+// `callee` is an IR NODE, not a string: `{kind:'ident',name:'escapeHtml'}` or
+// `{kind:'member',object:{kind:'ident',name:'he'},prop:'decode'}`. Flattened to
+// the dotted form the name list is written in, plus the bare leaf so a call
+// through an alias (`const {decode} = he`) still matches on an unambiguous name.
+function _calleeNames(callee) {
+  if (!callee || typeof callee !== 'object') return [];
+  if (callee.kind === 'ident' && callee.name) return [callee.name];
+  if (callee.kind === 'member' && callee.prop) {
+    const obj = callee.object;
+    const base = obj && obj.kind === 'ident' && obj.name ? obj.name : null;
+    return base ? [`${base}.${callee.prop}`, callee.prop] : [callee.prop];
+  }
+  return [];
+}
+
+function _unsanitizersInExprTree(expr, out) {
+  if (!expr || typeof expr !== 'object') return;
+  if (expr.kind === 'call') {
+    for (const n of _calleeNames(expr.callee)) {
+      // The bare leaf is accepted only when it is unambiguous on its own.
+      // `decode` is not — jwt.decode, base64 decode, protobuf decode — and
+      // matching it would void correct sanitization claims all over the tree.
+      if (n === 'decode') continue;
+      if (_UNSANITIZER_CALLEES.has(n)) { out.add(n); break; }
+    }
+  }
+  for (const k of ['left', 'right', 'callee', 'object', 'property', 'value']) {
+    if (expr[k] && typeof expr[k] === 'object') _unsanitizersInExprTree(expr[k], out);
+  }
+  for (const k of ['args', 'parts', 'branches', 'elements']) {
+    if (Array.isArray(expr[k])) for (const e of expr[k]) _unsanitizersInExprTree(e, out);
+  }
+  if (Array.isArray(expr.props)) for (const p of expr.props) _unsanitizersInExprTree(p && p.value, out);
+}
+
 function _sanitizersInExprTree(expr, out) {
   if (!expr || typeof expr !== 'object') return;
   if (expr.kind === 'call') {
@@ -592,6 +648,26 @@ function _sanitizersInExprTree(expr, out) {
 }
 
 // Sanitizers applied to `expr`: those called inline within it, plus those
+// Un-sanitizers applied to `expr`, by the same rule: inline in the expression,
+// or inherited from a variable it reads. The inheritance half is what makes it
+// work at all — `const escaped = escapeHtml(x); const name = he.decode(escaped);
+// sink(name)` puts the decode on an ASSIGNMENT, so an expression-tree walk of
+// the sink argument sees only `name` and would never find it.
+function _unsanitizersForExpr(expr, callContext) {
+  const out = new Set();
+  _unsanitizersInExprTree(expr, out);
+  const byVar = callContext && callContext._unsanitizersByVar;
+  if (byVar && byVar.size) {
+    const vars = new Set();
+    _collectExprVars(expr, vars);
+    for (const v of vars) {
+      const s = byVar.get(v);
+      if (s) for (const n of s) out.add(n);
+    }
+  }
+  return out;
+}
+
 // recorded against any variable it reads (`const safe = escapeHtml(x); sink(safe)`).
 function _sanitizersForExpr(expr, callContext) {
   const out = new Set();
@@ -695,8 +771,10 @@ function _sinkFindingsForCall(calleeExpr, argExprs, cat, argTaints, state, callC
         // covers the finding's threat class — an xss escaper on a SQL sink
         // must not read as sanitised.
         const _sanNames = _sanitizersForExpr(taintedArgExpr, callContext);
+        const _unsanNames = _unsanitizersForExpr(taintedArgExpr, callContext);
         findings.push({
           ...(_sanNames.size ? { _sanitizersOnPath: [..._sanNames] } : {}),
+          ...(_unsanNames.size ? { _unsanitizersOnPath: [..._unsanNames] } : {}),
           kind: 'taint',
           sinkId: e.id,
           vuln: e.vuln?.name || 'Tainted Sink',
@@ -759,8 +837,10 @@ function _memberWriteSinkFindings(hits, sourceExpr, state, callContext, line, ta
     const reachingSources = _sourcesReachingExpr(sourceExpr, state, callContext._taintSources);
     const traceForThisFinding = reachingSources.length ? reachingSources.slice(0, 5) : [];
     const _sanNames = _sanitizersForExpr(sourceExpr, callContext);
+    const _unsanNames = _unsanitizersForExpr(sourceExpr, callContext);
     findings.push({
       ...(_sanNames.size ? { _sanitizersOnPath: [..._sanNames] } : {}),
+      ...(_unsanNames.size ? { _unsanitizersOnPath: [..._unsanNames] } : {}),
       kind: 'taint',
       sinkId: e.id,
       vuln: e.vuln?.name || 'Tainted Sink',
@@ -859,6 +939,13 @@ function step(node, stateIn, callContext) {
         const _byVar = (callContext._sanitizersByVar ||= new Map());
         if (_san.size) _byVar.set(target, _san);
         else _byVar.delete(target);
+        // The same bookkeeping for reversals, and for the same reason: a clean
+        // re-assignment must clear it, or a decode recorded once would void
+        // every later sanitization claim on that name.
+        const _unsan = _unsanitizersForExpr(node.source, callContext);
+        const _unByVar = (callContext._unsanitizersByVar ||= new Map());
+        if (_unsan.size) _unByVar.set(target, _unsan);
+        else _unByVar.delete(target);
       }
       // Constant propagation: track variables assigned from literals
       if (target && _activeConstantVars) {
@@ -1710,6 +1797,14 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         // dropped — which is what previously left sanitizer-gate.js inert.
         ...(Array.isArray(f._sanitizersOnPath) && f._sanitizersOnPath.length
           ? { _sanitizersOnPath: f._sanitizersOnPath } : {}),
+        // The reversal half, and it hit the very trap this comment warns about:
+        // the walk collected `he.decode` correctly, the gate was wired to
+        // consume it, and the field was dropped HERE — so the fix looked inert
+        // through three rounds of debugging. An explicit allowlist is the right
+        // design and this is its standing cost: every new field must be added
+        // in two places, and the omission is silent.
+        ...(Array.isArray(f._unsanitizersOnPath) && f._unsanitizersOnPath.length
+          ? { _unsanitizersOnPath: f._unsanitizersOnPath } : {}),
         // _funcQid: the enclosing function's qid, set upstream during the walk
         // but silently dropped by this allowlist before backward.js's
         // annotateBackwardSlices ever saw it — the same class of omission

package/src/dataflow/sanitizer-gate.js

@@ -86,9 +86,60 @@ export function _sanitizerFamilies() {
 // ctx.sanitizersOnPath: { [findingId]: string[] } — callee names observed on the
 // flow that produced the finding. The engine supplies it; when absent the gate
 // is a no-op, which keeps this safe to call unconditionally.
+// Functions that UNDO an encoding, keyed by the family they reverse.
+//
+// The gate labelled a flow `sanitized` whenever a matching sanitizer appeared
+// on the path, with no notion that a later call could reverse it. Measured by
+// bench/mutation: `he.decode(escapeHtml(req.query.name))` reaching an HTML sink
+// was reported as SANITIZED — a missed XSS, because the decode puts back
+// exactly what the escape took out.
+//
+// Family-keyed, not a flat list, because reversal is family-specific:
+// `decodeURIComponent` undoes percent-encoding and does nothing at all to HTML
+// entities, so treating it as a universal un-sanitizer would throw away correct
+// sanitization claims.
+//
+// A match REFUSES the label rather than removing a finding. That is the safe
+// direction: the cost of being wrong here is a finding kept at full confidence
+// (a possible false positive), while the cost of the previous behaviour was a
+// real vulnerability reported as clean.
+const _UNSANITIZERS = {
+  xss: new Set([
+    'unescape', 'unescapeHtml', 'unescapeHtml3', 'unescapeHtml4',
+    'StringEscapeUtils.unescapeHtml3', 'StringEscapeUtils.unescapeHtml4',
+    'he.decode', 'entities.decode', 'html.decode', 'htmlparser2.decodeHTML',
+    'decodeHTML', 'decodeHTMLStrict', 'decodeEntities',
+    'html.unescape', 'html_entity_decode', 'htmlspecialchars_decode',
+    '_.unescape', 'lodash.unescape',
+  ]),
+  url: new Set([
+    'decodeURI', 'decodeURIComponent', 'unquote', 'unquote_plus',
+    'URLDecoder.decode', 'urldecode', 'querystring.unescape',
+  ]),
+  // sql / cmd / path have no encoding to reverse in the same sense: their
+  // sanitizers parameterise or canonicalise rather than encode, and there is no
+  // inverse call. Deliberately absent rather than guessed at.
+};
+
+/** Does any callee observed on this path undo the sanitization claimed for `fam`? */
+export function _reversedOnPath(observed, fam) {
+  const undoers = _UNSANITIZERS[fam];
+  if (!undoers) return null;
+  for (const name of observed) {
+    if (undoers.has(name)) return name;
+    // A member call may be recorded bare. Only accept a leaf that is
+    // unambiguous on its own — `decode` alone is not (jwt.decode, base64
+    // decode), and matching it would void correct claims.
+    const leaf = String(name).split('.').pop();
+    if (leaf !== name && undoers.has(leaf) && leaf !== 'decode') return name;
+  }
+  return null;
+}
+
 export function applySanitizerGate(findings, ctx) {
   const list = Array.isArray(findings) ? findings : [];
   const onPath = (ctx && ctx.sanitizersOnPath) || null;
+  const undoPath = (ctx && ctx.unsanitizersOnPath) || {};
   if (!onPath) return list;
   const index = _sanitizerIndex();
 
@@ -107,6 +158,16 @@ export function applySanitizerGate(findings, ctx) {
       return fams && (fams.has(fam) || fams.has('*'));
     });
     if (!matching.length) continue;
+    // A reversal anywhere on the path voids the claim. Order is not consulted:
+    // `sanitizersOnPath` is a set of observed callees, and a decode that
+    // precedes the escape is not a shape worth modelling separately when the
+    // conservative answer — refuse the label — is also the safe one.
+    const undone = undoPath[f.id] || undoPath[f.stableId] || [];
+    const reversedBy = _reversedOnPath(undone, fam);
+    if (reversedBy) {
+      f.sanitizerReversedBy = reversedBy;
+      continue;
+    }
     // Label only. The proof gate decides what to do with the label.
     f.sanitized = true;
     f.sanitizerProof = { sanitizers: matching, family: fam };