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

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

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.20.0 (2026-09-30)
+
+### Advisories
+
+- An advisory condition of kind `keyword_name` says the attacker must choose a keyword name of the call, as Django's ORM takes column aliases and lookups (`annotate(**{alias: expr})`); it carries its text and nothing else. The engine decides it from the keys of what the call expands with `**`, apart from the mapping's values: keys carrying attacker input meet it and the call is exploitable; constant keys, a dict literal with string keys, `dict(total=...)` or plain keywords, contradict it whatever the values carry, so the call is ruled out (`app.views:12 python.app.models.Item.objects.annotate(keywords=total)`, `(keywords absent)` for a call passing no keyword) and a project passing only those stays `not_affected`; keys the engine cannot establish, a `**extra` parameter, a mapping built elsewhere, `dict(zip(...))`, leave it pending review, so the call is reachable, and exploitable when the mapping's values carry input (#193).
+
+### Analysis
+
+- The keys of a mapping carry taint of their own, apart from its values: a dict literal `{alias: expr}`, `dict([(alias, expr)])`, a comprehension `{k: expr for k in input}` and a subscript assignment `mapping[alias] = expr` taint the `keys` location of the mapping's abstract object, which `{**mapping}`, `dict(mapping)` and `dict(**mapping)` copy; the value taint of a literal is what it was. A call expanding such a mapping with `**` passes its keys as the keyword names of the call, a way of passing only an advisory sink reads. Keys through a project wrapper are not followed; `mapping.update(other)`, `mapping.setdefault(k, v)`, `for k in mapping` and `mapping.keys()` carry no key taint; a mapping bound by a `Phi` is unknown (#193).
+
+### Plugins
+
+- `Arguments.keyword_unpacked` says a call expands a `**mapping` whose keys it does not write; a `**` literal with constant keys that nothing else uses is recorded as its keywords, so `given()` decides safe arguments and argument conditions for it. The cache format changes.
+
+## 0.19.0 (2026-09-29)
+
+### Analysis
+
+- Two files with the same Python module name, `a/app.py` and `z/app.py` outside any package, no longer overwrite each other: both are discovered, analysed and covered whatever the order they are found in. The engine tells them apart by their path from the root as a module name, `a.app` and `z.app`, in the module graph, the summary index, the cache keys and what project plugins see; a unique name stays what it was. An import of such a name resolves to the file in the importer's own root only, and one no root resolves is not followed. Each colliding file carries an `ambiguous-module` note and is covered as `ambiguous`, since a model or a route naming `python.app.main` applies to every definition of that symbol, and so does an importer whose import stayed unresolved; a VEX statement over such a project stays `under_investigation` (#182).
+
+### Precision
+
+- A `TEMPLATES` assigned inside a function or a class no longer counts as Django settings: only a module-level assignment can activate the `request` context processor, and only a mention of the module's `TEMPLATES` elsewhere leaves that activation uncertain. A function-local `TEMPLATES`, called or not, used to enable the implicit request source, upgrading a template filter finding to exploitable (#184).
+- A template block that renders `{{ block.super }}` keeps the parent block's content, so the filters the parent applies stay fed by the render context, with the parent template as the place of the call; a block without it still replaces the parent's whole block, and a chain of templates keeps exactly the parents each level renders. The parent's filters used to drop out of the exploitable flow as soon as a child defined the block (#185).
+- A project tag library registering a filter of a built-in's name replaces the built-in in every Django template loading it before applying the filter, as Django's parser does: `{% load custom %}{{ bio|striptags }}` calls the project's `striptags` when `app/templatetags/custom.py` registers one, so it is no longer a reachable or exploitable call to `django.template.defaultfilters.striptags`; the project's function is ordinary code, analysed as any other. A load affects only the filters after it, a later load overrides an earlier one, `{% load striptags from custom %}` replaces only what it names, and Django's own libraries change nothing. The analyzer reads the registrations on `register`, a `django.template.Library` however it is imported, in decorator and call form, at module level or under `if`, `try` or a function. Where it cannot tell what a library registers — no such library file, one it cannot read or parse, a name not written as a constant, `register` passed elsewhere or filled through `filters=` or `register.filters`, or two apps giving the name and registering different filters — a filter of that name applied under the load is neither the built-in nor certainly replaced: no call is claimed, and the load counts among the templates the analyzer could not read (`app/templates/app/profile.html:1 loads 'custom', not read`), so an advisory naming the filter stays `under_investigation` in the VEX document. The settings' `OPTIONS["libraries"]` and `OPTIONS["builtins"]` are not read (#183).
+
+### Plugins
+
+- `ModuleFunction.aliases` gives a project plugin the module-level names bound to a function by assigning one name to another, transitively and in source order, so an integration declaring a handler by the name a module binds (`handlers.main`) can report a name the engine resolves to no function; a method or a nested function has none. The cache format changes.
+- An `EntryPoint` naming a project function or class applies through a module-level alias of it: `main = actual` makes `python.app.handlers.main` name `actual`, so a deployment declaring `handlers.main` reaches the function doing the work. An alias is an assignment of one name to another at module level, followed transitively and in source order, in a conditional or a `try` as well; a name bound inside a function or class, or to a call, an import or anything but a name, is no alias, and the engine still infers nothing from a name. A model naming a method wins over one naming its class, whichever name it uses.
+
 ## 0.18.0 (2026-09-28)
 
 ### Precision

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.18.0
+Version: 0.20.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.18.0 → coretrace_python_analyzer-0.20.0}/docs/plugins.md

