coretrace-python-analyzer 0.7.0__tar.gz → 0.9.0__tar.gz

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.9.0 (2026-09-25)
+
+### Precision
+
+- An advisory entry point may name the `attacker_arguments` through which attacker input exploits it: by keyword, and by position when the argument may be passed positionally, a variadic one taking every later position. Attacker input in another argument leaves the call reachable instead of exploitable, so an advisory for `send_from_directory` that names its `path` no longer counts `download_name=`, and one for `requests.get` that names its `url` no longer counts the body. An argument unpacked with `*` or `**` may fill any of them: like an argument condition it leaves undecided, it does not rule the call out, so a wrapper forwarding `*args, **kwargs` still reaches the entry point. An entry point naming no argument counts every argument, as before. Each taint flow now records how its value is passed to the sink (#145).
+
+## 0.8.0 (2026-09-25)
+
+### Precision
+
+- A `Validator` proves its argument safe only for the kinds it declares. A validator declared for `REDIRECT` used to refute a command injection through the same value; the flow is now a hotspot, and it is refuted only when the validator covers every kind reaching the sink (#143).
+- A sanitizer called inside a project function protects the flows through that function, for every caller. That covers a helper that escapes before answering, a view redirecting to `reverse(...)`, and a helper rendering a template the analyzer shows escaping. Function summaries keep, for each parameter, the taint kinds cleared on every path from it to an external call or to the return value. A path that skips the sanitizer, or a kind it does not clear, still reaches the sink. The cache format is bumped (#134).
+
+### Plugins
+
+- `Plugin.project_models(root)` lets a plugin read models from the project under analysis, such as validators the project declares in a file. It is called once per directory check, in every process, and its models are part of the cache key. A model declared wrongly raises `ModelError`, which the command line now reports as an error (exit status 2) instead of a traceback (#140).
+- A `Validator` model may name a function of the project by its project symbol (`python.hc.accounts.views._allow_redirect`), and the refutation recognises it in its own module too, where a call to it has no imported symbol. A project can thus declare its own validation helpers, and a flow they guard is refuted (#134).
+
 ## 0.7.0 (2026-09-25)
 
 ### Precision

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.7.0
+Version: 0.9.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.7.0 → coretrace_python_analyzer-0.9.0}/docs/plugins.md

@@ -142,7 +142,7 @@ class BottleModels(ModelPlugin):
 |---|---|
 | `Source(symbol, label, kinds=ALL)` | A call or attribute whose value is attacker-controlled; `label` names it in messages (`http`, `stdin`, `argv`, `http-response`). `kinds` restricts what it can inject. |
 | `Sink(symbol, kinds, positions=(), keywords=())` | A call dangerous for `kinds`. `positions` limits a kind to the given argument indexes, and `keywords` to the given keyword names; a restricted kind reaches only the arguments listed there. SQL sinks read the statement only, and the SSRF sinks of HTTP clients read the URL, by position or as `url=`. A starred argument or `**kwargs` reaches no restricted kind. |
-| `Sanitizer(symbol, kinds)` | A call whose result is safe for `kinds`. |
+| `Sanitizer(symbol, kinds)` | A call whose result is safe for `kinds`, including when the call is inside a project function the data goes through. |
 | `EntryPoint(symbol, label, kinds=ALL)` | A decorator or a class base whose functions receive their parameters as `label` input, such as `flask.Flask.route`. |
 | `TypedParameter(symbol, label, kinds=ALL)` | A class whose annotated parameters carry `label` input, such as Django's `HttpRequest`. |
 | `NamedParameter(pattern, label, kinds)` | A regular expression on parameter names; matching parameters carry `kinds`, as `password` carries `CREDENTIAL`. |
@@ -150,7 +150,7 @@ class BottleModels(ModelPlugin):
 | `SuffixSink(suffix, kinds, positions=())` | A sink matched by the end of the symbol, for methods of any class such as `objects.raw`. |
 | `SafeArgument(symbol, argument, values, position=None, kinds=ALL)` | A call to the sink `symbol` whose `argument` (by keyword, or at `position`) denotes one of `values` is not a sink for `kinds`, such as `yaml.load` with `Loader=yaml.SafeLoader`. Values are written as the analyzer records arguments: a symbol by its canonical name, a constant as Python writes it (`True`). Only a value given explicitly makes the call safe. |
 | `TemplateRender(symbol, position=0, keyword="template_name")` | A call rendering, with autoescaping, the template named by its argument at `position` or `keyword`, such as `render_to_string`. What it returns carries no `HTML` when the name is written in the call and the project's template escapes everything it prints (see the usage guide). |
-| `Validator(symbol, kinds=ALL, argument=0)` | A callable whose truth proves its argument safe, such as `re.fullmatch`; a flow guarded by it is refuted. |
+| `Validator(symbol, kinds=ALL, argument=0)` | A callable whose truth proves its argument safe for `kinds`, such as `re.fullmatch`. A flow guarded by it is refuted when it carries no other kind into the sink, and is a hotspot otherwise: a redirect validator does not make a shell command safe. `symbol` may be a function of the project, by its project symbol (`python.hc.accounts.views._allow_redirect`), which then counts wherever it is called, in its own module too. |
 | `AuthorizationGuard(symbol, label)` | A decorator or a condition restricting who reaches the code, such as `login_required`; a flow behind it is a hotspot. |
 
 Two plugins may describe the same symbol. An identical model is registered once; two
@@ -158,6 +158,23 @@ Two plugins may describe the same symbol. An identical model is registered once;
 another plugin declared for `COMMAND`; any other difference is a conflict that stops
 the analysis with a `ModelError` naming both plugins.
 
+A plugin may also read models from the project it analyses: `project_models(self, root)`
+returns them, from a file at `root` for instance. It is called once per directory check,
+in every process analysing it, before any module. Its models join the plugin's own and
+are part of what cached results depend on. A single-file check reads no project. A
+model declared wrongly raises `ModelError`, which stops the check with its message
+(exit status 2). This is how a project declares validators of its own:
+
+```python
+class DeclaredValidators(ModelPlugin):
+    name: ClassVar[str] = "declared-validators"
+
+    def project_models(self, root: Path) -> Sequence[Model]:
+        path = root / "validators.txt"
+        lines = path.read_text(encoding="utf-8").splitlines() if path.is_file() else []
+        return tuple(Validator(SymbolId(line)) for line in lines if line)
+```
+
 A model plugin may also carry `advisories`, a tuple of `Advisory` values
 (`coretrace_python.dependency`) with the package, the vulnerable range and the affected
 symbols, as the shipped `sample-advisories` plugin does. Requirements matching them are

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/docs/usage.md

@@ -101,7 +101,11 @@ confidence (`high`, `medium`, `low`).
 ### Taint flows
 
 Reported when attacker-controlled data reaches a sensitive call without passing through
-a sanitizer for that kind of sink.
+a sanitizer for that kind of sink. The sanitizer may also sit inside a project function
+the data goes through, like a helper that escapes before it answers, or a view that
+redirects to `reverse(...)`. It then protects every caller, on every path through the
+function where it is called. What a function stores into an object or a `nonlocal`
+variable is not treated that way yet.
 
 | Rule | Reached sink |
 |---|---|
@@ -235,7 +239,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.7.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.9.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -332,6 +336,19 @@ 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.
 
+Most vulnerabilities need attacker input in one argument: the path `send_from_directory`
+serves, not its `download_name`; the URL `requests.get` fetches, not its body. An entry
+point may name them in `attacker_arguments`, by keyword `argument` and, when it may be
+passed positionally, by `position`, counted as for argument conditions; `"variadic": true`
+extends a position to every later one, as `safe_join(directory, *pathnames)` takes
+(`{"position": 1, "variadic": true}`). A call is then exploitable only when attacker
+input reaches one of them, `"attacker_arguments": [{"argument": "url", "position": 0}]`
+for `requests.get`; attacker input in another argument leaves it reachable. An argument
+unpacked with `*args` or `**kwargs` may fill any of them: like an argument condition it
+leaves undecided, it does not rule the call out, so it counts, and a wrapper forwarding
+`*args, **kwargs` to the entry point still reaches it. An entry point without
+`attacker_arguments` is exploitable through any argument.
+
 An `argument` condition is decided at each call. It names the argument by keyword and,
 when it may be passed positionally, by `position` (counted from 0, the receiver of a
 method excluded); `values` are what makes the call affected, written as the analyzer

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/pyproject.toml

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

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/__init__.py

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

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/cache.py

@@ -25,6 +25,7 @@ from coretrace_python.findings import Confidence, Finding, Severity
 from coretrace_python.interprocedural import (
     Arguments,
     CallSite,
+    Cleared,
     ExternalCall,
     ExternalSymbol,
     FunctionSummary,
@@ -41,7 +42,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
 
-CACHE_FORMAT = 9
+CACHE_FORMAT = 10
 
 
 @dataclass(frozen=True)
@@ -237,6 +238,8 @@ def _encode_call(call: ExternalCall) -> dict[str, Any]:
         "location": _encode_span(call.location),
         "call_site": None if call.call_site is None else _encode_span(call.call_site),
         "given": _encode_arguments(call.arguments),
+        "argument_cleared": [_encode_cleared(c) for c in call.argument_cleared],
+        "keyword_cleared": [_encode_cleared(c) for c in call.keyword_cleared],
     }
 
 
@@ -249,9 +252,19 @@ def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
         _decode_span(data["location"]),
         None if site is None else _decode_span(site),
         _decode_arguments(data["given"]),
+        tuple(_decode_cleared(c) for c in data["argument_cleared"]),
+        tuple(_decode_cleared(c) for c in data["keyword_cleared"]),
     )
 
 
+def _encode_cleared(cleared: Cleared) -> list[list[int]]:
+    return [[parameter, bits] for parameter, bits in cleared]
+
+
+def _decode_cleared(data: Any) -> Cleared:
+    return tuple((_integer(parameter), _integer(bits)) for parameter, bits in data)
+
+
 def _encode_summary(summary: FunctionSummary) -> dict[str, Any]:
     return {
         "name": summary.name,
@@ -275,6 +288,7 @@ def _encode_summary(summary: FunctionSummary) -> dict[str, Any]:
             for w in summary.nonlocal_writes
         ],
         "static": summary.static,
+        "return_cleared": _encode_cleared(summary.return_cleared),
     }
 
 
@@ -303,6 +317,7 @@ def _decode_summary(data: Mapping[str, Any]) -> FunctionSummary:
             for w in data["nonlocal_writes"]
         ),
         bool(data["static"]),
+        _decode_cleared(data["return_cleared"]),
     )
 
 

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/cli.py

