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

package/src/ir/parser-py.helper.py

@@ -127,12 +127,7 @@ def _lower_expr(node: ast.AST) -> dict[str, Any]:
         op = type(node.ops[0]).__name__ if node.ops else "Eq"
         return {"kind": "binary", "op": op, "left": left, "right": right}
     if isinstance(node, ast.Call):
-        callee = _flatten_callee(node.func)
-        args = [_lower_expr(a) for a in (node.args or [])]
-        # Keyword args lowered as positional — taint analysis treats them similarly.
-        for kw in (node.keywords or []):
-            args.append(_lower_expr(kw.value))
-        return {"kind": "call", "callee": callee, "args": args}
+        return _lower_call_chain(node)
     if isinstance(node, ast.List) or isinstance(node, ast.Tuple) or isinstance(node, ast.Set):
         return {"kind": "array", "elements": [_lower_expr(e) for e in (node.elts or [])]}
     if isinstance(node, ast.Dict):
@@ -186,6 +181,79 @@ def _lower_expr(node: ast.AST) -> dict[str, Any]:
     return {"kind": "unknown"}
 
 
+def _lower_call_chain(node: ast.Call) -> dict[str, Any]:
+    """Lowers a (possibly chained) call expression, e.g. `open(x).read()` or
+    `a.b(x).c(y).d(z)`, WITHOUT losing an inner call's own arguments.
+
+    _flatten_callee's "mixed shape" fallback (`func()[0].attr` -> just the
+    last segment name) previously ALSO caught this shape — `.read` on a
+    Call value is not an ast.Attribute-of-ast.Name chain, so it fell to
+    that same fallback, which returns ONLY the bare terminal name and
+    discards the entire inner Call node, including its arguments. Opening
+    a path built from a tainted suffix and immediately reading it in one
+    chained expression meant the tainted portion vanished completely — not
+    just misattributed to the wrong arg index, but never represented in
+    the IR at all. Confirmed via a real corpus fixture
+    (CVE-2019-10097-python-path-traversal — see its pre/srv.py fixture for
+    the exact disclosed shape this fixes).
+
+    Walks the chain from the OUTERMOST call inward, collecting each level's
+    (name segment, own args) — mirrors every hand-rolled parser's
+    `_followChain` convention in this codebase: the reconstructed callee is
+    the dot-joined names in SOURCE order (inner-to-outer, since we walked
+    outer-to-inner), and the args are kept in OUTERMOST-FIRST order (a
+    trailing no-arg call like `.read()` contributes nothing, so the
+    innermost call's real argument — the tainted path — survives as
+    `args[0]`, exactly where `argIndex: 0` catalog entries expect it).
+    """
+    segments: list[tuple[Any, list[dict[str, Any]]]] = []
+    kwargs: dict[str, Any] = {}
+    cur: Any = node
+    while isinstance(cur, ast.Call):
+        args = [_lower_expr(a) for a in (cur.args or [])]
+        for kw in (cur.keywords or []):
+            args.append(_lower_expr(kw.value))
+            # Keyword NAMES were previously dropped: `subprocess.run(cmd,
+            # shell=True)` lowered to args=[cmd, True] with no way to tell
+            # which argument was `shell`. That made it impossible for a sink
+            # to distinguish the shell-interpreted form from the safe
+            # argv-array form, so py-subprocess-run fired on both and
+            # labelled both "shell=True". Recorded alongside args rather than
+            # instead of them, so every existing argIndex consumer is
+            # unaffected. (PRD T3.1 prerequisite.)
+            if kw.arg:
+                kwargs.setdefault(kw.arg, _lower_expr(kw.value))
+            else:
+                # `**opts` — the keyword set is NOT enumerable here. Recorded
+                # under a reserved key so a requireKeyword gate can tell
+                # "this keyword is absent" from "we cannot see the keywords",
+                # and stay recall-preserving in the second case.
+                kwargs.setdefault("**", {"kind": "unknown"})
+        func = cur.func
+        if isinstance(func, ast.Attribute):
+            segments.append((func.attr, args))
+            cur = func.value
+        elif isinstance(func, ast.Name):
+            segments.append((func.id, args))
+            cur = None
+        else:
+            # e.g. a subscript-returned callable (`handlers[key](x)`) —
+            # no further name segment to extract; stop walking but keep
+            # this level's own args.
+            segments.append((None, args))
+            cur = None
+    prefix = _flatten_callee(cur) if cur is not None else None
+    names = ([prefix] if prefix else []) + [s[0] for s in reversed(segments) if s[0]]
+    callee = ".".join(names) if names else None
+    all_args: list[dict[str, Any]] = []
+    for _, args in segments:
+        all_args = all_args + args
+    call: dict[str, Any] = {"kind": "call", "callee": callee, "args": all_args}
+    if kwargs:
+        call["kwargs"] = kwargs
+    return call
+
+
 def _flatten_callee(node: ast.AST) -> Any:
     """Return a dot-joined name like 'os.path.join' for a callee, or a
     structured member-access tree for harder shapes. The dataflow engine
@@ -329,13 +397,22 @@ class CfgBuilder:
             # Bare expression — useful when it's a call (decorator pattern,
             # dispatch shape). For everything else, noop.
             if isinstance(stmt.value, ast.Call):
-                cur = self._add({
+                _node = {
                     "kind": "call",
                     "callee": _flatten_callee(stmt.value.func),
                     "args": [_lower_expr(a) for a in (stmt.value.args or [])]
                           + [_lower_expr(kw.value) for kw in (stmt.value.keywords or [])],
                     "line": line,
-                })
+                }
+                # Keyword names, so a sink can tell `subprocess.run(cmd,
+                # shell=True)` from the safe argv-array form. See
+                # _lower_call_chain for the full rationale.
+                _kw = {kw.arg: _lower_expr(kw.value) for kw in (stmt.value.keywords or []) if kw.arg}
+                if any(kw.arg is None for kw in (stmt.value.keywords or [])):
+                    _kw["**"] = {"kind": "unknown"}   # see _lower_call_chain
+                if _kw:
+                    _node["kwargs"] = _kw
+                cur = self._add(_node)
             elif isinstance(stmt.value, ast.NamedExpr):
                 cur = self._add({
                     "kind": "assign",
@@ -347,6 +424,31 @@ class CfgBuilder:
                 cur = self._add({"kind": "noop", "line": line})
             self._link(prev, cur)
             return cur
+        if isinstance(stmt, ast.Assign) and len(stmt.targets) == 1 and isinstance(stmt.targets[0], ast.Subscript):
+            # Taint-recall PRD (80%): `response["X-Trace"] = tainted` / a
+            # subscript-assignment target. `_assign_target` has no branch for
+            # ast.Subscript, so this previously fell through to `target: None`
+            # — an untracked, effectively no-op assign; the write itself was
+            # invisible to every sink check (matchMemberWriteSink needs a
+            # dotted `target` string; the RHS-is-a-call check doesn't apply
+            # since the RHS here is rarely a call). Lowered instead as a
+            # synthetic `<receiver>.__setitem__(key, value)` call so it flows
+            # through the SAME argument-based sink-matching machinery every
+            # other call already uses — no new engine mechanism, argIndex 1
+            # for the value. `d[k] = v` for an ordinary dict still produces
+            # this same shape; it's harmless (no catalog entry matches
+            # '__setitem__' without a receiver constraint, so it resolves as
+            # an ordinary unrecognized call, same effective no-op as before).
+            receiver = _flatten_callee(stmt.targets[0].value)
+            key_expr = _lower_expr(stmt.targets[0].slice)
+            cur = self._add({
+                "kind": "call",
+                "callee": f"{receiver}.__setitem__" if receiver else "__setitem__",
+                "args": [key_expr, _lower_expr(stmt.value)],
+                "line": line,
+            })
+            self._link(prev, cur)
+            return cur
         if isinstance(stmt, (ast.Assign, ast.AugAssign, ast.AnnAssign)):
             # AugAssign: x += y  → assign x = x + y
             # AnnAssign: x: int = y → assign x = y (or noop if no value)
@@ -568,7 +670,7 @@ def _extract_functions(tree: ast.Module, file: str) -> list[dict[str, Any]]:
         line = node.lineno or 0
         builder = CfgBuilder(node.name)
         builder.lower(node.body)
-        fns.append({
+        fn_rec = {
             "qid": _qid(file, node.name, line),
             "name": node.name,
             "line": line,
@@ -579,10 +681,97 @@ def _extract_functions(tree: ast.Module, file: str) -> list[dict[str, Any]]:
                 "exit": builder.exit,
                 "nodes": builder.nodes,
             },
-        })
+        }
+        pa = _param_annotations(node, params)
+        if pa:
+            fn_rec["paramAnnotations"] = pa
+        fns.append(fn_rec)
     return fns
 
 
+def _decorator_names(node: Any) -> list[str]:
+    """Every decorator on a function, as both its dotted form and its last
+    segment.
+
+    Both are emitted because the receiver of a decorator is a local naming
+    choice — `@mcp.tool()`, `@server.tool()` and `@app.tool()` are the same
+    framework concept — while the last segment alone (`tool`) is too generic
+    to key a taint source on by itself. Emitting both lets the catalog choose
+    how specific it wants to be, and costs nothing when it matches neither.
+    """
+    out: list[str] = []
+    for d in getattr(node, "decorator_list", []) or []:
+        expr = d.func if isinstance(d, ast.Call) else d
+        parts: list[str] = []
+        while isinstance(expr, ast.Attribute):
+            parts.append(expr.attr)
+            expr = expr.value
+        if isinstance(expr, ast.Name):
+            parts.append(expr.id)
+        if not parts:
+            continue
+        parts.reverse()
+        dotted = ".".join(parts)
+        out.append(dotted)
+        if len(parts) > 1:
+            out.append(parts[-1])
+    return out
+
+
+def _param_annotations(node: Any, params: list[str]) -> list[dict[str, Any]]:
+    """Entry-point markers on a function's parameters, in the IR's shared
+    `{index, name, decorator}` side-channel shape (see ir/CLAUDE.md).
+
+    Python expresses "this parameter is attacker-controlled" two ways, and both
+    are captured here:
+
+      1. A FUNCTION-level decorator that makes the whole function an entry
+         point — `@mcp.tool()`, `@app.route(...)`, `@celery.task`. Every
+         parameter inherits it.
+      2. A PER-PARAMETER default marker — FastAPI's
+         `q: str = Query(...)` / `Body(...)` / `Form(...)` / `Header(...)`.
+
+    Nothing is decided here about which of these is untrusted. The IR emits the
+    fact that the decorator exists; dataflow/catalog.js decides whether it
+    names a source, exactly as it already does for Java/C#/NestJS. That
+    separation is why emitting broadly is safe: an unrecognised decorator
+    (`@staticmethod`, `@lru_cache`) resolves to no catalog entry and therefore
+    to no taint.
+    """
+    out: list[dict[str, Any]] = []
+
+    for dec in _decorator_names(node):
+        for idx, pname in enumerate(params):
+            if pname in ("self", "cls"):
+                continue
+            out.append({"index": idx, "name": pname, "decorator": dec})
+
+    # Per-parameter markers: the default value is a call, e.g. `= Query(...)`.
+    args = node.args
+    positional = list(getattr(args, "posonlyargs", [])) + list(args.args)
+    defaults = list(args.defaults)
+    # `defaults` right-aligns with the positional parameters.
+    offset = len(positional) - len(defaults)
+    pairs = [(positional[offset + i], d) for i, d in enumerate(defaults) if 0 <= offset + i < len(positional)]
+    pairs += [(a, d) for a, d in zip(args.kwonlyargs, args.kw_defaults) if d is not None]
+    for arg, default in pairs:
+        expr = default.func if isinstance(default, ast.Call) else default
+        marker = None
+        if isinstance(expr, ast.Name):
+            marker = expr.id
+        elif isinstance(expr, ast.Attribute):
+            marker = expr.attr
+        if not marker:
+            continue
+        try:
+            idx = params.index(arg.arg)
+        except ValueError:
+            continue
+        out.append({"index": idx, "name": arg.arg, "decorator": marker})
+
+    return out
+
+
 # ─── Driver ──────────────────────────────────────────────────────────────────