coretrace-python-analyzer 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

coretrace_python/__init__.py

@@ -1,4 +1,4 @@
 """CoreTrace's Python static analysis frontend."""
 
-__version__ = "0.19.0"
+__version__ = "0.21.0"
 

coretrace_python/abstract/__init__.py

@@ -8,6 +8,7 @@ from coretrace_python.abstract.constants import (
 from coretrace_python.abstract.heap import (
     ATTRIBUTES,
     ELEMENTS,
+    KEYS,
     MUTATORS,
     AbstractObject,
     AliasSet,
@@ -24,6 +25,7 @@ from coretrace_python.abstract.values import AbstractValue, Truth
 __all__ = [
     "ATTRIBUTES",
     "ELEMENTS",
+    "KEYS",
     "MUTATORS",
     "AbstractObject",
     "AbstractValue",

coretrace_python/abstract/heap.py

@@ -6,7 +6,8 @@ globals and imported symbols by name, and the fields loaded from an object by fi
 Each value points to an ``AliasSet`` of objects, computed by a flow-insensitive
 points-to fixpoint over the SSA form; each object has two ``HeapLocation`` fields,
 ``elements`` for its items and ``attributes`` for its attributes, field-insensitive
-within each. Taint and dependence analyses key their states by these locations, so a
+within each, and a third, ``keys``, for the keys of a mapping, which only the taint
+engine fills. Taint and dependence analyses key their states by these locations, so a
 store, a mutating method call or a load on any alias reads and writes the same place.
 """
 
@@ -47,6 +48,8 @@ from coretrace_python.source import SourceSpan
 
 ELEMENTS = "elements"
 ATTRIBUTES = "attributes"
+# The keys of a mapping, stored by the taint engine; the points-to solver never fills it.
+KEYS = "keys"
 
 # Method names that store their arguments into the receiver's elements.
 MUTATORS = frozenset(

coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py

@@ -8,12 +8,14 @@ from collections.abc import Iterator, Sequence
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.dependency import Advisory, DependencyAnalysis
+from coretrace_python.dependency import Advisory, AdvisoryEntryPoint, DependencyAnalysis
 from coretrace_python.dependency.correlation import (
     ConditionCheck,
+    affected_entries,
     affected_symbols,
     check_conditions,
     evidence,
+    suffix_index,
 )
 from coretrace_python.findings import Confidence, Finding
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
@@ -30,6 +32,7 @@ class ReachableVulnerabilityPlugin(ProjectPlugin):
         affected = affected_symbols(ctx.dependencies, ctx.advisories)
         if not affected:
             return ()
+        suffixes = suffix_index(affected, ctx.modules)
         findings: list[Finding] = []
         for module in ctx.modules:
             graph = ctx.call_graph(module)
@@ -37,30 +40,28 @@ class ReachableVulnerabilityPlugin(ProjectPlugin):
                 for site in graph.sites(function):
                     if not isinstance(site.target, ExternalSymbol):
                         continue
-                    for advisory in affected.get(site.target.symbol, ()):
-                        entry = advisory.entry_point(site.target.symbol)
+                    for advisory, entry in affected_entries(site.target.symbol, affected, suffixes):
                         if entry is not None and entry.read:
                             continue  # a call reads its callee first: reported with the reads
-                        check = check_conditions(entry, site.arguments)
+                        check = check_conditions(entry, site.arguments, prior_calls=site.prior_calls)
                         if check.contradicted is not None:
                             continue
-                        findings.append(_reached(advisory, site.target.symbol, site.location, function, check))
+                        findings.append(_reached(advisory, site.target.symbol, site.location, function, check, entry))
                 # Reading ``request.form.get`` reads ``request.form``: one finding per entry
                 # point and function, where the function first reads it.
                 reported: set[tuple[Advisory, SymbolId]] = set()
                 for read in graph.reads(function):
                     for symbol in _read_through(read.symbol):
-                        for advisory in affected.get(symbol, ()):
-                            entry = advisory.entry_point(symbol)
+                        for advisory, entry in affected_entries(symbol, affected, suffixes):
                             if entry is None or not entry.read or (advisory, symbol) in reported:
                                 continue
                             reported.add((advisory, symbol))
                             check = check_conditions(entry, None)
-                            findings.append(_reached(advisory, symbol, read.location, function, check))
+                            findings.append(_reached(advisory, symbol, read.location, function, check, entry))
         for call in ctx.templates.calls:
-            for advisory in affected.get(call.symbol, ()):
-                check = check_conditions(advisory.entry_point(call.symbol), None)
-                findings.append(_reached(advisory, call.symbol, call.span, None, check))
+            for advisory, entry in affected_entries(call.symbol, affected, suffixes):
+                check = check_conditions(entry, None)
+                findings.append(_reached(advisory, call.symbol, call.span, None, check, entry))
         return findings
 
 
@@ -73,7 +74,12 @@ def _read_through(symbol: SymbolId) -> Iterator[SymbolId]:
 
 
 def _reached(
-    advisory: Advisory, symbol: SymbolId, span: SourceSpan, function: str | None, check: ConditionCheck
+    advisory: Advisory,
+    symbol: SymbolId,
+    span: SourceSpan,
+    function: str | None,
+    check: ConditionCheck,
+    entry: AdvisoryEntryPoint | None,
 ) -> Finding:
     return Finding(
         rule_id="reachable-vulnerability",
@@ -85,5 +91,5 @@ def _reached(
         confidence=Confidence.HIGH,
         span=span,
         function=function,
-        metadata=evidence(advisory, symbol, "reachable", check),
+        metadata=evidence(advisory, symbol, "reachable", check, entry),
     )

coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -7,7 +7,13 @@ from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.dependency import DependencyAnalysis
-from coretrace_python.dependency.correlation import affected_symbols, check_conditions, ruled_out
+from coretrace_python.dependency.correlation import (
+    affected_entries,
+    affected_symbols,
+    check_conditions,
+    ruled_out,
+    suffix_index,
+)
 from coretrace_python.findings import Confidence, Finding
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
@@ -57,6 +63,7 @@ def _ruled_out(ctx: ProjectContext) -> dict[str, list[str]]:
     conditions: the evidence that the requirement, imported, is not reached there."""
 
     affected = affected_symbols(ctx.dependencies, ctx.advisories)
+    suffixes = suffix_index(affected, ctx.modules)
     excluded: dict[str, list[str]] = {}
     for module in sorted(ctx.modules):
         graph = ctx.call_graph(module)
@@ -64,8 +71,8 @@ def _ruled_out(ctx: ProjectContext) -> dict[str, list[str]]:
             for site in graph.sites(function):
                 if not isinstance(site.target, ExternalSymbol):
                     continue
-                for advisory in affected.get(site.target.symbol, ()):
-                    check = check_conditions(advisory.entry_point(site.target.symbol), site.arguments)
+                for advisory, entry in affected_entries(site.target.symbol, affected, suffixes):
+                    check = check_conditions(entry, site.arguments, prior_calls=site.prior_calls)
                     if check.contradicted is not None:
                         excluded.setdefault(advisory.id, []).append(ruled_out(module, site, check))
     return excluded

coretrace_python/cache.py

@@ -34,6 +34,7 @@ from coretrace_python.interprocedural import (
     ModuleGraph,
     Mutation,
     NonlocalWrite,
+    PriorCall,
     SummaryIndex,
     SymbolRead,
     Target,
@@ -42,7 +43,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
 
-CACHE_FORMAT = 11
+CACHE_FORMAT = 13
 
 
 @dataclass(frozen=True)
@@ -351,23 +352,39 @@ def _encode_site(site: CallSite) -> dict[str, Any]:
         "location": _encode_span(site.location),
         "target": _encode_target(site.target),
         "arguments": _encode_arguments(site.arguments),
+        "prior": None
+        if site.prior_calls is None
+        else [
+            [str(p.symbol), _encode_span(p.location), _encode_arguments(p.arguments), p.dominates]
+            for p in site.prior_calls
+        ],
     }
 
 
 def _decode_site(data: Mapping[str, Any]) -> CallSite:
+    prior = data["prior"]
     return CallSite(
         _string(data["caller"]),
         _decode_span(data["location"]),
         _decode_target(data["target"]),
         _decode_arguments(data["arguments"]),
+        None if prior is None else tuple(_decode_prior(entry) for entry in prior),
     )
 
 
+def _decode_prior(data: Any) -> PriorCall:
+    symbol, span, arguments, dominates = data
+    if not isinstance(dominates, bool):
+        raise TypeError(f"expected a boolean, got {dominates!r}")
+    return PriorCall(SymbolId(_string(symbol)), _decode_span(span), _decode_arguments(arguments), dominates)
+
+
 def _encode_arguments(arguments: Arguments) -> dict[str, Any]:
     return {
         "positional": list(arguments.positional),
         "keywords": [[name, value] for name, value in arguments.keywords],
         "unpacked": arguments.unpacked,
+        "keyword_unpacked": arguments.keyword_unpacked,
     }
 
 
@@ -375,11 +392,12 @@ def _decode_arguments(data: Mapping[str, Any]) -> Arguments:
     def denoted(value: Any) -> str | None:
         return None if value is None else _string(value)
 
-    unpacked = data["unpacked"]
-    if not isinstance(unpacked, bool):
-        raise TypeError(f"expected a boolean, got {unpacked!r}")
+    unpacked, keyword_unpacked = data["unpacked"], data["keyword_unpacked"]
+    if not isinstance(unpacked, bool) or not isinstance(keyword_unpacked, bool):
+        raise TypeError(f"expected booleans, got {unpacked!r} and {keyword_unpacked!r}")
     return Arguments(
         tuple(denoted(value) for value in data["positional"]),
         tuple((_string(name), denoted(value)) for name, value in data["keywords"]),
         unpacked,
+        keyword_unpacked,
     )

coretrace_python/dependency/advisories.py

@@ -6,7 +6,7 @@ events into a version specifier; ``dump_advisories`` writes them as a small JSON
 that a project keeps at its root as ``advisories.json`` or passes with ``--advisories``.
 OSV records name no affected APIs, so imported advisories feed the requirement checks
 and the SBOM; a file completed by hand with ``affected_symbols``, ``entry_points`` and
-their ``conditions`` also feeds the reachability and correlation checks.
+their ``conditions`` and ``suffixes`` also feeds the reachability and correlation checks.
 """
 
 from __future__ import annotations
@@ -161,6 +161,8 @@ def _entry_point_entry(entry_point: AdvisoryEntryPoint) -> dict[str, Any]:
     }
     if entry_point.read:
         entry["read"] = True
+    if entry_point.suffixes:
+        entry["suffixes"] = list(entry_point.suffixes)
     if entry_point.attacker_arguments:
         entry["attacker_arguments"] = [_attacker_argument_entry(a) for a in entry_point.attacker_arguments]
     return entry
@@ -187,6 +189,10 @@ def _condition_entry(condition: Condition) -> dict[str, Any]:
         entry["position"] = condition.position
     if condition.default:
         entry["default"] = True
+    if condition.present:
+        entry["present"] = True
+    if condition.method is not None:
+        entry["method"] = condition.method
     return entry
 
 
@@ -226,9 +232,20 @@ def _entry_point(entry: Mapping[str, Any]) -> AdvisoryEntryPoint:
         tuple(_condition(c) for c in entry.get("conditions") or []),
         read,
         tuple(_attacker_argument(a) for a in entry.get("attacker_arguments") or []),
+        tuple(_suffix(s) for s in entry.get("suffixes") or []),
     )
 
 
+def _suffix(value: Any) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"an entry point suffix must be a string, got {value!r}")
+    parts = value.split(".")
+    # A single name (``annotate``) would match every project method of that name.
+    if len(parts) < 2 or not all(p.isidentifier() for p in parts):
+        raise ValueError(f"an entry point suffix is at least two dot-separated names, got {value!r}")
+    return value
+
+
 def _attacker_argument(entry: Mapping[str, Any]) -> AttackerArgument:
     argument, position, variadic = entry.get("argument"), entry.get("position"), entry.get("variadic", False)
     if argument is not None and not isinstance(argument, str):
@@ -251,6 +268,9 @@ def _condition(entry: Mapping[str, Any]) -> Condition:
     default = entry.get("default", False)
     if not isinstance(default, bool):
         raise TypeError(f"condition default must be true or false, got {default!r}")
+    present = entry.get("present", False)
+    if not isinstance(present, bool):
+        raise TypeError(f"condition present must be true or false, got {present!r}")
     condition = Condition(
         str(entry["kind"]),
         str(entry["text"]),
@@ -258,9 +278,28 @@ def _condition(entry: Mapping[str, Any]) -> Condition:
         tuple(str(v) for v in entry.get("values") or []),
         position,
         default,
+        present,
+        None if entry.get("method") is None else str(entry["method"]),
     )
+    if condition.present and (
+        condition.kind != "argument"
+        or (condition.argument is None and condition.position is None)
+        or condition.values
+        or condition.default
+    ):
+        raise ValueError("a present condition names the argument that must be passed, by keyword or position, and nothing else")
+    if condition.kind == "sequence" and not condition.method:
+        raise ValueError("a sequence condition names the method of the prior call")
+    if condition.kind == "sequence" and condition.values and condition.argument is None:
+        raise ValueError("the values of a sequence condition need the argument they constrain")
+    if condition.kind != "sequence" and condition.method is not None:
+        raise ValueError(f"only a sequence condition names a method, not {condition.kind!r}")
     if condition.kind == "host" and (
         (condition.argument is None and condition.position is None) or condition.values or condition.default
     ):
         raise ValueError("a host condition names the URL argument, by keyword or position, and nothing else")
+    if condition.kind == "keyword_name" and (
+        condition.argument is not None or condition.position is not None or condition.values or condition.default
+    ):
+        raise ValueError("a keyword_name condition carries its text and nothing else")
     return condition

coretrace_python/dependency/correlation.py

@@ -21,9 +21,9 @@ from coretrace_python.dependency.graph import (
 )
 from coretrace_python.findings import Confidence, Finding, Severity
 from coretrace_python.findings.refutation import Status, Verdict, Verdicts
-from coretrace_python.interprocedural import Arguments, CallSite, ExternalSymbol
+from coretrace_python.interprocedural import Arguments, CallSite, ExternalSymbol, PriorCall
 from coretrace_python.semantic.symbols import SymbolId
-from coretrace_python.taint import Sink, TaintFlow, TaintKind
+from coretrace_python.taint import KEYWORD_NAMES, Sink, SuffixSink, TaintFlow, TaintKind
 from coretrace_python.taint.urls import UrlProof, redirects_disabled
 
 Affected = Mapping[SymbolId, tuple[Advisory, ...]]
@@ -49,6 +49,56 @@ def advisory_sinks(affected: Affected) -> tuple[Sink, ...]:
     return tuple(Sink(symbol, TaintKind.ADVISORY) for symbol in affected)
 
 
+@dataclass(frozen=True)
+class SuffixIndex:
+    """The curated entry-point suffixes of the matching advisories, and the project's
+    module prefixes: a derived symbol matches a suffix on a dot boundary, as a
+    ``SuffixSink`` does, and only when it belongs to a project module — another
+    package's ``objects.annotate`` stays out."""
+
+    entries: tuple[tuple[str, Advisory, AdvisoryEntryPoint], ...] = ()
+    prefixes: tuple[str, ...] = ()
+
+    def matches(self, symbol: SymbolId) -> tuple[tuple[Advisory, AdvisoryEntryPoint], ...]:
+        name = symbol.canonical_name
+        found = tuple((a, e) for tail, a, e in self.entries if name.endswith(tail))
+        return found if found and name.startswith(self.prefixes) else ()
+
+
+def suffix_index(affected: Affected, modules: Iterable[str]) -> SuffixIndex:
+    advisories = {a: None for found in affected.values() for a in found}
+    entries = tuple((f".{s}", a, e) for a in advisories for e in a.entry_points for s in e.suffixes)
+    return SuffixIndex(entries, tuple(f"python.{m}." for m in sorted(set(modules))))
+
+
+def affected_entries(
+    symbol: SymbolId, affected: Affected, suffixes: SuffixIndex | None = None
+) -> tuple[tuple[Advisory, AdvisoryEntryPoint | None], ...]:
+    """The advisories reached through ``symbol``, each with the entry point it is reached
+    by: the advisories affecting the exact symbol, then those a suffix matches."""
+
+    found: list[tuple[Advisory, AdvisoryEntryPoint | None]] = [
+        (a, a.entry_point(symbol)) for a in affected.get(symbol, ())
+    ]
+    if suffixes is not None:
+        seen = {(a.id, a.package, None if e is None else e.symbol) for a, e in found}
+        for advisory, entry in suffixes.matches(symbol):
+            key = (advisory.id, advisory.package, entry.symbol)
+            if key not in seen:
+                seen.add(key)
+                found.append((advisory, entry))
+    return tuple(found)
+
+
+def advisory_suffix_sinks(affected: Affected) -> tuple[SuffixSink, ...]:
+    """A suffix sink per curated entry-point suffix, so the taint engine tracks flows
+    into the derived symbols; ``correlate`` then keeps only the project's."""
+
+    advisories = {a: None for found in affected.values() for a in found}
+    suffixes = {s: None for a in advisories for e in a.entry_points for s in e.suffixes}
+    return tuple(SuffixSink(s, TaintKind.ADVISORY) for s in suffixes)
+
+
 @dataclass(frozen=True)
 class ConditionCheck:
     """What one call tells of an entry point's conditions: those it meets, those left to
@@ -67,18 +117,39 @@ def check_conditions(
     arguments: Arguments | None,
     url: UrlProof | None = None,
     passed_as: frozenset[tuple[int | None, str | None]] = frozenset(),
+    prior_calls: tuple[PriorCall, ...] | None = None,
 ) -> ConditionCheck:
     """Decide ``entry``'s conditions against what the call's ``arguments`` denote and, for
     a ``host`` condition, what ``url`` proves of the value the attacker's input is passed
     in (``passed_as``). A host the URL's constant text fixes rules the call out when the
     call disables redirects; otherwise a redirect may still lead to a host the attacker
-    controls, and the condition stays pending with that uncertainty."""
+    controls, and the condition stays pending with that uncertainty. A ``keyword_name``
+    condition is met when the attacker's input is passed as the keys of a ``**`` mapping,
+    pending when the call expands a mapping whose keys are not established, and
+    contradicted by a call writing every keyword name. An ``argument`` condition with
+    ``present`` is met when the call gives the argument, whatever it denotes, and
+    contradicted when the call surely does not give it. A ``sequence`` condition is met
+    when one of the ``prior_calls`` on the call's receiver dominates it — surely executes
+    before it — matches the condition's method and passes what it requires; contradicted
+    when the receiver is followed whole and no matching call could do so, the call's own
+    ``arguments`` included, since across the iterations of a loop the call is its own
+    prior; pending otherwise — an unfollowed receiver (``prior_calls`` is None), an
+    undecided or non-dominating matching call, or an undecidable self-check."""
 
     if entry is None:
         return ConditionCheck()
     met: list[Condition] = []
     pending: list[Condition] = []
     for condition in entry.conditions:
+        if condition.kind == "keyword_name":
+            if any(keyword == KEYWORD_NAMES for _, keyword in passed_as):
+                met.append(condition)
+            elif arguments is None or arguments.keyword_unpacked:
+                pending.append(condition)
+            else:
+                names = ", ".join(sorted({name for name, _ in arguments.keywords}))
+                return ConditionCheck(tuple(met), tuple(pending), condition, names or None)
+            continue
         if condition.kind == "host":
             origin = url.origin if url is not None and _passed_in(condition, passed_as) else None
             if origin is None:
@@ -89,10 +160,40 @@ def check_conditions(
                 text = f"the host is fixed by {origin!r}, but a redirect may lead to a host the attacker controls"
                 pending.append(replace(condition, text=text))
             continue
+        if condition.kind == "sequence":
+            candidates = [
+                p
+                for p in prior_calls or ()
+                if condition.method is not None and _named(p.symbol, condition.method)
+            ]
+            satisfied = [_first_call_satisfies(condition, p.arguments) for p in candidates]
+            hit = next(
+                (p for p, s in zip(candidates, satisfied, strict=True) if s is True and p.dominates), None
+            )
+            if hit is not None:
+                text = f"{condition.text} (prior {condition.method} at line {hit.location.start_line})"
+                met.append(replace(condition, text=text))
+            elif (
+                prior_calls is None
+                or condition.method is None
+                or None in satisfied
+                or True in satisfied
+                or _first_call_satisfies(condition, arguments) is not False
+            ):
+                pending.append(condition)
+            else:
+                return ConditionCheck(tuple(met), tuple(pending), condition, None)
+            continue
         given = arguments.given(condition.argument, condition.position) if condition.checkable and arguments is not None else None
         if given is None:
             pending.append(condition)
             continue
+        if condition.present:
+            if given[0]:
+                met.append(condition)
+            else:
+                return ConditionCheck(tuple(met), tuple(pending), condition, None)
+            continue
         explicit, value = given
         if explicit and value is None:
             pending.append(condition)
@@ -104,6 +205,32 @@ def check_conditions(
     return ConditionCheck(tuple(met), tuple(pending))
 
 
+def _named(symbol: SymbolId, method: str) -> bool:
+    """Whether ``symbol`` is the ``method`` a sequence condition names, by exact
+    canonical name or by ``.``-suffix (``Session.get``)."""
+
+    name = symbol.canonical_name
+    return name == method or name.endswith("." + method)
+
+
+def _first_call_satisfies(condition: Condition, arguments: Arguments | None) -> bool | None:
+    """Whether ``arguments`` carry what a sequence ``condition`` requires of the first
+    call: trivially when it names no argument, else as an argument condition reads
+    ``given()``; None when they cannot tell."""
+
+    if condition.argument is None and condition.position is None:
+        return True
+    if arguments is None:
+        return None
+    given = arguments.given(condition.argument, condition.position)
+    if given is None:
+        return None
+    explicit, value = given
+    if explicit and value is None:
+        return None
+    return value in condition.values if explicit else condition.default
+
+
 def _passed_in(condition: Condition, passed_as: frozenset[tuple[int | None, str | None]]) -> bool:
     """Whether a value passed as ``passed_as`` is the argument ``condition`` names."""
 
@@ -119,18 +246,32 @@ def ruled_out(module: str, site: CallSite, check: ConditionCheck) -> str:
     python.yaml.load(Loader=python.yaml.SafeLoader)``."""
 
     assert check.contradicted is not None and isinstance(site.target, ExternalSymbol)
-    argument = check.contradicted.argument or f"#{check.contradicted.position}"
+    contradicted = check.contradicted
+    if contradicted.kind == "sequence":
+        return (
+            f"{module}:{site.location.start_line} {site.target.symbol}"
+            f"(no prior {contradicted.method} on the receiver)"
+        )
+    argument = contradicted.argument or ("keywords" if contradicted.kind == "keyword_name" else f"#{contradicted.position}")
     passed = f"{argument} absent" if check.passed is None else f"{argument}={check.passed}"
     return f"{module}:{site.location.start_line} {site.target.symbol}({passed})"
 
 
-def evidence(advisory: Advisory, symbol: SymbolId, level: str, check: ConditionCheck) -> dict[str, str]:
+def evidence(
+    advisory: Advisory,
+    symbol: SymbolId,
+    level: str,
+    check: ConditionCheck,
+    entry: AdvisoryEntryPoint | None = None,
+) -> dict[str, str]:
     """What a finding keeps of the advisory for ``symbol``: the level of evidence
     established, how the symbol relates to the vulnerability, and its conditions — those
-    the call meets and those left to review."""
+    the call meets and those left to review. ``entry`` names the entry point ``symbol``
+    was matched by when it is not the advisory's own symbol, as a suffix match derives
+    it from the project; the metadata then keeps both."""
 
     metadata = {"advisory": advisory.id, "package": advisory.package, "symbol": str(symbol), "level": level}
-    entry = advisory.entry_point(symbol)
+    entry = entry if entry is not None else advisory.entry_point(symbol)
     if entry is None:
         metadata["justification"] = DIRECT
         return metadata
@@ -151,9 +292,12 @@ def correlate(
     verdicts: Verdicts | None,
     affected: Affected,
     urls: Mapping[TaintFlow, UrlProof] | None = None,
+    suffixes: SuffixIndex | None = None,
+    prior: Mapping[TaintFlow, tuple[PriorCall, ...] | None] | None = None,
 ) -> tuple[Finding, ...]:
     """Exploitable-vulnerability findings for the non-refuted ADVISORY flows of a function,
-    one per advisory the sink is affected by; ``urls`` holds what each flow's URL proves."""
+    one per advisory the sink is affected by; ``urls`` holds what each flow's URL proves
+    and ``prior`` the other calls on each flow's receiver, for sequence conditions."""
 
     findings: list[Finding] = []
     for flow in flows:
@@ -163,25 +307,32 @@ def correlate(
         if verdict is not None and verdict.status is Status.REFUTED:
             continue
         hotspot = verdict is not None and verdict.status is Status.HOTSPOT
-        for advisory in affected.get(flow.sink.symbol, ()):
-            entry = advisory.entry_point(flow.sink.symbol)
+        for advisory, entry in affected_entries(flow.sink.symbol, affected, suffixes):
             if entry is not None and not any(entry.exploitable_through(p, k) for p, k in flow.passed_as):
                 continue
-            check = check_conditions(entry, flow.sink_arguments, (urls or {}).get(flow), flow.passed_as)
+            check = check_conditions(
+                entry, flow.sink_arguments, (urls or {}).get(flow), flow.passed_as, (prior or {}).get(flow)
+            )
             if check.contradicted is None:
-                findings.append(_exploitable(function, flow, advisory, verdict, hotspot, check))
+                findings.append(_exploitable(function, flow, advisory, verdict, hotspot, check, entry))
     return tuple(findings)
 
 
 def _exploitable(
-    function: str, flow: TaintFlow, advisory: Advisory, verdict: Verdict | None, hotspot: bool, check: ConditionCheck
+    function: str,
+    flow: TaintFlow,
+    advisory: Advisory,
+    verdict: Verdict | None,
+    hotspot: bool,
+    check: ConditionCheck,
+    entry: AdvisoryEntryPoint | None,
 ) -> Finding:
     message = (
         f"{advisory.id}: {flow.source.label} input reaches {flow.sink.symbol}, affected in "
         f"the required {advisory.package} {advisory.vulnerable}: {advisory.summary}"
     )
     metadata = {
-        **evidence(advisory, flow.sink.symbol, "exploitable", check),
+        **evidence(advisory, flow.sink.symbol, "exploitable", check, entry),
         "source": str(flow.source.symbol),
         "source_label": flow.source.label,
         "verdict": "hotspot" if hotspot else "vulnerability",

coretrace_python/dependency/graph.py

@@ -151,10 +151,21 @@ class Condition:
     ``argument`` condition names the argument by keyword, and by ``position`` when it may
     be passed positionally, and lists the ``values`` that satisfy it — symbols
     (``python.yaml.FullLoader``) or constants as Python writes them (``True``);
-    ``default`` says an absent argument means a vulnerable value. A ``host`` condition
+    ``default`` says an absent argument means a vulnerable value; ``present`` says the
+    argument being passed at all, whatever its value, is the condition, so it excludes
+    ``values`` and ``default``. A ``host`` condition
     says the attacker must choose the host of the URL passed as ``argument`` (or at
     ``position``); the engine decides it from what the URL's constant text proves. A
-    ``semantic`` condition cannot be checked and is reported as pending review."""
+    ``keyword_name`` condition says the attacker must choose a keyword name of the call,
+    as an ORM alias expanded from a mapping; the engine decides it from the keys of what
+    the call expands with ``**``. A ``sequence`` condition says the flaw needs a prior
+    call on the same receiver: it names the ``method`` that call must be, by canonical
+    name or ``.``-suffix, and, when ``argument`` is named, what it must pass, as an
+    argument condition does. It is met when such a call dominates the entry call —
+    surely executes before it — matches ``method`` and passes a value in ``values``
+    (``default`` for an absent argument); contradicted when the receiver is fully
+    followed and no such prior call can precede; pending otherwise. A ``semantic``
+    condition cannot be checked and is reported as pending review."""
 
     kind: str
     text: str
@@ -162,6 +173,8 @@ class Condition:
     values: tuple[str, ...] = ()
     position: int | None = None
     default: bool = False
+    present: bool = False
+    method: str | None = None
 
     @property
     def checkable(self) -> bool:
@@ -201,13 +214,19 @@ class AdvisoryEntryPoint:
     An entry point is reached by a call, or — when ``read`` is set, for an attribute whose
     getter runs the affected code, such as a lazily parsed request body — by any read of
     it or of an attribute of it. When it names ``attacker_arguments``, attacker input
-    exploits it only through one of them; otherwise through any argument."""
+    exploits it only through one of them; otherwise through any argument.
+
+    A suffix names the tail of a derived project symbol through which the entry point is
+    reached when the engine cannot type the receiver: ``Item.objects.annotate`` derives
+    ``python.app.models.Item.objects.annotate``, which ``objects.annotate`` matches.
+    Suffixes match on dot boundaries, and only symbols of the project's own modules."""
 
     symbol: SymbolId
     justification: str
     conditions: tuple[Condition, ...] = ()
     read: bool = False
     attacker_arguments: tuple[AttackerArgument, ...] = ()
+    suffixes: tuple[str, ...] = ()
 
     def exploitable_through(self, position: int | None, keyword: str | None) -> bool:
         """Whether attacker input in the argument at ``position`` or ``keyword`` can