@@ -27,6 +27,7 @@ from coretrace_python.reporters import FORMATS, render
 from coretrace_python.semantic.imports import ImportResolutionError
 from coretrace_python.semantic.scopes import ScopeError
 from coretrace_python.source import SourceManager
+from coretrace_python.taint import ModelError
 
 EXIT_CLEAN = 0
 EXIT_FINDINGS = 1
@@ -45,6 +46,7 @@ _ANALYSIS_ERRORS = (
     AnalysisError,
     ManifestError,
     IncompatiblePluginError,
+    ModelError,
 )
 
 

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/dependency/__init__.py

@@ -12,6 +12,7 @@ from coretrace_python.dependency.graph import (
     DEPENDENCY_FILES,
     Advisory,
     AdvisoryEntryPoint,
+    AttackerArgument,
     Condition,
     DependencyAnalysis,
     DependencyGraph,
@@ -31,6 +32,7 @@ __all__ = [
     "Advisory",
     "AdvisoryEntryPoint",
     "AdvisoryFileError",
+    "AttackerArgument",
     "Condition",
     "DependencyAnalysis",
     "DependencyGraph",

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/dependency/advisories.py

@@ -17,7 +17,13 @@ from collections.abc import Iterable, Iterator, Mapping
 from pathlib import Path
 from typing import Any
 
-from coretrace_python.dependency.graph import Advisory, AdvisoryEntryPoint, Condition, normalize
+from coretrace_python.dependency.graph import (
+    Advisory,
+    AdvisoryEntryPoint,
+    AttackerArgument,
+    Condition,
+    normalize,
+)
 from coretrace_python.findings import Severity
 from coretrace_python.semantic.symbols import SymbolId
 
@@ -155,6 +161,19 @@ def _entry_point_entry(entry_point: AdvisoryEntryPoint) -> dict[str, Any]:
     }
     if entry_point.read:
         entry["read"] = True
+    if entry_point.attacker_arguments:
+        entry["attacker_arguments"] = [_attacker_argument_entry(a) for a in entry_point.attacker_arguments]
+    return entry
+
+
+def _attacker_argument_entry(argument: AttackerArgument) -> dict[str, Any]:
+    entry: dict[str, Any] = {}
+    if argument.argument is not None:
+        entry["argument"] = argument.argument
+    if argument.position is not None:
+        entry["position"] = argument.position
+    if argument.variadic:
+        entry["variadic"] = True
     return entry
 
 
@@ -206,9 +225,25 @@ def _entry_point(entry: Mapping[str, Any]) -> AdvisoryEntryPoint:
         str(entry["justification"]),
         tuple(_condition(c) for c in entry.get("conditions") or []),
         read,
+        tuple(_attacker_argument(a) for a in entry.get("attacker_arguments") or []),
     )
 
 
