coretrace-python-analyzer 0.20.0__tar.gz → 0.21.0__tar.gz

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.21.0 (2026-09-30)
+
+### Advisories
+
+- An `argument` condition may carry `present: true`: the argument being passed at all, whatever its value, is the condition, as a `\r` in `web.Response(reason=…)` needs `reason` given, constant or not. It names the argument by keyword or position as today and excludes `values` and `default`. A call giving the argument — positionally, by keyword, or through a `**` literal with constant keys, folded into the keywords — meets it even when the value is unknown, so attacker input there makes the call exploitable; a call surely not giving it is ruled out (`app:5 python.aiohttp.web.Response(reason absent)`) and a project passing only such calls stays `not_affected`; a call unpacking `*args` or a `**mapping` whose keys are not written leaves it pending review (#195).
+- A curated entry point may declare `suffixes`, for receivers the engine cannot type: `Item.objects.annotate(...)` derives the project's own `python.app.models.Item.objects.annotate`, which the canonical `python.django.db.models.QuerySet.annotate` entry point never matches. A suffix matches any symbol of the project's own modules ending with a dot plus the suffix, on dot boundaries as a `SuffixSink` matches, never another package's symbol; a queryset chain is declared explicitly (`objects.filter.annotate`), and a suffix is at least two dot-separated names. The finding keeps the advisory's symbol as `entry_point` and the derived one as `symbol`; conditions, `attacker_arguments` and the ruled-out evidence of contradicted calls apply through a suffix as through the exact symbol. An exact advisory sink whose symbol a bundled suffix sink also matches (`objects.extra`) now composes its kinds with the suffix sink's instead of shadowing them (#197).
+- An advisory condition of kind `sequence` says the flaw spans two calls on one receiver: the first call leaves state on the object the entry point — the second call — reuses. It names the `method` the first call must be, by canonical name or `.`-suffix, and, optionally, the argument that call must carry (`{"kind": "sequence", "method": "Session.get", "argument": "verify", "values": ["False"], ...}`), so `s = requests.Session(); s.get(url, verify=False); s.get(other)` marks the second `get` reachable with the prior call as evidence (requests CVE-2024-35195). A receiver followed whole — bound once to the result of a call or a `with` and used only to call its methods — with no matching call on every path to the entry call rules it out (`app.fetch:6 python.requests.Session.get(no prior Session.get on the receiver)`), and a project with only such calls stays `not_affected`. A receiver the engine cannot follow (a parameter, a module-level instance, one passed to another function or mutated through an attribute), a matching call only in a branch or textually later, an unpacking that leaves the first call's arguments undecided, or an entry call that itself carries the named argument — its own prior across the iterations of a loop — leaves the condition pending review (#194).
+
+### Plugins
+
+- `CallSite.prior_calls` records, for a receiver the engine follows whole, the other external calls on the same receiver (`PriorCall`: symbol, location, arguments, and whether it surely executes before this one), in source order; `CallGraph.prior_calls_at` reads it by location, and `check_conditions` takes it to decide `sequence` conditions. The cache format changes.
+
 ## 0.20.0 (2026-09-30)
 
 ### Advisories

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.20.0
+Version: 0.21.0
 Summary: Static security analysis infrastructure for Python code
 Project-URL: Homepage, https://github.com/CoreTrace/coretrace-python-analyzer
 Project-URL: Repository, https://github.com/CoreTrace/coretrace-python-analyzer

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/docs/plugins.md

@@ -195,8 +195,12 @@ A model plugin may also carry `advisories`, a tuple of `Advisory` values
 symbols, as the shipped `sample-advisories` plugin does. Requirements matching them are
 reported, calls to the affected symbols become reachable vulnerabilities and tainted
 calls become exploitable ones. An advisory's entry points carry `conditions`, of kind
-`argument`, `host`, `semantic` or `keyword_name`, and `attacker_arguments`, decided as
-the [usage guide](usage.md) describes.
+`argument` (on the value, or with `present` on the argument being passed at all),
+`host`, `semantic`, `keyword_name` or `sequence`, and `attacker_arguments`, decided as
+the [usage guide](usage.md) describes. An entry point may also declare `suffixes`,
+matched against the tail of a derived symbol of the project's own modules on dot
+boundaries, as a `SuffixSink` matches, for receivers the engine cannot type (see the
+usage guide).
 
 ### Reclassifying findings: `ProjectPlugin.refine`
 

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/docs/usage.md

@@ -247,7 +247,7 @@ the directory of the checked file; a path outside it is printed as it is.
 ```json
 {
   "schema_version": 1,
-  "tool": {"name": "coretrace-python-analyzer", "version": "0.20.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.21.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -281,7 +281,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.20.0",
+  "name": "coretrace-python-analyzer", "version": "0.21.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -370,6 +370,29 @@ it is reachable, called or not — `request.form['name']`, `for key in request.f
 `request.form.get('name')` all read it. A function reading it several times is reported
 once, where it first reads it.
 
+An entry point may declare `suffixes`, for receivers the engine cannot type. A project
+reaches `python.django.db.models.QuerySet.annotate` through a manager on its own model,
+`Item.objects.annotate(...)`, whose call derives the project's own symbol
+`python.app.models.Item.objects.annotate` — `Item` is a project class, `objects` an
+attribute the engine does not type — so the canonical entry point never matches. A
+suffix matches any symbol of the project's own modules ending with a dot plus the
+suffix:
+
+```json
+{"symbol": "python.django.db.models.QuerySet.annotate", "justification": "…",
+ "suffixes": ["objects.annotate", "objects.filter.annotate"]}
+```
+
+A queryset chain is declared explicitly: `Item.objects.filter(...).annotate(...)`
+derives `…objects.filter.annotate`, which only the second suffix matches. A suffix is
+at least two dot-separated names, so a bare method name, matching every project method
+of that name, cannot be declared; another package's symbol, such as
+`other_lib.objects.annotate`, never matches. The finding names the advisory's symbol as
+`entry_point` and the derived one as `symbol`, and the entry point's conditions and
+`attacker_arguments` apply through a suffix as through the exact symbol. A project
+attribute chain genuinely ending with a declared suffix matches too — the vulnerable
+version range and the conditions still gate what is reported.
+
 A filter of Django's own libraries that a project template applies is a call to the
 function behind it, placed at the template's line: `{{ bio|striptags }}` calls
 `python.django.template.defaultfilters.striptags`, and so do filters in tag arguments
@@ -471,6 +494,16 @@ a call passing a variable, or unpacking `*args` or `**kwargs`, leaves the condit
 pending review. A `semantic` condition — the document's tags, the platform, the
 template's origin — cannot be decided and is always pending review, never dropped.
 
+An `argument` condition with `"present": true` says the argument being passed at all,
+whatever its value, is the condition, as a `\r` in `web.Response(reason=…)` needs
+`reason` given, constant or not: `{"kind": "argument", "text": "…", "argument":
+"reason", "position": 1, "present": true}`, exclusive with `values` and `default`. A
+call giving the argument — positionally, by keyword, or through a `**` literal with
+constant keys, which is folded into the keywords — meets it even when the value is
+unknown; a call surely not giving it does not reach the vulnerability and is ruled out
+(`(reason absent)`); a call unpacking `*args` or a `**mapping` whose keys the engine
+cannot read leaves it pending review.
+
 A `host` condition says the attacker must choose the host of the URL passed as
 `argument` (or at `position`), as credentials leaking to the host of a crafted URL
 need: `{"kind": "host", "text": "…", "argument": "url", "position": 0}`. It is
@@ -514,6 +547,47 @@ Keys passed through a project wrapper stay pending, and `mapping.update(other)`,
 taint. A literal the function fills after building it (`m = {}; m[alias] = expr`)
 has keys the literal does not write, so the call is not ruled out.
 
+A `sequence` condition says the flaw spans two calls on one receiver: a first call
+leaves state on the object, and the entry point — the second call — reuses it, as
+`Session.get(url, verify=False)` disables certificate verification for the pooled
+connection a later `Session.get(other)` on the same session reuses (requests
+CVE-2024-35195). It names the `method` the first call must be, by canonical name or
+`.`-suffix, and, optionally, the argument that call must carry, read as an argument
+condition reads it:
+
+```json
+{
+  "kind": "sequence",
+  "text": "a prior call on the same session disabled certificate verification",
+  "method": "Session.get",
+  "argument": "verify",
+  "values": ["False"]
+}
+```
+
+The engine follows a receiver bound once in the analysed function to the result of a
+call or a `with` and used only to call its methods. The outcome has three cases:
+
+- A prior call on the same receiver, on every path to the entry call, matches the
+  method and carries a value in `values` (`default` for an absent argument): the
+  condition is met, and the evidence names that call's line.
+- The receiver's whole lifetime is visible and no such prior call can precede — one
+  call alone on the receiver, or the two calls on different receivers: the condition
+  is contradicted, the call is ruled out
+  (`app.fetch:6 python.requests.Session.get(no prior Session.get on the receiver)`)
+  and a project with only such calls stays `not_affected`.
+- Otherwise the condition stays pending review: a receiver the engine cannot follow —
+  a parameter, a module-level instance, one passed to another function or mutated
+  through an attribute such as `s.verify = False` — a prior call whose arguments a
+  `*`/`**` unpacking leaves undecided, or a flow reaching the entry point inside a
+  callee.
+
+Only a prior call on every path to the entry call counts as before it: a matching
+call in a branch that may not run, or a textually later one, leaves the condition
+pending, since a loop may bring it before the entry call. A call that itself carries
+what the condition requires of the first call is never ruled out either: across the
+iterations of a loop it is its own prior.
+
 Every dependency finding records the highest level of evidence established in its
 `level` metadata: `declared` (the requirement allows a vulnerable version), `imported`
 (a module of the package is imported somewhere), `reachable` (an entry point or affected
@@ -577,7 +651,7 @@ project's behalf would go unseen. Without a lock file, a package is never
 `not_affected`. The document's `@id` derives from its statements, so two runs with the
 same result share it; its `author` is `Unknown Author`, as OpenVEX tools write when they
 cannot know it. Its `tooling` names the analyzer and each component with its digest
-(`coretrace-python-analyzer 0.20.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.21.0; curated-advisories 2026.09.25 (sha256:…)`), so the
 `@id` changes with the advisory data a statement was decided with.
 
 ## Large projects

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coretrace-python-analyzer"
-version = "0.20.0"
+version = "0.21.0"
 description = "Static security analysis infrastructure for Python code"
 readme = "README.md"
 requires-python = ">=3.11"

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/src/coretrace_python/__init__.py

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

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/src/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_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/src/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_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/src/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 = 12
+CACHE_FORMAT = 13
 
 
 @dataclass(frozen=True)
@@ -351,18 +352,33 @@ 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),

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.21.0}/src/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,7 +278,22 @@ 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
     ):