@@ -53,7 +53,11 @@ resolved through imports and aliases, so `python.os.system` covers `os.system`,
 symbol, so a chain such as `sqlite3.connect(p).cursor().execute` is
 `python.sqlite3.connect.cursor.execute`, and `app = Flask(__name__)` gives `app.route` the
 symbol `python.flask.Flask.route`. Builtins are `python.builtins.<name>`. Symbols are
-`SymbolId` values from `coretrace_python.semantic.symbols`.
+`SymbolId` values from `coretrace_python.semantic.symbols`. A function of the project is
+`python.` followed by its module's import name and its qualified name,
+`python.app.handlers.main`; two files with the same import name, `a/app.py` and
+`z/app.py` outside any package, define the same symbols, so a model naming
+`python.app.main` names the function of each.
 
 ## Kinds of plugin
 
@@ -190,7 +194,9 @@ 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
 reported, calls to the affected symbols become reachable vulnerabilities and tainted
-calls become exploitable ones.
+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.
 
 ### Reclassifying findings: `ProjectPlugin.refine`
 
@@ -255,14 +261,19 @@ module graph, the dependency graph, every advisory the plugins and advisory file
 contributed, the policy, the project root, and each module's imports, call graph and
 functions. `ctx.functions(module)` gives every function as the call graph names it
 (`Admin.get`, `outer.inner`, `<module>`), with its span, so a finding can be placed in
-one, and the label of the entry point it is (`http` for a route, `argv` for a command)
-when the models make it one. `ctx.call_graph(module)` gives each function's call sites
+one, the label of the entry point it is (`http` for a route, `argv` for a command)
+when the models make it one, and its `aliases`, the module-level names bound to it by
+assigning one name to another (`main = actual`), transitively and in source order, so
+an integration declaring a handler by the name a module binds can tell a name the
+engine resolves to no function; a method or a nested function has none. `ctx.call_graph(module)` gives each function's call sites
 (`sites(function)`) and the symbols it reads, called or not (`reads(function)`: reading
 `request.form['name']` reads `python.flask.request.form`), each where it first reads it.
 `ctx.templates` gives the templates found under the project's `templates` directories:
-their `names`, the filters they apply as `calls` (each a `FilterCall(symbol, span)`, the
-function behind the filter and where the template applies it), and where they name a
-template the analyzer cannot read (`unread`).
+their `names`, the filters of Django's own libraries they apply as `calls` (each a
+`FilterCall(symbol, span)`, the function behind the filter and where the template
+applies it; a filter a project tag library the template loads replaces is no call),
+and where they name a template the analyzer cannot read, or load a library it cannot
+read while applying a filter of that library's name (`unread`).
 The shipped `vulnerable-dependency`, `reachable-vulnerability` and `dependency-policy`
 plugins are of this kind.
 

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

@@ -65,7 +65,13 @@ coretrace-python-analyzer [--check | --emit-ir [--ssa]] [options] [path]
 ## What is analysed
 
 Given a directory, every `.py` file below it is a module of one project, named after
-its package (`app/views.py` is `app.views`). Hidden directories, `node_modules`,
+its package (`app/views.py` is `app.views`). Two files that would share a name, `a/app.py`
+and `z/app.py` outside any package, are told apart by their path from the root, `a.app`
+and `z.app`, and reported: each carries an `ambiguous-module` note, since a symbol
+`python.app.main` may name a function of either and an import of `app` resolves only
+from the importer's own directory, and each is covered as `ambiguous` rather than
+analysed. An import of such a name that no file of the importer's own directory answers
+is noted where it is written and not followed. Hidden directories, `node_modules`,
 `__pycache__`, `build`, `dist` and any virtual environment, recognised by its
 `pyvenv.cfg` whatever its name, are skipped. Dependency files at the root
 (`requirements*.txt`, `pyproject.toml`, `poetry.lock`, `uv.lock`) are read into a
@@ -241,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.18.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.20.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -261,7 +267,9 @@ the directory of the checked file; a path outside it is printed as it is.
 }
 ```
 
-`root` is the directory the paths are relative to.
+`root` is the directory the paths are relative to. A file's `status` is `analysed`,
+`ambiguous` (analysed, but another file has its module name, see above), `syntax-error`
+or `unreadable`; only `analysed` files count in `files_analysed`.
 
 A directory check also lists, in `tool.components`, what the result was produced with
 besides the engine and the sources: each plugin it loaded, by manifest name and version,
@@ -273,7 +281,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.18.0",
+  "name": "coretrace-python-analyzer", "version": "0.20.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -372,6 +380,28 @@ Django. Most filters are functions of the same name in `django.template.defaultf
 are `<name>_filter` there, and the filters of `i18n`, `l10n`, `tz` and `humanize` are in
 their library's module (`timezone` is `django.templatetags.tz.do_timezone`).
 
+A project tag library, a module of a `templatetags` directory, that registers a filter
+of that name replaces the built-in in every template loading it, as Django's parser
+does: `{% load custom %}{{ bio|striptags }}` calls the project's function when
+`custom.py` registers a `striptags` filter, which is no call to the built-in; the
+project's function is ordinary code, whose own calls are analysed as any other. A
+load affects only the filters applied after it in the file, a later load overrides an
+earlier one, `{% load striptags from custom %}` replaces only the filters it names, and
+Django's own libraries (`static`, `i18n`, `l10n`, `tz`, `cache`, `humanize`) change
+nothing. The analyzer reads the registrations on the library's `register`, a
+`django.template.Library` however it is imported: `@register.filter`,
+`@register.filter("name")`, `@register.filter(name="name", is_safe=True)`,
+`register.filter("name", function)` and `register.filter(function)`, at module level or
+under `if`, `try` or a function. Where it cannot tell what a library registers, the
+filter is neither the built-in nor certainly replaced: a library found in no
+`templatetags` directory (one an installed package ships, or that the settings'
+`OPTIONS["libraries"]` or `OPTIONS["builtins"]` name, which are not read), a file it
+cannot read or parse, a name given by a variable or unpacked arguments, `register`
+passed to another function, filled through `filters=` or `register.filters`, or bound
+to anything but a `Library`, or two apps giving the same library name and registering
+different filters. The analyzer then claims no call, and counts the template among those
+it could not read (below) when a filter of the library's name is applied under the load.
+
 Attacker input in the render context makes the filter exploitable at the render call:
 `render(request, "app/profile.html", {"bio": request.POST["bio"]})` with
 `{{ bio|striptags }}`. The analyzer links a context value to a filter only where it is