+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):
+        raise TypeError(f"attacker argument name must be a string, got {argument!r}")
+    if position is not None and (not isinstance(position, int) or isinstance(position, bool) or position < 0):
+        raise TypeError(f"attacker argument position must be a non-negative integer, got {position!r}")
+    if not isinstance(variadic, bool):
+        raise TypeError(f"attacker argument variadic must be true or false, got {variadic!r}")
+    if argument is None and position is None:
+        raise ValueError("an attacker argument needs a name, a position or both")
+    if variadic and position is None:
+        raise ValueError("a variadic attacker argument needs the position it starts at")
+    return AttackerArgument(argument, position, variadic)
+
+
 def _condition(entry: Mapping[str, Any]) -> Condition:
     position = entry.get("position")
     if position is not None and (not isinstance(position, int) or isinstance(position, bool) or position < 0):

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/dependency/correlation.py

@@ -133,7 +133,10 @@ def correlate(
             continue
         hotspot = verdict is not None and verdict.status is Status.HOTSPOT
         for advisory in affected.get(flow.sink.symbol, ()):
-            check = check_conditions(advisory.entry_point(flow.sink.symbol), flow.sink_arguments)
+            entry = advisory.entry_point(flow.sink.symbol)
+            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)
             if check.contradicted is None:
                 findings.append(_exploitable(function, flow, advisory, verdict, hotspot, check))
     return tuple(findings)

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/dependency/graph.py

