codejury 0.5.1__tar.gz → 0.7.0__tar.gz

{codejury-0.5.1 → codejury-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codejury
-Version: 0.5.1
+Version: 0.7.0
 Summary: General-purpose Application Security AI audit framework -- five-layer architecture, capabilities as first-class data
 Author: AISecLabs
 License-Expression: MIT
@@ -25,6 +25,7 @@ Provides-Extra: litellm
 Requires-Dist: litellm>=1.0; extra == "litellm"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
 Dynamic: license-file
 
 # codejury
@@ -80,15 +81,38 @@ git diff | codejury audit --provider anthropic
 | `codejury audit [diff]` | Audit a unified diff from a file or stdin (`-`). |
 | `codejury scan <dir>` | Audit a whole directory tree, capability by capability. |
 | `codejury run <task>` | Run a named task preset (see [Tasks](#tasks)). |
-| `codejury eval` | Score the golden cases and report precision / recall. |
+| `codejury eval` | Score the golden cases; report precision / recall / F1, overall and per capability. |
 
-Shared flags: `--orchestrator {single,pipeline,debate,reflexion,challenge}`,
-`--provider {anthropic,openai,litellm}`, `--model`, `--format {text,markdown,json}`.
+Shared flags: `--orchestrator {single,pipeline,debate,reflexion,challenge,taint}`,
+`--provider {anthropic,openai,litellm}`, `--model`,
+`--format {text,markdown,json,sarif}`.
+
+`--orchestrator taint` adds a data-flow gate: after the verifier rules, it clears
+an `input_validation` finding only when static provenance analysis proves the
+value reaching the sink is constant, sanitized, or trusted (using cross-file
+caller/callee context). It downgrades only on positive proof, so it removes false
+positives without dropping real findings.
+
+`--format sarif` emits a SARIF 2.1.0 log (validates against the official schema)
+for CI and security dashboards: each problem with a code location becomes a
+result carrying its capability (as the rule id), CWE, and a precise location.
 
 Findings in known-noise categories (availability/DoS, rate limiting, memory safety
 outside C/C++) are dropped by versioned rules in
 `codejury/data/suppressions.yaml`; disable with `--no-suppress`.
 
+`codejury eval` takes `--dataset <dir>` (golden YAML directory), `--split <name>`
+(score only cases tagged with that `split:`, e.g. a held-out set), and
+`--format {text,json}` -- the JSON report is a stable schema (overall plus
+per-capability confusion matrix and precision / recall / F1).
+
+Runs are deterministic: providers query at temperature 0, and `audit` / `scan`
+cache each verdict on a hash of the normalized code, the in-scope capability
+versions, and the orchestration. Re-auditing unchanged code returns the recorded
+verdicts without re-querying the model; editing a capability YAML changes its
+fingerprint and invalidates affected entries. Pass `--no-cache` to always
+re-query.
+
 ```bash
 # Multi-round adversarial debate, rendered as Markdown
 git diff | codejury audit --orchestrator debate --format markdown - > report.md

{codejury-0.5.1 → codejury-0.7.0}/README.md

@@ -51,15 +51,38 @@ git diff | codejury audit --provider anthropic
 | `codejury audit [diff]` | Audit a unified diff from a file or stdin (`-`). |
 | `codejury scan <dir>` | Audit a whole directory tree, capability by capability. |
 | `codejury run <task>` | Run a named task preset (see [Tasks](#tasks)). |
-| `codejury eval` | Score the golden cases and report precision / recall. |
+| `codejury eval` | Score the golden cases; report precision / recall / F1, overall and per capability. |
 
-Shared flags: `--orchestrator {single,pipeline,debate,reflexion,challenge}`,
-`--provider {anthropic,openai,litellm}`, `--model`, `--format {text,markdown,json}`.
+Shared flags: `--orchestrator {single,pipeline,debate,reflexion,challenge,taint}`,
+`--provider {anthropic,openai,litellm}`, `--model`,
+`--format {text,markdown,json,sarif}`.
+
+`--orchestrator taint` adds a data-flow gate: after the verifier rules, it clears
+an `input_validation` finding only when static provenance analysis proves the
+value reaching the sink is constant, sanitized, or trusted (using cross-file
+caller/callee context). It downgrades only on positive proof, so it removes false
+positives without dropping real findings.
+
+`--format sarif` emits a SARIF 2.1.0 log (validates against the official schema)
+for CI and security dashboards: each problem with a code location becomes a
+result carrying its capability (as the rule id), CWE, and a precise location.
 
 Findings in known-noise categories (availability/DoS, rate limiting, memory safety
 outside C/C++) are dropped by versioned rules in
 `codejury/data/suppressions.yaml`; disable with `--no-suppress`.
 
+`codejury eval` takes `--dataset <dir>` (golden YAML directory), `--split <name>`
+(score only cases tagged with that `split:`, e.g. a held-out set), and
+`--format {text,json}` -- the JSON report is a stable schema (overall plus
+per-capability confusion matrix and precision / recall / F1).
+
+Runs are deterministic: providers query at temperature 0, and `audit` / `scan`
+cache each verdict on a hash of the normalized code, the in-scope capability
+versions, and the orchestration. Re-auditing unchanged code returns the recorded
+verdicts without re-querying the model; editing a capability YAML changes its
+fingerprint and invalidates affected entries. Pass `--no-cache` to always
+re-query.
+
 ```bash
 # Multi-round adversarial debate, rendered as Markdown
 git diff | codejury audit --orchestrator debate --format markdown - > report.md

{codejury-0.5.1 → codejury-0.7.0}/codejury/__init__.py

@@ -5,4 +5,9 @@ Domain knowledge lives in YAML capability files as a first-class citizen,
 aligned with OWASP ASVS.
 """
 
-__version__ = "0.0.0"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("codejury")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"

{codejury-0.5.1 → codejury-0.7.0}/codejury/agents/verifier.py

@@ -93,15 +93,27 @@ def _build_prompt(path: str, content: str, cap: Capability, context: str = "") -
     )
 
 
+def _anti_pattern_cwes(cap: Capability) -> dict[str, str]:
+    """Map anti_pattern id -> CWE, so a verdict can inherit the CWE it matched."""
+    return {
+        p.id: p.cwe
+        for sub in cap.sub_capabilities.values()
+        for p in sub.anti_patterns
+        if p.cwe
+    }
+
+
 def _parse_verdicts(text: str, cap: Capability) -> list[Verdict]:
     obj = extract_json_object(text)
     if not obj:
         return []
+    cwe_by_id = _anti_pattern_cwes(cap)
     out: list[Verdict] = []
     for v in obj.get("verdicts", []):
         if not isinstance(v, dict):
             continue
         sub = str(v.get("sub_capability", "")).strip()
+        matched_anti = str_list(v.get("matched_anti"))
         out.append(
             Verdict(
                 capability=f"{cap.id}.{sub}" if sub else cap.id,
@@ -109,7 +121,8 @@ def _parse_verdicts(text: str, cap: Capability) -> list[Verdict]:
                 status=one_of(v.get("status"), _VALID_STATUS, "UNKNOWN"),
                 reasoning=str(v.get("reasoning", "")),
                 matched_correct=str_list(v.get("matched_correct")),
-                matched_anti=str_list(v.get("matched_anti")),
+                matched_anti=matched_anti,
+                cwe=next((cwe_by_id[a] for a in matched_anti if a in cwe_by_id), ""),
                 evidence=to_evidence(v.get("evidence")),
                 confidence=to_float(v.get("confidence"), 0.5),
             )

codejury-0.7.0/codejury/analysis/__init__.py

@@ -0,0 +1,7 @@
+"""Static analysis for provenance (P1).
+
+The code-graph / data-flow engine that gives the verifier provenance -- whether a
+value reaching a sink is attacker-controlled, sanitized, or a trusted constant.
+This is the real fix for the taint precision floor that single-file LLM review
+cannot reach (see ROADMAP P1). Python / AST based to start.
+"""

codejury-0.7.0/codejury/analysis/provenance.py

@@ -0,0 +1,208 @@
+"""Intra-procedural value-origin tracing (P1-01).
+
+Classify where the value of an expression inside a function comes from, so a
+later layer (P1-03) can decide whether it is attacker-controlled. The output is
+an ``Origin``: the parameters, callees, attribute/subscript roots, free names,
+and literals a value derives from.
+
+The analysis is deliberately conservative and flow-insensitive: a name assigned
+more than once contributes the union of all its right-hand sides, so a possible
+source is never dropped (recall over precision). A value built only from literals
+is reported as ``is_constant`` -- the signal that distinguishes, for example,
+SQL concatenated from constants (safe) from SQL concatenated from a parameter.
+
+This module finds where a value comes from; it does not decide what is a source
+or a sanitizer (that is data, P1-02) nor follow a call into another file (P1-03).
+Python / AST only.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Origin:
+    params: frozenset[str] = frozenset()    # parameters the value derives from
+    calls: frozenset[str] = frozenset()     # callee names whose return it derives from
+    attrs: frozenset[str] = frozenset()     # attribute/subscript roots, dotted (e.g. "request.args")
+    globals_: frozenset[str] = frozenset()  # free names: module globals, imports, builtins
+    has_literal: bool = False               # a literal contributes to the value
+    unknown: bool = False                   # an unmodelled expression contributes (be cautious)
+
+    def merge(self, other: Origin) -> Origin:
+        return Origin(
+            params=self.params | other.params,
+            calls=self.calls | other.calls,
+            attrs=self.attrs | other.attrs,
+            globals_=self.globals_ | other.globals_,
+            has_literal=self.has_literal or other.has_literal,
+            unknown=self.unknown or other.unknown,
+        )
+
+    @property
+    def is_constant(self) -> bool:
+        """True when the value is built only from literals -- no param, call, attr,
+        free name, or unmodelled expression contributes."""
+        return not (self.params or self.calls or self.attrs or self.globals_ or self.unknown)
+
+
+_LITERAL = Origin(has_literal=True)
+_UNKNOWN = Origin(unknown=True)
+
+
+def parse_function(source: str, name: str) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+    """Find the first function named ``name`` in ``source`` (any nesting)."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == name:
+            return node
+    return None
+
+
+def find_calls(scope: ast.AST, callee: str) -> list[ast.Call]:
+    """Every call within ``scope`` whose function is named ``callee`` -- matching a
+    bare name (``open``) or the final attribute (``execute`` in ``cur.execute``)."""
+    return [node for node in ast.walk(scope) if isinstance(node, ast.Call) and _call_name(node) == callee]
+
+
+def trace_value(func: ast.FunctionDef | ast.AsyncFunctionDef, expr: ast.AST) -> Origin:
+    """Trace where ``expr`` (an expression inside ``func``) gets its value from."""
+    return _classify(expr, _params(func), _assignments(func), frozenset())
+
+
+def parameters(func: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    """The parameter names of ``func`` (positional, keyword, *args, **kwargs)."""
+    return _params(func)
+
+
+def assignments(func: ast.FunctionDef | ast.AsyncFunctionDef) -> dict[str, list[ast.AST]]:
+    """Map each assigned local name to the right-hand sides it is assigned (union)."""
+    return _assignments(func)
+
+
+def callee(call: ast.Call) -> tuple[str | None, str | None]:
+    """The (dotted, bare) callee of a call: ("json.loads", "loads") or ("open", "open")."""
+    return _dotted(call.func), _call_name(call)
+
+
+def access_path(node: ast.AST) -> str | None:
+    """Dotted access chain with subscripts collapsed: request.args["x"] -> request.args."""
+    return _dotted(node)
+
+
+def access_root(node: ast.AST) -> str | None:
+    """Leftmost name of an attribute/subscript chain: request.args["x"] -> request."""
+    return _root_name(node)
+
+
+def _classify(expr: ast.AST, params: set[str], assigns: dict[str, list[ast.AST]], seen: frozenset[str]) -> Origin:
+    if isinstance(expr, ast.Constant):
+        return _LITERAL
+    if isinstance(expr, ast.JoinedStr):  # f-string: literal parts + interpolated exprs
+        origin = _LITERAL
+        for value in expr.values:
+            if isinstance(value, ast.FormattedValue):
+                origin = origin.merge(_classify(value.value, params, assigns, seen))
+        return origin
+    if isinstance(expr, ast.BinOp):
+        return _classify(expr.left, params, assigns, seen).merge(_classify(expr.right, params, assigns, seen))
+    if isinstance(expr, (ast.BoolOp,)):
+        return _merge_all(expr.values, params, assigns, seen)
+    if isinstance(expr, ast.IfExp):  # value is one branch or the other; the test does not flow in
+        return _classify(expr.body, params, assigns, seen).merge(_classify(expr.orelse, params, assigns, seen))
+    if isinstance(expr, (ast.List, ast.Tuple, ast.Set)):
+        return _merge_all(expr.elts, params, assigns, seen)
+    if isinstance(expr, ast.Call):
+        # the return value's taint depends on the callee's semantics, which P1-03
+        # decides with the sanitizer/propagator catalog; here we just name the callee.
+        name = _call_name(expr)
+        return Origin(calls=frozenset({name})) if name else _UNKNOWN
+    if isinstance(expr, (ast.Attribute, ast.Subscript)):
+        dotted = _dotted(expr)
+        origin = Origin(attrs=frozenset({dotted})) if dotted else _UNKNOWN
+        root = _root_name(expr)
+        if root in params:  # e.g. request.args[...] where `request` is a parameter
+            origin = origin.merge(Origin(params=frozenset({root})))
+        return origin
+    if isinstance(expr, ast.Name):
+        if expr.id in seen:  # assignment cycle -- stop
+            return Origin()
+        if expr.id in params:
+            return Origin(params=frozenset({expr.id}))
+        if expr.id in assigns:
+            return _merge_all(assigns[expr.id], params, assigns, seen | {expr.id})
+        return Origin(globals_=frozenset({expr.id}))  # module global, import, or builtin
+    return _UNKNOWN
+
+
+def _merge_all(exprs: list[ast.AST], params, assigns, seen) -> Origin:
+    origin = Origin()
+    for e in exprs:
+        origin = origin.merge(_classify(e, params, assigns, seen))
+    return origin
+
+
+def _params(func: ast.AST) -> set[str]:
+    a = getattr(func, "args", None)
+    if a is None:  # a module-level scope has no parameters
+        return set()
+    names = {arg.arg for arg in (*a.posonlyargs, *a.args, *a.kwonlyargs)}
+    if a.vararg:
+        names.add(a.vararg.arg)
+    if a.kwarg:
+        names.add(a.kwarg.arg)
+    return names
+
+
+def _assignments(func: ast.FunctionDef | ast.AsyncFunctionDef) -> dict[str, list[ast.AST]]:
+    out: dict[str, list[ast.AST]] = {}
+    for node in ast.walk(func):
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                for name in _target_names(target):
+                    out.setdefault(name, []).append(node.value)
+        elif isinstance(node, ast.AnnAssign) and node.value is not None and isinstance(node.target, ast.Name):
+            out.setdefault(node.target.id, []).append(node.value)
+        elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name):
+            out.setdefault(node.target.id, []).append(node.value)
+    return out
+
+
+def _target_names(target: ast.AST) -> list[str]:
+    if isinstance(target, ast.Name):
+        return [target.id]
+    if isinstance(target, (ast.Tuple, ast.List)):
+        return [name for elt in target.elts for name in _target_names(elt)]
+    return []
+
+
+def _call_name(call: ast.Call) -> str | None:
+    func = call.func
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+def _dotted(node: ast.AST) -> str | None:
+    """Dotted access chain, with subscripts collapsed: request.args["x"] -> request.args."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _dotted(node.value)
+        return f"{base}.{node.attr}" if base else None
+    if isinstance(node, ast.Subscript):
+        return _dotted(node.value)
+    return None
+
+
+def _root_name(node: ast.AST) -> str | None:
+    while isinstance(node, (ast.Attribute, ast.Subscript)):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None

codejury-0.7.0/codejury/analysis/taint.py

@@ -0,0 +1,273 @@
+"""Taint classification (P1-03): turn provenance into a taint verdict.
+
+Walks a value expression like P1-01's tracer, but consults the taint vocabulary
+(P1-02) at every call and access: a known source makes a value EXTERNAL, a known
+sanitizer makes it SANITIZED (taint stops), a propagator carries taint through to
+the result, and a trusted origin or a literal is clean.
+
+The point is to let a later layer (P1-04) downgrade a taint finding only when the
+value is *provably* not attacker-controlled -- ``classification in SAFE`` -- so
+recall is preserved: anything uncertain is UNKNOWN or PARAM, never quietly safe.
+
+Two documented precision leans: a bare module-global name (e.g. ``STATIC_DIR``)
+is treated as TRUSTED (module-level names are conventionally constants), and an
+unknown attribute access (e.g. ``self.x``) is UNKNOWN rather than safe. These are
+revisited against real repositories in P1-05.
+
+This layer is intra-procedural: a value that depends on a parameter returns
+PARAM, for the cross-file caller hop (next) to resolve.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+import yaml
+
+from codejury.analysis.provenance import (
+    access_path,
+    access_root,
+    assignments,
+    callee,
+    find_calls,
+    parameters,
+)
+from codejury.resources import TAINT_FILE
+
+
+class Taint(str, Enum):
+    EXTERNAL = "external"    # derives from an attacker source, not sanitized
+    UNKNOWN = "unknown"      # an unknown call / access -- cannot prove either way
+    PARAM = "param"          # depends on a parameter; resolve at the call site (cross-file)
+    SANITIZED = "sanitized"  # had an external component, but a sanitizer neutralized it
+    TRUSTED = "trusted"      # operator/config/global origin
+    CONSTANT = "constant"    # built only from literals
+
+
+# Provably-not-attacker-controlled: the only classes P1-04 may downgrade on.
+SAFE = frozenset({Taint.CONSTANT, Taint.SANITIZED, Taint.TRUSTED})
+
+# Ranked for combining a composite value: the most dangerous component wins.
+_RANK = {
+    Taint.EXTERNAL: 6,
+    Taint.UNKNOWN: 5,
+    Taint.PARAM: 4,
+    Taint.SANITIZED: 3,
+    Taint.TRUSTED: 2,
+    Taint.CONSTANT: 1,
+}
+
+
+@dataclass(frozen=True)
+class TaintVocab:
+    sources: tuple[str, ...]
+    trusted: tuple[str, ...]
+    sanitizers: tuple[str, ...]
+    safe_sinks: tuple[str, ...]
+    propagators: tuple[str, ...]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TaintVocab:
+        def match(section: str) -> tuple[str, ...]:
+            return tuple(m for e in data.get(section, []) for m in e.get("match", []))
+
+        def calls(section: str) -> tuple[str, ...]:
+            return tuple(c for e in data.get(section, []) for c in e.get("calls", []))
+
+        return cls(
+            sources=match("sources"),
+            trusted=match("trusted"),
+            sanitizers=calls("sanitizers"),
+            safe_sinks=calls("safe_sinks"),
+            propagators=calls("propagators"),
+        )
+
+
+def load_vocab(path: str | Path = TAINT_FILE) -> TaintVocab:
+    with open(path, encoding="utf-8") as f:
+        return TaintVocab.from_dict(yaml.safe_load(f) or {})
+
+
+def is_safe_sink(call: ast.Call, vocab: TaintVocab) -> bool:
+    """True if the call itself is a safe parser (json.loads, ast.literal_eval, ...)."""
+    return _callee_in(call, vocab.safe_sinks)
+
+
+def taint_of(
+    func: ast.AST,
+    expr: ast.AST,
+    vocab: TaintVocab,
+    *,
+    resolve_param=None,
+) -> Taint:
+    """Classify the taint of ``expr`` within ``func`` using the vocabulary.
+
+    ``resolve_param`` is an optional ``(name) -> Taint`` callback; when given, a
+    value that reaches a parameter is resolved through it (the cross-file caller
+    hop, P1-03b) instead of returning PARAM.
+    """
+    return _walk(func, expr, vocab, assignments(func), parameters(func), frozenset(), resolve_param)
+
+
+def _walk(func, expr, vocab, assigns, params, seen, resolve) -> Taint:
+    def w(e):
+        return _walk(func, e, vocab, assigns, params, seen, resolve)
+
+    if isinstance(expr, ast.Constant):
+        return Taint.CONSTANT
+    if isinstance(expr, ast.JoinedStr):
+        return _combine([Taint.CONSTANT] + [w(v.value) for v in expr.values if isinstance(v, ast.FormattedValue)])
+    if isinstance(expr, ast.BinOp):
+        return _combine([w(expr.left), w(expr.right)])
+    if isinstance(expr, ast.BoolOp):
+        return _combine([w(v) for v in expr.values])
+    if isinstance(expr, ast.IfExp):
+        return _combine([w(expr.body), w(expr.orelse)])
+    if isinstance(expr, (ast.List, ast.Tuple, ast.Set)):
+        return _combine([w(e) for e in expr.elts] or [Taint.CONSTANT])
+    if isinstance(expr, ast.Call):
+        if _callee_in(expr, vocab.sanitizers):
+            return Taint.SANITIZED            # a sanitizer cleans its result regardless of input
+        if _callee_in(expr, vocab.sources):
+            return Taint.EXTERNAL             # e.g. input()
+        if _callee_in(expr, vocab.propagators) or _callee_in(expr, vocab.safe_sinks):
+            return _combine([w(a) for a in expr.args] or [Taint.CONSTANT])
+        return Taint.UNKNOWN                  # unknown call -- a cross-file hop may resolve it later
+    if isinstance(expr, (ast.Attribute, ast.Subscript)):
+        path = access_path(expr)
+        if path and _access_in(path, vocab.sources):
+            return Taint.EXTERNAL
+        if path and _access_in(path, vocab.trusted):
+            return Taint.TRUSTED
+        root = access_root(expr)
+        if root in params:                    # attribute of a parameter -- resolve at call site
+            return resolve(root) if resolve else Taint.PARAM
+        return Taint.UNKNOWN                  # unknown object attribute (e.g. self.x): not provably safe
+    if isinstance(expr, ast.Name):
+        if expr.id in seen:
+            return Taint.CONSTANT             # assignment cycle: no new information
+        if expr.id in params:
+            return resolve(expr.id) if resolve else Taint.PARAM
+        if expr.id in assigns:
+            return _combine([_walk(func, r, vocab, assigns, params, seen | {expr.id}, resolve)
+                             for r in assigns[expr.id]])
+        return Taint.TRUSTED                  # free module global / builtin -- conventionally a constant
+    return Taint.UNKNOWN
+
+
+def _combine(taints: list[Taint]) -> Taint:
+    return max(taints, key=lambda t: _RANK[t])
+
+
+def _callee_in(call: ast.Call, names: tuple[str, ...]) -> bool:
+    dotted, bare = callee(call)
+    for name in names:
+        if "." in name:
+            if dotted is not None and (dotted == name or dotted.endswith("." + name)):
+                return True
+        elif bare == name:
+            return True
+    return False
+
+
+def _access_in(path: str, prefixes: tuple[str, ...]) -> bool:
+    # "request.args" matches the source "request.args" and also "request.args.get"
+    return any(path == p or path.startswith(p + ".") for p in prefixes)
+
+
+# --- cross-file one-hop resolution (P1-03b) ---------------------------------
+
+def taint_in_repo(
+    func: ast.FunctionDef | ast.AsyncFunctionDef,
+    expr: ast.AST,
+    vocab: TaintVocab,
+    files: dict[str, str],
+) -> Taint:
+    """Classify ``expr`` in ``func``, resolving a value that reaches a parameter by
+    looking one hop up at how ``func`` is called across ``files``.
+
+    Combines all call sites: if any caller passes an attacker-controlled value the
+    result is EXTERNAL; if every caller passes a sanitized/constant/trusted value it
+    is safe. With no caller found, the parameter stays UNKNOWN (not assumed safe).
+    """
+    return taint_of(func, expr, vocab, resolve_param=_caller_resolver(func, files, vocab))
+
+
+def _caller_resolver(func, files, vocab):
+    def resolve(param_name: str) -> Taint:
+        index = _param_index(func, param_name)
+        results = []
+        for scope, call in _call_sites(func.name, files):
+            arg = _arg_for_param(call, index, param_name)
+            # one hop only: classify the caller's argument without recursing further
+            results.append(taint_of(scope, arg, vocab) if arg is not None else Taint.UNKNOWN)
+        return _combine(results) if results else Taint.UNKNOWN
+    return resolve
+
+
+def _param_index(func, name: str) -> int | None:
+    positional = [*func.args.posonlyargs, *func.args.args]
+    for i, arg in enumerate(positional):
+        if arg.arg == name:
+            return i
+    return None  # keyword-only or *args: matched by keyword at the call site instead
+
+
+def _arg_for_param(call: ast.Call, index: int | None, name: str) -> ast.AST | None:
+    if index is not None and index < len(call.args):
+        return call.args[index]
+    for kw in call.keywords:
+        if kw.arg == name:
+            return kw.value
+    return None
+
+
+def _call_sites(name: str, files: dict[str, str]) -> list[tuple[ast.AST, ast.Call]]:
+    sites = []
+    for source in files.values():
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+        funcs = [n for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+        for call in find_calls(tree, name):
+            sites.append((_enclosing_scope(funcs, call) or tree, call))
+    return sites
+
+
+def _enclosing_scope(funcs: list[ast.AST], call: ast.Call) -> ast.AST | None:
+    containing = [f for f in funcs if any(node is call for node in ast.walk(f))]
+    if not containing:
+        return None  # module-level call site
+    return min(containing, key=lambda f: sum(1 for _ in ast.walk(f)))  # innermost
+
+
+def worst_sink_taint(content: str, files: dict[str, str], vocab: TaintVocab) -> Taint | None:
+    """The most dangerous taint reaching any potential sink call in ``content``.
+
+    A "potential sink" is any call that is not a safe sink, sanitizer, or
+    propagator (those are not where injection happens). Each such call's argument
+    taint is classified with the cross-file resolver, and the worst is returned.
+    ``Taint.CONSTANT`` when there is no sink to worry about; ``None`` when the
+    code does not parse (the caller should then not act).
+
+    Used by the taint gate to downgrade an input_validation finding only when the
+    whole artifact is provably clean -- so a single tainted sink keeps every
+    finding (recall preserved).
+    """
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return None
+    funcs = [n for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+    taints: list[Taint] = []
+    for call in [n for n in ast.walk(tree) if isinstance(n, ast.Call)]:
+        if is_safe_sink(call, vocab) or _callee_in(call, vocab.sanitizers) or _callee_in(call, vocab.propagators):
+            continue  # not a place an injection lands
+        scope = _enclosing_scope(funcs, call) or tree
+        for arg in (*call.args, *(kw.value for kw in call.keywords)):
+            taints.append(taint_in_repo(scope, arg, vocab, files))
+    return _combine(taints) if taints else Taint.CONSTANT