coretrace-python-analyzer 0.11.0__tar.gz → 0.12.0__tar.gz

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.12.0 (2026-09-26)
+
+### Detection
+
+- A module-level name bound to an attribute, an item or a call of another module-level name resolves in functions, as the same value does in a function body. `cursor = conn.cursor()` after `conn = sqlite3.connect(...)`, `db = client.shop` and `run = os.system` used to leave the calls made through them unknown, so a query built from request data and executed through a module-level cursor was not reported. Names resolve in statement order. The regression corpus is unchanged (#155).
+- `nosql-injection` reports attacker input that may hold a structure reaching a NoSQL sink, such as a MongoDB filter, where a JSON body giving `{"$ne": null}` matches any value. Only input that may hold a structure carries `NOSQL`: JSON, the raw bodies a `json.loads` decodes, files, WebSocket messages and standard input. Text cannot hold an operator. The text sources of Flask, bottle and tornado, the URL parameters of their routes, the command line, the environment and `input()` no longer carry `NOSQL`. Neither does an entry-point parameter annotated with scalars (`str`, `Optional[int]`, `Annotated[str, Query()]`, `list[str]`, …), which FastAPI validates. Two limits remain. Django and aiohttp request objects stay tainted as a whole. The keys of a dict are not followed, so a string concatenated into `$where` is not reported. The engine ships no NoSQL sink: model plugins declare them (#158).
+
+### Plugins
+
+- `TEXT_KINDS` holds every kind but `NOSQL`: what text input carries. A model plugin declares its text sources with it (#158).
+
+- A `Members(symbol, dynamic=None, defined=(), typed=())` model says what the attributes and items of a class's instances give, for libraries whose objects give others by names the project chooses. A pymongo client gives the database it is dotted or indexed with, a database gives a collection. The names used to end up in the symbol (`MongoClient.shop.users.find`), or an item vanished into its container's symbol (`MongoClient.find`), so no model could list them. With the model, every path to a collection denotes the collection class, the one a parameter annotated `Collection` denotes: `client.shop.users`, `client["shop"]["users"]`, `client.get_database("shop").get_collection("users")`, a module-level `db = client.shop`, an attribute inherited from the client class. A sink on `Collection.find` covers them all. Symbol resolution now depends on these models, which the engine provides to every module and worker (#157).
+
 ## 0.11.0 (2026-09-25)
 
 ### Detection

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.11.0
+Version: 0.12.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.11.0 → coretrace_python_analyzer-0.12.0}/docs/plugins.md

@@ -140,7 +140,7 @@ class BottleModels(ModelPlugin):
 
 | Model | Declares |
 |---|---|
-| `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. |
+| `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. Text input, such as a form field, a header or a URL parameter, carries `TEXT_KINDS`, every kind but `NOSQL`: a string cannot hold a query operator. |
 | `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`, 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`. |
@@ -152,6 +152,7 @@ class BottleModels(ModelPlugin):
 | `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 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. |
+| `Members(symbol, dynamic=None, defined=(), typed=())` | What the attributes and items of an instance of the class `symbol` give, for objects that give others by name. `typed` maps an attribute to the class of what it gives, called or not, since a call denotes its callee: pymongo's `get_database` gives a `Database`, as Flask-PyMongo's `db` property does. `dynamic`, when set, is the class of every item and of every attribute outside `defined` and `typed`: a pymongo client gives a `Database` by name (`client.shop`, `client["shop"]`), a database a `Collection`. Every path to a collection then denotes the collection class, so a sink on `Collection.find` covers them all. Without `dynamic`, an attribute keeps its path and an item its container's symbol, as for any class. |
 
 Two plugins may describe the same symbol. An identical model is registered once; two
 `Sink` models merge their kinds, positions and keywords, so a plugin can add `SQL` to a sink

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/docs/usage.md

@@ -112,6 +112,7 @@ variable is not treated that way yet.
 | `command-injection` | Shell or process execution (`os.system`, `subprocess` with a string, …). |
 | `code-injection` | The code `eval` or `exec` runs; the globals and locals passed with it are data. `dangerous-eval` reports every such call, this rule the ones attacker input reaches. |
 | `sql-injection` | A database statement (`cursor.execute`, SQLAlchemy `text`, Django `raw`, …). Parameters of a parameterised query are not statements. |
+| `nosql-injection` | A NoSQL query, such as a MongoDB filter, given attacker input that may hold a structure: a JSON body giving `{"$ne": null}` matches any value. The input that may hold a structure is JSON, the raw bodies a `json.loads` decodes, files, WebSocket messages and standard input. Text cannot hold an operator: form fields, query parameters, headers, cookies, URL parameters, the command line, the environment, and an entry-point parameter annotated with scalars (`str`, `int`, `Optional[str]`, `Annotated[str, Query()]`, `list[str]`, …), which FastAPI validates. Limits: a Django or aiohttp request object is tainted as a whole, so `request.GET` counts like `request.body`; the keys of a dict are not followed, so a string concatenated into `$where` is not reported. The analyzer ships no NoSQL sink: model plugins declare them. |
 | `path-traversal` | A file system path (`open`, `send_file`, `os.remove`, …). |
 | `ssrf` | The URL of an HTTP client request (Requests, httpx, `urllib`), by position or as `url=`; the body, headers and query parameters are not the destination. |
 | `xss` | An HTTP response body built without escaping. A Django template rendered by `render_to_string` escapes, where the analyzer can establish it (below). |
@@ -240,7 +241,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.11.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.12.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -272,7 +273,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.11.0",
+  "name": "coretrace-python-analyzer", "version": "0.12.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -435,7 +436,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.11.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.12.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.11.0 → coretrace_python_analyzer-0.12.0}/pyproject.toml

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

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/__init__.py

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

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/bundled/models/bottle/bottle_models.py

@@ -8,13 +8,15 @@ from typing import ClassVar
 
 from coretrace_python.plugins import ModelPlugin
 from coretrace_python.semantic.symbols import SymbolId
-from coretrace_python.taint import EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
+from coretrace_python.taint import TEXT_KINDS, EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
 
 _METHODS = ("route", "get", "post", "put", "delete", "patch")
-_REQUEST_ATTRIBUTES = (
-    "query", "forms", "params", "json", "body", "headers", "cookies", "GET", "POST", "files",
+# Text, which cannot hold a query operator; JSON, raw bodies and files may hold a structure.
+_TEXT_ATTRIBUTES = (
+    "query", "forms", "params", "headers", "cookies", "GET", "POST",
     "url", "path", "fullpath", "query_string", "get_cookie", "get_header",
 )
+_PAYLOAD_ATTRIBUTES = ("json", "body", "files")
 _FIRST_ONLY = lambda kind: ((kind, (0,)),)
 
 
@@ -25,9 +27,11 @@ def _sym(path: str) -> SymbolId:
 class BottleModels(ModelPlugin):
     name: ClassVar[str] = "bottle-models"
     models: ClassVar[tuple[Model, ...]] = (
-        *(EntryPoint(_sym(f"bottle.{method}"), "http") for method in _METHODS),
-        *(EntryPoint(_sym(f"bottle.Bottle.{method}"), "http") for method in _METHODS),
-        *(Source(_sym(f"bottle.request.{attribute}"), "http") for attribute in _REQUEST_ATTRIBUTES),
+        # A route's parameters are segments of its URL.
+        *(EntryPoint(_sym(f"bottle.{method}"), "http", TEXT_KINDS) for method in _METHODS),
+        *(EntryPoint(_sym(f"bottle.Bottle.{method}"), "http", TEXT_KINDS) for method in _METHODS),
+        *(Source(_sym(f"bottle.request.{attribute}"), "http", TEXT_KINDS) for attribute in _TEXT_ATTRIBUTES),
+        *(Source(_sym(f"bottle.request.{attribute}"), "http") for attribute in _PAYLOAD_ATTRIBUTES),
         Sink(_sym("bottle.redirect"), TaintKind.REDIRECT, _FIRST_ONLY(TaintKind.REDIRECT)),
         # ``static_file(filename, root)``: the root is the application's own.
         Sink(_sym("bottle.static_file"), TaintKind.PATH, _FIRST_ONLY(TaintKind.PATH)),

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/bundled/models/cli/cli_models.py

@@ -6,11 +6,11 @@ from typing import ClassVar
 
 from coretrace_python.plugins import ModelPlugin
 from coretrace_python.semantic.symbols import SymbolId
-from coretrace_python.taint import EntryPoint, Model, TaintKind
+from coretrace_python.taint import TEXT_KINDS, EntryPoint, Model, TaintKind
 
-# A command-line tool is expected to open the paths it is given: argv input carries every
-# kind but PATH.
-ARGV_KINDS = TaintKind.ALL & ~TaintKind.PATH
+# A command-line tool is expected to open the paths it is given: argv input is text,
+# without PATH.
+ARGV_KINDS = TEXT_KINDS & ~TaintKind.PATH
 
 _COMMANDS = (
     "click.command",

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/bundled/models/flask/flask_models.py

@@ -7,6 +7,7 @@ from typing import ClassVar
 from coretrace_python.plugins import ModelPlugin
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.taint import (
+    TEXT_KINDS,
     AuthorizationGuard,
     EntryPoint,
     Model,
@@ -17,10 +18,10 @@ from coretrace_python.taint import (
     TaintKind,
 )
 
-_REQUEST_ATTRIBUTES = (
-    "args", "form", "values", "json", "data", "cookies", "headers", "files",
-    "get_json", "get_data", "url", "full_path", "path", "query_string", "stream",
-)
+# Strings, or mappings of strings: text, which cannot hold a query operator.
+_TEXT_ATTRIBUTES = ("args", "form", "values", "cookies", "headers", "url", "full_path", "path", "query_string")
+# JSON, and the raw bodies and files a ``json.loads`` may decode into a structure.
+_PAYLOAD_ATTRIBUTES = ("json", "get_json", "data", "get_data", "stream", "files")
 
 
 _TARGET_ONLY = ((TaintKind.REDIRECT, (0,)),)
@@ -33,11 +34,13 @@ def _sym(path: str) -> SymbolId:
 class FlaskModels(ModelPlugin):
     name: ClassVar[str] = "flask-models"
     models: ClassVar[tuple[Model, ...]] = (
-        *(Source(_sym(f"flask.request.{attribute}"), "http") for attribute in _REQUEST_ATTRIBUTES),
-        EntryPoint(_sym("flask.Flask.route"), "http"),
-        EntryPoint(_sym("flask.Blueprint.route"), "http"),
-        RouteRegistrar(_sym("flask.Flask.add_url_rule"), 2, "http", keyword="view_func"),
-        RouteRegistrar(_sym("flask.Blueprint.add_url_rule"), 2, "http", keyword="view_func"),
+        *(Source(_sym(f"flask.request.{attribute}"), "http", TEXT_KINDS) for attribute in _TEXT_ATTRIBUTES),
+        *(Source(_sym(f"flask.request.{attribute}"), "http") for attribute in _PAYLOAD_ATTRIBUTES),
+        # A route's parameters are segments of its URL.
+        EntryPoint(_sym("flask.Flask.route"), "http", TEXT_KINDS),
+        EntryPoint(_sym("flask.Blueprint.route"), "http", TEXT_KINDS),
+        RouteRegistrar(_sym("flask.Flask.add_url_rule"), 2, "http", TEXT_KINDS, keyword="view_func"),
+        RouteRegistrar(_sym("flask.Blueprint.add_url_rule"), 2, "http", TEXT_KINDS, keyword="view_func"),
         Sink(_sym("flask.render_template_string"), TaintKind.HTML),
         Sink(_sym("flask.make_response"), TaintKind.HTML),
         Sink(_sym("flask.Response"), TaintKind.HTML),

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/bundled/models/python_stdlib/python_stdlib.py

@@ -7,6 +7,7 @@ from typing import ClassVar
 from coretrace_python.plugins import ModelPlugin
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.taint import (
+    TEXT_KINDS,
     Model,
     SafeArgument,
     Sanitizer,
@@ -16,7 +17,7 @@ from coretrace_python.taint import (
     Validator,
 )
 
-_ENVIRONMENT_KINDS = TaintKind.ALL & ~(TaintKind.COMMAND | TaintKind.PATH)
+_ENVIRONMENT_KINDS = TEXT_KINDS & ~(TaintKind.COMMAND | TaintKind.PATH)
 # SafeLoader and BaseLoader build plain data only, in Python and in C, under every spelling.
 _SAFE_YAML_LOADERS = (
     "python.yaml.SafeLoader",
@@ -38,13 +39,14 @@ def _sym(path: str) -> SymbolId:
 class PythonStdlibModels(ModelPlugin):
     name: ClassVar[str] = "python-stdlib-models"
     models: ClassVar[tuple[Model, ...]] = (
-        Source(_sym("builtins.input"), "stdin"),
+        # A line of text; the stream may be a payload ``json.load`` decodes.
+        Source(_sym("builtins.input"), "stdin", TEXT_KINDS),
         Source(_sym("sys.stdin"), "stdin"),
         # Operator-controlled inputs. A command-line tool is expected to open the paths
         # it is given; the environment is set by whoever runs the program, so a command
         # or a path built from it is not an injection; the output of a local process is
         # not a path either, but a downloaded script piped into a shell is a real flaw.
-        Source(_sym("sys.argv"), "argv", TaintKind.ALL & ~TaintKind.PATH),
+        Source(_sym("sys.argv"), "argv", TEXT_KINDS & ~TaintKind.PATH),
         Source(_sym("os.environ"), "environment", _ENVIRONMENT_KINDS),
         Source(_sym("subprocess.run.stdout"), "process-output", _PROCESS_OUTPUT_KINDS),
         Source(_sym("subprocess.check_output"), "process-output", _PROCESS_OUTPUT_KINDS),

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/bundled/models/tornado/tornado_models.py

@@ -8,12 +8,13 @@ from typing import ClassVar
 
 from coretrace_python.plugins import ModelPlugin
 from coretrace_python.semantic.symbols import SymbolId
-from coretrace_python.taint import EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
+from coretrace_python.taint import TEXT_KINDS, EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
 
 _HANDLERS = ("tornado.web.RequestHandler", "tornado.websocket.WebSocketHandler")
-_REQUEST_METHODS = (
+# Text, which cannot hold a query operator; the request object holds the raw body too.
+_TEXT_METHODS = (
     "get_argument", "get_arguments", "get_query_argument", "get_query_arguments",
-    "get_body_argument", "get_body_arguments", "get_cookie", "request", "path_args", "path_kwargs",
+    "get_body_argument", "get_body_arguments", "get_cookie", "path_args", "path_kwargs",
 )
 _CLIENTS = ("tornado.httpclient.AsyncHTTPClient.fetch", "tornado.httpclient.HTTPClient.fetch")
 _TARGET_ONLY = ((TaintKind.REDIRECT, (0,)),)
@@ -26,8 +27,12 @@ def _sym(path: str) -> SymbolId:
 class TornadoModels(ModelPlugin):
     name: ClassVar[str] = "tornado-models"
     models: ClassVar[tuple[Model, ...]] = (
-        *(EntryPoint(_sym(handler), "http") for handler in _HANDLERS),
-        *(Source(_sym(f"{handler}.{method}"), "http") for handler in _HANDLERS for method in _REQUEST_METHODS),
+        # A request handler's parameters are segments of its URL; a WebSocket handler also
+        # receives the messages, raw payloads a ``json.loads`` may decode.
+        EntryPoint(_sym("tornado.web.RequestHandler"), "http", TEXT_KINDS),
+        EntryPoint(_sym("tornado.websocket.WebSocketHandler"), "http"),
+        *(Source(_sym(f"{handler}.{method}"), "http", TEXT_KINDS) for handler in _HANDLERS for method in _TEXT_METHODS),
+        *(Source(_sym(f"{handler}.request"), "http") for handler in _HANDLERS),
         *(Sink(_sym(f"{handler}.write"), TaintKind.HTML) for handler in _HANDLERS),
         *(Sink(_sym(f"{handler}.finish"), TaintKind.HTML) for handler in _HANDLERS),
         *(Sink(_sym(f"{handler}.redirect"), TaintKind.REDIRECT, _TARGET_ONLY) for handler in _HANDLERS),

coretrace_python_analyzer-0.12.0/src/coretrace_python/bundled/security/nosql_injection/nosql_injection.py

@@ -0,0 +1,20 @@
+"""NoSQL injection: attacker input that may hold a structure reaching a NOSQL sink, such
+as a MongoDB filter, where a JSON body giving ``{"$ne": null}`` matches any value. Text
+input carries no ``NOSQL``: a string cannot hold an operator. The engine ships no NOSQL
+sink; model plugins declare them."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from coretrace_python.findings import Severity
+from coretrace_python.plugins import TaintDetector
+from coretrace_python.taint import TaintKind
+
+
+class NoSqlInjectionPlugin(TaintDetector):
+    name: ClassVar[str] = "nosql-injection"
+    rule_id: ClassVar[str] = "nosql-injection"
+    kind: ClassVar[TaintKind] = TaintKind.NOSQL
+    severity: ClassVar[Severity] = Severity.HIGH
+    title: ClassVar[str] = "NoSQL injection"

coretrace_python_analyzer-0.12.0/src/coretrace_python/bundled/security/nosql_injection/plugin.toml

@@ -0,0 +1,9 @@
+name = "nosql-injection"
+version = "1.0.0"
+plugin_api = ">=1,<2"
+requires = ["taint.flows", "findings.refutation"]
+provides = ["vulnerability.nosql-injection"]
+
+[entrypoint]
+module = "nosql_injection"
+class = "NoSqlInjectionPlugin"

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/engine.py

@@ -109,7 +109,7 @@ from coretrace_python.reporters import Report
 from coretrace_python.semantic import SEMANTIC_ANALYSES
 from coretrace_python.semantic.imports import ImportAnalysis, ImportResolutionError, ImportTable
 from coretrace_python.semantic.scopes import ScopeAnalysis, ScopeError
-from coretrace_python.semantic.symbols import SymbolAnalysis, SymbolId
+from coretrace_python.semantic.symbols import MembersAnalysis, SymbolAnalysis, SymbolId
 from coretrace_python.source import SourceFile, SourceId, SourceManager, SourceSpan, decode_text
 from coretrace_python.taint import (
     EntryPoint,
@@ -257,6 +257,7 @@ def build_manager(
     manager = _register_all(module)
     table = (models or SecurityModelRegistry()).freeze()
     manager.provide(SecurityModelAnalysis, table)
+    manager.provide(MembersAnalysis, table.members_by_class())
     manager.provide(ClearingAnalysis, table.clearing())
     manager.provide(ProjectSummaries, SummaryIndex())
     manager.provide(RegisteredRoutes, _routes_of(manager))
@@ -311,6 +312,7 @@ def analyze_file(source: SourceFile, plugin_roots: Sequence[Path]) -> FileAnalys
     registry = load_plugins(plugin_roots, manager)
     table = plugin_models(loaded.plugin for loaded in registry)
     manager.provide(SecurityModelAnalysis, table)
+    manager.provide(MembersAnalysis, table.members_by_class())
     manager.provide(ClearingAnalysis, table.clearing())
     manager.provide(ProjectSummaries, SummaryIndex())
     manager.provide(RegisteredRoutes, _routes_of(manager))
@@ -402,8 +404,10 @@ def analyze_project(
     advisories, origins = _merge_advisories(_contributions(registry, plugins, root, file_advisories))
     affected = affected_symbols(dependencies, advisories)
     models = plugin_models(all_plugins, root).extended(*advisory_sinks(affected))
+    members = models.members_by_class()
     for manager in managers.values():
         manager.provide(SecurityModelAnalysis, models)
+        manager.provide(MembersAnalysis, members)
         manager.provide(DependencyAnalysis, dependencies)
 
     imports: dict[str, ImportTable] = {}
@@ -698,8 +702,10 @@ def _analyse_batch(batch: _Batch) -> dict[str, dict[str, Any]]:
     models = plugin_models(all_plugins, batch.root).extended(*advisory_sinks(affected))
     routes = _decode_routes(batch.routes)
     escaped = frozenset(batch.escaped)
+    members = models.members_by_class()
     for manager in managers.values():
         manager.provide(SecurityModelAnalysis, models)
+        manager.provide(MembersAnalysis, members)
         manager.provide(DependencyAnalysis, dependencies)
         manager.provide(RegisteredRoutes, routes)
         manager.provide(EscapedTemplates, escaped)

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/interprocedural/callgraph.py

@@ -176,12 +176,12 @@ class CallGraph:
 
 
 def derive_symbols(
-    function: FunctionIR, initial: Mapping[Value, SymbolId] | None = None
+    function: FunctionIR, table: SymbolTable, initial: Mapping[Value, SymbolId] | None = None
 ) -> dict[Value, SymbolId]:
-    """Symbols of values: ``Symbol`` results, attributes and items of symbol values,
-    results of calling a symbol (``sqlite3.connect(p)`` denotes ``python.sqlite3.connect``)
-    and the values a ``with`` on such a result binds. Known functions derive nothing;
-    parameters only through ``initial``, their annotated classes."""
+    """Symbols of values: ``Symbol`` results, attributes and items of symbol values, as
+    ``table`` types them, results of calling a symbol (``sqlite3.connect(p)`` denotes
+    ``python.sqlite3.connect``) and the values a ``with`` on such a result binds. Known
+    functions derive nothing; parameters only through ``initial``, their annotated classes."""
 
     symbols: dict[Value, SymbolId] = dict(initial or {})
     changed = True
@@ -195,11 +195,9 @@ def derive_symbols(
                 if isinstance(instruction, Symbol):
                     symbol = instruction.symbol_id
                 elif isinstance(instruction, GetAttr) and instruction.object in symbols:
-                    symbol = symbols[instruction.object].attribute(instruction.attribute)
+                    symbol = table.attribute(symbols[instruction.object], instruction.attribute)
                 elif isinstance(instruction, GetItem) and instruction.object in symbols:
-                    # An item of a symbol-denoted container (``request.files['f']``)
-                    # carries the container's symbol, so its methods resolve.
-                    symbol = symbols[instruction.object]
+                    symbol = table.item(symbols[instruction.object])
                 elif isinstance(instruction, Call | WithEnter):
                     origin = (
                         instruction.callee if isinstance(instruction, Call) else instruction.context
@@ -263,6 +261,8 @@ def resolve_targets(
     owner: str | None = None,
     typed: Mapping[Value, str] | None = None,
     bases: Mapping[str, SymbolId] | None = None,
+    *,
+    table: SymbolTable,
 ) -> tuple[dict[Value, Target], dict[Value, SymbolId]]:
     """Map every callee value of ``function`` to its target, and every symbol value.
     ``nested`` names the functions defined inside this one (``outer.inner``);
@@ -271,7 +271,8 @@ def resolve_targets(
     call to ``App.__init__``, ``app.run()`` and ``self.run()`` calls to ``App.run``.
     ``bases`` maps a module class to the symbol of its base: an attribute the class does
     not define is inherited, so ``self.get_argument`` in a ``RequestHandler`` subclass
-    denotes ``tornado.web.RequestHandler.get_argument``."""
+    denotes ``tornado.web.RequestHandler.get_argument``. ``table`` says what the
+    attributes and items of a class a ``Members`` model describes give."""
 
     module = scopes.module_scope
     classes = classes or {}
@@ -294,8 +295,8 @@ def resolve_targets(
                 class_name = instance_of[instruction.object]
                 base = (bases or {}).get(class_name)
                 if base is not None and instruction.attribute not in classes.get(class_name, ()):
-                    inherited[instruction.result] = base.attribute(instruction.attribute)
-    symbols = derive_symbols(function, inherited)
+                    inherited[instruction.result] = table.attribute(base, instruction.attribute)
+    symbols = derive_symbols(function, table, inherited)
     targets: dict[Value, Target] = {
         value: ExternalSymbol(symbol) for value, symbol in symbols.items()
     }
@@ -427,6 +428,7 @@ class CallGraphAnalysis(Analysis[CallGraph]):
                 owner,
                 _typed_with_module_classes(function, ssa, classes),
                 bases,
+                table=table,
             )
             defs = {i.result: i for block in ssa.blocks for i in block.instructions if i.result is not None}
             found: list[CallSite] = []

{coretrace_python_analyzer-0.11.0 → coretrace_python_analyzer-0.12.0}/src/coretrace_python/ir/lowering.py

@@ -141,7 +141,7 @@ class _FunctionLowerer:
             return self.symbols.resolve(self.scope.id, node.identifier)
         if isinstance(node, nodes.Attribute):
             parent = self.imported_symbol(node.value)
-            return parent.attribute(node.name) if parent is not None else None
+            return self.symbols.attribute(parent, node.name) if parent is not None else None
         return None
 
     def expression(self, node: nodes.Expression) -> Value:

coretrace_python_analyzer-0.12.0/src/coretrace_python/semantic/__init__.py

@@ -0,0 +1,9 @@
+"""Semantic analyses computed from PyHIR: scopes, imports and symbols."""
+
+from coretrace_python.semantic.imports import ImportAnalysis
+from coretrace_python.semantic.scopes import ScopeAnalysis
+from coretrace_python.semantic.symbols import MembersAnalysis, SymbolAnalysis
+
+SEMANTIC_ANALYSES = (ScopeAnalysis, ImportAnalysis, MembersAnalysis, SymbolAnalysis)
+
+__all__ = ["SEMANTIC_ANALYSES", "ImportAnalysis", "MembersAnalysis", "ScopeAnalysis", "SymbolAnalysis"]

coretrace_python_analyzer-0.12.0/src/coretrace_python/semantic/symbols.py

@@ -0,0 +1,177 @@
+"""Symbol analysis: resolve names to canonical identities (architecture §4.3)."""
+
+from __future__ import annotations
+
+import builtins
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import ClassVar
+
+from coretrace_python.analysis import Analysis, AnalysisContext, AnyAnalysis
+from coretrace_python.hir import nodes
+from coretrace_python.semantic.identity import SymbolId
+from coretrace_python.semantic.imports import ImportAnalysis, ImportTable
+from coretrace_python.semantic.scopes import ResolutionKind, ScopeAnalysis, ScopeId, ScopeTable
+
+BUILTIN_NAMES = frozenset(name for name in dir(builtins) if not name.startswith("_"))
+
+
+@dataclass(frozen=True)
+class Members:
+    """What the attributes and items of an instance of ``symbol`` give, for a class whose
+    instances give other objects by name, as a pymongo client gives the database it is
+    dotted or indexed with (``client.shop``, ``client['shop']``).
+
+    ``typed`` maps an attribute to the class of what it gives, called or not, since a
+    call denotes its callee: ``get_database`` gives a database, as a ``db`` property does.
+    ``dynamic``, when set, is the class of every item and of every attribute outside
+    ``defined`` and ``typed``. Otherwise an attribute keeps its path and an item its
+    container's symbol, as for any other class."""
+
+    symbol: SymbolId
+    dynamic: SymbolId | None = None
+    defined: tuple[str, ...] = ()
+    typed: tuple[tuple[str, SymbolId], ...] = ()
+
+    def __post_init__(self) -> None:
+        # Sorted: the models' repr is part of the cache key, the same in every process.
+        object.__setattr__(self, "defined", tuple(sorted(set(self.defined))))
+
+    def attribute(self, name: str) -> SymbolId:
+        for attribute, gives in self.typed:
+            if attribute == name:
+                return gives
+        if self.dynamic is not None and name not in self.defined:
+            return self.dynamic
+        return self.symbol.attribute(name)
+
+    def item(self) -> SymbolId:
+        return self.symbol if self.dynamic is None else self.dynamic
+
+
+class SymbolTable:
+    """Resolve names to canonical symbols through scopes, imports, builtins and the
+    module-level names bound to a value denoting a symbol (``app = Flask(__name__)``,
+    ``cursor = conn.cursor()``). ``members`` holds the ``Members`` models by class."""
+
+    def __init__(
+        self,
+        scopes: ScopeTable,
+        imports: ImportTable,
+        instances: Mapping[str, SymbolId] | None = None,
+        members: Mapping[SymbolId, Members] | None = None,
+    ) -> None:
+        self._scopes = scopes
+        self._imports = imports
+        self._instances = MappingProxyType(dict(instances or {}))
+        self._members = MappingProxyType(dict(members or {}))
+
+    def attribute(self, symbol: SymbolId, name: str) -> SymbolId:
+        """The symbol of attribute ``name`` of what ``symbol`` denotes: its path, unless
+        a ``Members`` model describes the class."""
+
+        members = self._members.get(symbol)
+        return symbol.attribute(name) if members is None else members.attribute(name)
+
+    def item(self, symbol: SymbolId) -> SymbolId:
+        """The symbol of an item of what ``symbol`` denotes: the container's own, so its
+        methods resolve (``request.files['f'].save``), unless a ``Members`` model says."""
+
+        members = self._members.get(symbol)
+        return symbol if members is None else members.item()
+
+    def resolve(self, scope_id: ScopeId, name: str) -> SymbolId | None:
+        resolution = self._scopes.resolve(scope_id, name)
+        if resolution.kind is ResolutionKind.UNBOUND:
+            return SymbolId(f"python.builtins.{name}") if name in BUILTIN_NAMES else None
+        assert resolution.scope is not None
+        imported = self._imports.bindings(resolution.scope).get(name)
+        if imported is not None:
+            return imported
+        if resolution.scope == self._scopes.module_scope.id:
+            return self._instances.get(name)
+        return None
+
+    def resolve_expression(self, scope_id: ScopeId, node: nodes.Expression) -> SymbolId | None:
+        """The symbol of a name or attribute chain, or of the callee of a call."""
+
+        if isinstance(node, nodes.Name):
+            return self.resolve(scope_id, node.identifier)
+        if isinstance(node, nodes.Attribute):
+            parent = self.resolve_expression(scope_id, node.value)
+            return self.attribute(parent, node.name) if parent is not None else None
+        if isinstance(node, nodes.Call):
+            return self.resolve_expression(scope_id, node.callee)
+        return None
+
+
+def analyze_symbols(
+    scopes: ScopeTable,
+    imports: ImportTable,
+    module: nodes.Module | None = None,
+    members: Mapping[SymbolId, Members] | None = None,
+) -> SymbolTable:
+    table = SymbolTable(scopes, imports, members=members)
+    if module is None:
+        return table
+    instances: dict[str, SymbolId] = {}
+    module_scope = scopes.module_scope.id
+    for statement in module.body:
+        if isinstance(statement, nodes.Assign) and isinstance(statement.target, nodes.Name):
+            symbol = _denoted(table, module_scope, statement.value)
+            if symbol is not None:
+                instances[statement.target.identifier] = symbol
+                # Later bindings resolve through this one, in statement order.
+                table = SymbolTable(scopes, imports, instances, members)
+    return table
+
+
+def _denoted(table: SymbolTable, scope_id: ScopeId, node: nodes.Expression) -> SymbolId | None:
+    """What a value denotes, as a function body derives it (``derive_symbols``): a
+    resolved name or an attribute of one, the result of calling one, or an item of one,
+    which carries its container's symbol (``os.environ['HOME']``) unless a ``Members``
+    model says what its items are."""
+
+    if isinstance(node, nodes.Subscript):
+        container = _denoted(table, scope_id, node.value)
+        return table.item(container) if container is not None else None
+    if isinstance(node, nodes.Attribute):
+        parent = _denoted(table, scope_id, node.value)
+        return table.attribute(parent, node.name) if parent is not None else None
+    if isinstance(node, nodes.Call):
+        return _denoted(table, scope_id, node.callee)
+    return table.resolve_expression(scope_id, node)
+
+
+class MembersAnalysis(Analysis[Mapping[SymbolId, Members]]):
+    """The ``Members`` models by class, provided by the engine from the security models;
+    none on its own, so every attribute keeps its path."""
+
+    name: ClassVar[str] = "semantic.members"
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext) -> Mapping[SymbolId, Members]:
+        return MappingProxyType({})
+
+
+class SymbolAnalysis(Analysis[SymbolTable]):
+    name: ClassVar[str] = "semantic.symbols"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({ScopeAnalysis, ImportAnalysis, MembersAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext) -> SymbolTable:
+        return analyze_symbols(
+            ctx.get(ScopeAnalysis), ctx.get(ImportAnalysis), ctx.module, ctx.get(MembersAnalysis)
+        )
+
+
+__all__ = [
+    "BUILTIN_NAMES",
+    "Members",
+    "MembersAnalysis",
+    "SymbolAnalysis",
+    "SymbolId",
+    "SymbolTable",
+    "analyze_symbols",
+]