@@ -166,6 +166,31 @@ class Condition:
         return self.kind == "argument"
 
 
+@dataclass(frozen=True)
+class AttackerArgument:
+    """An argument of an entry point that must carry the attacker's input: passed by
+    keyword ``argument``, or at ``position`` (from 0, a method's receiver excluded) when it
+    may be passed positionally; a ``variadic`` one, such as ``*pathnames``, also takes every
+    later position."""
+
+    argument: str | None = None
+    position: int | None = None
+    variadic: bool = False
+
+    def receives(self, position: int | None, keyword: str | None) -> bool:
+        """Whether the argument passed at ``position`` or as ``keyword`` is this one. An
+        argument unpacked with ``*`` or ``**`` has neither and may fill this one: like an
+        argument condition it leaves undecided, it does not rule the call out, so it is."""
+
+        if keyword is not None:
+            return keyword == self.argument
+        if position is None:
+            return True
+        if self.position is None:
+            return False
+        return position == self.position or (self.variadic and position > self.position)
+
+
 @dataclass(frozen=True)
 class AdvisoryEntryPoint:
     """A public API through which a project reaches an affected symbol, justified by the
@@ -173,12 +198,20 @@ 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."""
+    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."""
 
     symbol: SymbolId
     justification: str
     conditions: tuple[Condition, ...] = ()
     read: bool = False
+    attacker_arguments: tuple[AttackerArgument, ...] = ()
+
+    def exploitable_through(self, position: int | None, keyword: str | None) -> bool:
+        """Whether attacker input in the argument at ``position`` or ``keyword`` can
+        exploit the vulnerability."""
+
+        return not self.attacker_arguments or any(a.receives(position, keyword) for a in self.attacker_arguments)
 
 
 DIRECT = "affected symbol, changed by the fix"

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/engine.py

@@ -70,6 +70,7 @@ from coretrace_python.interprocedural import (
     CallGraph,
     CallGraphAnalysis,
     CallSite,
+    ClearingAnalysis,
     FunctionSummary,
     ModuleFunction,
     ModuleGraph,
@@ -149,6 +150,7 @@ ALL_ANALYSES: tuple[AnyAnalysis, ...] = (
     DependencyAnalysis,
     RegisteredRoutes,
     EscapedTemplates,
+    ClearingAnalysis,
 )
 
 
@@ -188,6 +190,7 @@ class ResultsEvicted(TransformationPass):
             DependencyAnalysis,
             RegisteredRoutes,
             EscapedTemplates,
+            ClearingAnalysis,
         }
     )
 
@@ -246,7 +249,9 @@ def build_manager(
     """A manager with every engine analysis registered and the engine inputs provided."""
 
     manager = _register_all(module)
-    manager.provide(SecurityModelAnalysis, (models or SecurityModelRegistry()).freeze())
+    table = (models or SecurityModelRegistry()).freeze()
+    manager.provide(SecurityModelAnalysis, table)
+    manager.provide(ClearingAnalysis, table.clearing())
     manager.provide(ProjectSummaries, SummaryIndex())
     manager.provide(RegisteredRoutes, _routes_of(manager))
     return manager
@@ -276,10 +281,14 @@ def load_plugins(plugin_roots: Sequence[Path], manager: AnalysisManager) -> Plug
     return registry
 
 
-def plugin_models(plugins: Iterable[Plugin]) -> ModelTable:
+def plugin_models(plugins: Iterable[Plugin], root: Path | None = None) -> ModelTable:
+    """The models of ``plugins``, with those they read from the project at ``root``."""
+
     models = SecurityModelRegistry()
     for plugin in plugins:
         models.register(*plugin.models, origin=plugin.name)
+        if root is not None:
+            models.register(*plugin.project_models(root), origin=plugin.name)
     return models.freeze()
 
 
@@ -294,7 +303,9 @@ def analyze_file(source: SourceFile, plugin_roots: Sequence[Path]) -> FileAnalys
 
     manager = _register_all(build_hir(source))
     registry = load_plugins(plugin_roots, manager)
-    manager.provide(SecurityModelAnalysis, plugin_models(loaded.plugin for loaded in registry))
+    table = plugin_models(loaded.plugin for loaded in registry)
+    manager.provide(SecurityModelAnalysis, table)
+    manager.provide(ClearingAnalysis, table.clearing())
     manager.provide(ProjectSummaries, SummaryIndex())
     manager.provide(RegisteredRoutes, _routes_of(manager))
     findings, supported = _check_module(manager, tuple(loaded.plugin for loaded in registry))
@@ -385,7 +396,7 @@ def analyze_project(
         (a for plugin in all_plugins for a in plugin.advisories), file_advisories
     )
     affected = affected_symbols(dependencies, advisories)
-    models = plugin_models(all_plugins).extended(*advisory_sinks(affected))
+    models = plugin_models(all_plugins, root).extended(*advisory_sinks(affected))
     for manager in managers.values():
         manager.provide(SecurityModelAnalysis, models)
         manager.provide(DependencyAnalysis, dependencies)
@@ -408,9 +419,11 @@ def analyze_project(
         for symbol, registered in _routes_of(analysable[name]).items():
             routes.setdefault(symbol, registered)
     escaped = escaped_templates(root)
+    clearing = models.clearing(escaped)
     for manager in analysable.values():
         manager.provide(RegisteredRoutes, routes)
         manager.provide(EscapedTemplates, escaped)
+        manager.provide(ClearingAnalysis, clearing)
 
     configuration = _configuration_key(registry, plugins, models, advisories, dependencies, routes, escaped)
     keys = module_keys(
@@ -620,13 +633,15 @@ def _analyse_batch(batch: _Batch) -> dict[str, dict[str, Any]]:
         (a for plugin in all_plugins for a in plugin.advisories), file_advisories
     )
     affected = affected_symbols(dependencies, advisories)
-    models = plugin_models(all_plugins).extended(*advisory_sinks(affected))
+    models = plugin_models(all_plugins, batch.root).extended(*advisory_sinks(affected))
     routes = _decode_routes(batch.routes)
+    escaped = frozenset(batch.escaped)
     for manager in managers.values():
         manager.provide(SecurityModelAnalysis, models)
         manager.provide(DependencyAnalysis, dependencies)
         manager.provide(RegisteredRoutes, routes)
-        manager.provide(EscapedTemplates, frozenset(batch.escaped))
+        manager.provide(EscapedTemplates, escaped)
+        manager.provide(ClearingAnalysis, models.clearing(escaped))
     module_plugins = tuple(p for p in all_plugins if not isinstance(p, ProjectPlugin))
     results = _analyse_managers(managers, decode_index(batch.seed), module_plugins, affected)
     return {name: encode(entry) for name, entry in results.items()}

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/findings/refutation.py

@@ -29,7 +29,12 @@ from coretrace_python.abstract import ConstantPropagation, RangeAnalysis, RangeF
 from coretrace_python.analysis import AnalysisContext, AnyAnalysis, FunctionAnalysis
 from coretrace_python.cfg import CFG, BlockId, CFGAnalysis, DominanceAnalysis, DominatorTree
 from coretrace_python.hir import nodes
-from coretrace_python.interprocedural import CallGraphAnalysis
+from coretrace_python.interprocedural import (
+    CallGraph,
+    CallGraphAnalysis,
+    KnownFunction,
+    project_symbol,
+)
 from coretrace_python.ir.model import (
     BoolOp,
     Branch,
@@ -55,6 +60,7 @@ from coretrace_python.taint import (
     TaintAnalysis,
     TaintFacts,
     TaintFlow,
+    TaintKind,
 )
 
 VALIDATORS = frozenset(
@@ -214,15 +220,16 @@ class _Judge:
 
     def interpret(
         self, condition: Value, truth: bool | None
-    ) -> tuple[dict[Value, str], set[Value]]:
-        """Values the condition proves safe (with the reason), and values it mentions
-        without proving anything. ``truth`` is ``None`` when it is not fixed at the sink.
+    ) -> tuple[dict[Value, tuple[str, TaintKind]], set[Value]]:
+        """Values the condition proves safe (with the reason and the kinds it proves them
+        safe for), and values it mentions without proving anything. ``truth`` is ``None``
+        when it is not fixed at the sink.
 
         A recognised check evaluated the wrong way (``isdigit()`` known false) yields
         nothing: it is neither a proof nor a reassuring guard."""
 
         definition = self.defs.get(condition)