@@ -386,7 +416,8 @@ certain of it:
   arguments of the filters before it, or the output of a `{% filter %}` block. A name a
   tag binds shadows the context, and `{% include ... only %}` passes none of it.
 - The filter renders: a template extending another renders only its blocks, which
-  replace the blocks of that name in what it extends.
+  replace the blocks of that name in what it extends, unless the block renders
+  `{{ block.super }}`, which keeps the parent's content and the filters it applies.
 - One file has the template's name; of two files of the same name, which one renders
   depends on the loaders.
 
@@ -399,9 +430,12 @@ With the `django.template.context_processors.request` context processor, a templ
 rendered with the request reads it as `request`: `{{ request.GET.q|striptags }}` is
 exploitable at the render call too. The analyzer counts it only where all of these hold:
 
-- The project's settings assign `TEMPLATES` a literal list, every `DjangoTemplates`
-  engine of it lists the processor in a literal `context_processors`, and no other code
-  of the project names `TEMPLATES`. A mere mention of the processor proves nothing.
+- The project's settings assign `TEMPLATES` a literal list at module level, every
+  `DjangoTemplates` engine of it lists the processor in a literal `context_processors`,
+  and no other code of the project names the module's `TEMPLATES`, or a `TEMPLATES` it
+  does not bind, as a star import gives. A `TEMPLATES` bound in a function or a class
+  is another name: it configures nothing and changes nothing.
+  A mere mention of the processor proves nothing.
 - The render call passes the request: `render` and `TemplateResponse` always do,
   `render_to_string` when given `request`, `SimpleTemplateResponse` never.
 - The render's context is certain, absent or a dict literal as above, so it cannot hide
@@ -454,6 +488,32 @@ attacker's input is passed in that argument. The outcome has three cases:
 
 The other conditions, the environment included, stay pending as before.
 
+A `keyword_name` condition says the attacker must choose a keyword name of the call,
+as Django's ORM takes column aliases and lookups (`annotate(**{alias: expr})`):
+`{"kind": "keyword_name", "text": "…"}`, and nothing else. The engine decides it from
+the keys of what the call expands with `**`; the values of the mapping do not decide
+it. The outcome has three cases:
+
+- Keys carrying attacker input meet it, and the call is exploitable. Key taint is
+  carried, apart from value taint, for a dict literal `{alias: expr}`,
+  `dict([(alias, expr)])`, a comprehension `{k: expr for k in request.GET}` and a
+  subscript assignment `mapping[alias] = expr`, and copied by `{**mapping}` and
+  `dict(mapping)`.
+- Constant keys — a dict literal with string keys, `dict(total=…)`, plain keywords —
+  contradict it, whatever the values carry: the call is ruled out
+  (`app.views:12 python.app.models.Item.objects.annotate(keywords=total)`, or
+  `(keywords absent)` for a call passing no keyword), and a project passing only those
+  stays `not_affected`.
+- Keys the engine cannot establish — a `**extra` parameter, a mapping built elsewhere
+  or returned by a function, `dict(zip(...))`, `**request.GET` — leave it pending
+  review, as any unknown argument does: the call is reachable, and exploitable when the
+  mapping's values carry attacker input.
+
+Keys passed through a project wrapper stay pending, and `mapping.update(other)`,
+`mapping.setdefault(k, v)`, `for k in mapping` and `mapping.keys()` carry no key
+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.
+
 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
@@ -502,10 +562,14 @@ A template the analyzer cannot read may apply any filter. The project names one
 `render`, `render_to_string`, `TemplateResponse`, an `{% include %}` or an `{% extends %}`
 names a template by an expression, or by a name found under no `templates` directory,
 including one an installed package ships; a template file that cannot be read counts