-        proven: dict[Value, str] = {}
+        proven: dict[Value, tuple[str, TaintKind]] = {}
         mentioned: set[Value] = set()
         if isinstance(definition, UnaryOp) and definition.operator == "not":
             return self.interpret(definition.operand, None if truth is None else not truth)
@@ -236,27 +243,29 @@ class _Judge:
         recognised = self.recognise(definition)
         if recognised is None:
             return proven, set(self.closure(condition)) | {condition}
-        tested, reason, when_true = recognised
+        tested, reason, when_true, kinds = recognised
         if truth is None:
             mentioned = set(self.closure(condition)) | {condition}
         elif truth == when_true:
             # The check proves ``tested``; whatever else it reads is merely mentioned.
-            proven[tested] = reason
+            proven[tested] = (reason, kinds)
             mentioned = set(self.closure(condition)) | {condition}
         return proven, mentioned
 
-    def recognise(self, definition: Instruction | None) -> tuple[Value, str, bool] | None:
-        """``(validated value, reason, truth that validates)`` for known check shapes."""
+    def recognise(self, definition: Instruction | None) -> tuple[Value, str, bool, TaintKind] | None:
+        """``(validated value, reason, truth that validates, kinds it proves)`` for known
+        check shapes. A string check, a constant allowlist or an equality with a constant
+        proves every kind; a ``Validator`` only the kinds it declares."""
 
         if isinstance(definition, Call) and not definition.arguments:
             callee = self.defs.get(definition.callee)
             if isinstance(callee, GetAttr) and callee.attribute in VALIDATORS:
-                return callee.object, f"guarded by {callee.attribute}()", True
+                return callee.object, f"guarded by {callee.attribute}()", True, TaintKind.ALL
         if isinstance(definition, Call):
             symbol = self.symbols.get(definition.callee)
             validator = self.models.validator(symbol) if symbol is not None else None
             if validator is not None and validator.argument < len(definition.arguments):
-                return definition.arguments[validator.argument], f"validated by {symbol}", True
+                return definition.arguments[validator.argument], f"validated by {symbol}", True, validator.kinds
         if isinstance(definition, Compare):
             left, right = definition.left, definition.right
             if definition.operator in ("in", "not_in") and self.is_constant_collection(right):
@@ -264,11 +273,12 @@ class _Judge:
                     left,
                     "allowlisted by a membership check on constants",
                     definition.operator == "in",
+                    TaintKind.ALL,
                 )
             if definition.operator in ("eq", "not_eq"):
                 for tested, other in ((left, right), (right, left)):
                     if isinstance(self.defs.get(other), Constant):
-                        return tested, "equals a constant", definition.operator == "eq"
+                        return tested, "equals a constant", definition.operator == "eq", TaintKind.ALL
         return None
 
     def examined(
@@ -387,8 +397,9 @@ class _Judge:
         )
         for guard in self.guards(sink):
             found, mentioned = self.interpret(guard.condition, guard.truth)
-            for value, reason in found.items():
-                if value in chain:
+            for value, (reason, kinds) in found.items():
+                # A check proving some kinds only leaves the others reaching the sink.
+                if value in chain and not flow.kinds & ~kinds:
                     proven.setdefault(value, reason)
             examined = self.examined(guard.condition, mentioned, flow.argument, chain)
             for origin in origins:
@@ -478,6 +489,7 @@ class RefutationAnalysis(FunctionAnalysis[Verdicts]):
         constants = ctx.get(ConstantPropagation, function)
         graph = ctx.get(CallGraphAnalysis)
         models = ctx.get(SecurityModelAnalysis)
+        name = graph.name_of(function)
         return judge_flows(
             ssa,
             ctx.get(CFGAnalysis, function),
@@ -486,7 +498,21 @@ class RefutationAnalysis(FunctionAnalysis[Verdicts]):
             frozenset(b.id for b in ssa.blocks if constants.reachable(b.id)),
             ctx.get(RangeAnalysis, function),
             models,
-            graph.symbols(graph.name_of(function)),
+            _with_project_callees(ssa, graph, name, ctx.module.name),
             authorization_of(function, models, ctx.get(ScopeAnalysis), ctx.get(SymbolAnalysis)),
         )
 
+
+def _with_project_callees(function: FunctionIR, graph: CallGraph, name: str, module: str) -> dict[Value, SymbolId]:
+    """The symbols of ``name``'s values, with each call to a function of its module named
+    by its project symbol, so a model declared on it (``Validator``) applies there too."""
+
+    symbols = dict(graph.symbols(name))
+    for block in function.blocks:
+        for instruction in block.instructions:
+            if isinstance(instruction, Call):
+                target = graph.target_at(name, instruction.location)
+                if isinstance(target, KnownFunction):
+                    symbols.setdefault(instruction.callee, project_symbol(module, target.name))
+    return symbols
+

{coretrace_python_analyzer-0.7.0 → coretrace_python_analyzer-0.9.0}/src/coretrace_python/interprocedural/__init__.py

@@ -20,6 +20,9 @@ from coretrace_python.interprocedural.modulegraph import (
     project_symbol,
 )
 from coretrace_python.interprocedural.summaries import (
+    Cleared,
+    Clearing,
+    ClearingAnalysis,
     ExternalCall,
     FunctionSummary,
     Mutation,
@@ -28,6 +31,7 @@ from coretrace_python.interprocedural.summaries import (
     SummaryAnalysis,
     SummaryIndex,
     SummaryTable,
+    cleared_by,
 )
 
 __all__ = [
@@ -35,6 +39,9 @@ __all__ = [
     "CallGraph",
     "CallGraphAnalysis",
     "CallSite",
+    "Cleared",
+    "Clearing",
+    "ClearingAnalysis",
     "ExternalCall",
     "ExternalSymbol",
     "FunctionSummary",
@@ -51,6 +58,7 @@ __all__ = [
     "Target",
     "UnknownTarget",
     "build_module_graph",
+    "cleared_by",
     "discover_files",
     "discover_sources",
     "project_symbol",