-too. An advisory whose entry points include a template filter then stays
-`under_investigation`, and the notes list where the project names each such template
-(`app.views:12 names a template by an expression`). A template named elsewhere, such as
-a class-based view's `template_name`, is not checked.
+too, and so does a template loading a tag library the analyzer cannot read, or find,
+or finds in several apps registering different filters, where it then applies a filter
+of a built-in's name, since the library may replace it. An advisory whose entry points
+include a template filter then stays `under_investigation`, and the notes list where
+the project names each such template (`app.views:12 names a template by an
+expression`, `app/templates/app/profile.html:1 loads 'crispy_forms_tags', not found`).
+A template named elsewhere, such as a class-based view's `template_name`, is not
+checked.
 
 `not_affected` needs the lock-file check because the analyzer reads the project's code,
 not the code of installed packages. A framework calling the vulnerable function on the
@@ -513,7 +577,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.18.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.20.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.18.0 → coretrace_python_analyzer-0.20.0}/pyproject.toml

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

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

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

{coretrace_python_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/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_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/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_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/coretrace_python/cache.py

@@ -42,7 +42,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
 
-CACHE_FORMAT = 10
+CACHE_FORMAT = 12
 
 
 @dataclass(frozen=True)
@@ -134,7 +134,7 @@ class ProjectCache:
 def encode(module: CachedModule) -> dict[str, Any]:
     return {
         "format": CACHE_FORMAT,
-        "functions": [[f.name, _encode_span(f.span), f.entry_point] for f in module.functions],
+        "functions": [[f.name, _encode_span(f.span), f.entry_point, list(f.aliases)] for f in module.functions],
         "summaries": {name: _encode_summary(s) for name, s in module.summaries.items()},
         "sites": [_encode_site(site) for site in module.sites],
         "findings": [_encode_finding(finding) for finding in module.findings],
@@ -196,8 +196,13 @@ def _decode_span(data: Any) -> SourceSpan:
 
 
 def _decode_function(data: Any) -> ModuleFunction:
-    name, span, entry_point = data
-    return ModuleFunction(_string(name), _decode_span(span), None if entry_point is None else _string(entry_point))
+    name, span, entry_point, aliases = data
+    return ModuleFunction(
+        _string(name),
+        _decode_span(span),
+        None if entry_point is None else _string(entry_point),
+        tuple(_string(alias) for alias in aliases),
+    )
 
 
 def _decode_read(data: Any) -> SymbolRead:
@@ -363,6 +368,7 @@ def _encode_arguments(arguments: Arguments) -> dict[str, Any]:
         "positional": list(arguments.positional),
         "keywords": [[name, value] for name, value in arguments.keywords],
         "unpacked": arguments.unpacked,
+        "keyword_unpacked": arguments.keyword_unpacked,
     }
 
 
@@ -370,11 +376,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_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/coretrace_python/dependency/advisories.py

@@ -263,4 +263,8 @@ def _condition(entry: Mapping[str, Any]) -> Condition:
         (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_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/coretrace_python/dependency/correlation.py

@@ -23,7 +23,7 @@ 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.semantic.symbols import SymbolId
-from coretrace_python.taint import Sink, TaintFlow, TaintKind
+from coretrace_python.taint import KEYWORD_NAMES, Sink, TaintFlow, TaintKind
 from coretrace_python.taint.urls import UrlProof, redirects_disabled
 
 Affected = Mapping[SymbolId, tuple[Advisory, ...]]
@@ -72,13 +72,25 @@ def check_conditions(
     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."""
 
     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:
@@ -119,7 +131,8 @@ 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
+    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})"
 

{coretrace_python_analyzer-0.18.0 → coretrace_python_analyzer-0.20.0}/src/coretrace_python/dependency/graph.py

@@ -154,7 +154,10 @@ class Condition:
     ``default`` says an absent argument means a vulnerable value. 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 ``semantic`` condition cannot be checked and is
+    reported as pending review."""
 
     kind: str
     text: str