coretrace-python-analyzer 0.22.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

coretrace_python/__init__.py

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

coretrace_python/abstract/module_constants.py

@@ -0,0 +1,121 @@
+"""Module-level names whose value is known (architecture §18): the names bound once and
+never rebound, and among them the ones bound to an immutable collection of constants,
+which an allowlist reads."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import ClassVar
+
+from coretrace_python.analysis import Analysis, AnalysisContext, AnyAnalysis
+from coretrace_python.cfg import CFGError
+from coretrace_python.hir import nodes
+from coretrace_python.ir.lowering import (
+    MODULE_BODY,
+    LoweringError,
+    PyIRAnalysis,
+    analyzable_functions,
+)
+from coretrace_python.ir.model import (
+    BuildDict,
+    BuildList,
+    BuildSet,
+    BuildTuple,
+    Call,
+    Constant,
+    ForNext,
+    Instruction,
+    SetGlobal,
+    StoreLocal,
+    Symbol,
+    Value,
+)
+from coretrace_python.semantic.symbols import SymbolId
+
+FROZENSET = SymbolId("python.builtins.frozenset")
+
+
+def module_bindings(ctx: AnalysisContext) -> tuple[Mapping[str, Instruction], Mapping[Value, Instruction]]:
+    """The module-level names bound once and never rebound, by no other statement of the
+    module body, no function assigning them as ``global``, no definition of that name,
+    each with the instruction that makes its value; and the definitions of the module
+    body's values. A module that does not lower entirely has none."""
+
+    try:
+        functions = [ctx.get(PyIRAnalysis, function) for function in analyzable_functions(ctx.module)]
+    except (LoweringError, CFGError):
+        return MappingProxyType({}), MappingProxyType({})
+    body = next((function for function in functions if function.name == MODULE_BODY), None)
+    if body is None:
+        return MappingProxyType({}), MappingProxyType({})
+    defs = {i.result: i for block in body.blocks for i in block.instructions if i.result is not None}
+    stored: dict[str, list[Value | None]] = {}
+    for block in body.blocks:
+        for instruction in block.instructions:
+            if isinstance(instruction, StoreLocal):
+                stored.setdefault(instruction.name, []).append(instruction.value)
+        if isinstance(block.terminator, ForNext):
+            # A ``for`` binds its target to each item.
+            stored.setdefault(block.terminator.target, []).append(None)
+    rebound = {
+        i.name for function in functions for block in function.blocks for i in block.instructions
+        if isinstance(i, SetGlobal)
+    }
+    rebound |= {s.name for s in ctx.module.body if isinstance(s, nodes.Function | nodes.Class)}
+    bound: dict[str, Instruction] = {}
+    for name, values in stored.items():
+        value = values[0] if len(values) == 1 and name not in rebound else None
+        made = defs.get(value) if value is not None else None
+        if made is not None:
+            bound[name] = made
+    return MappingProxyType(bound), MappingProxyType(defs)
+
+
+def constant_members(display: Instruction | None, defs: Mapping[Value, Instruction]) -> bool:
+    """Whether ``display`` is a tuple, list or set display whose items are all constants,
+    or a dict display whose keys are, with nothing unpacked into it: the members a
+    membership test reads."""
+
+    if isinstance(display, BuildList | BuildTuple | BuildSet):
+        return not display.unpacked and all(isinstance(defs.get(e), Constant) for e in display.elements)
+    if isinstance(display, BuildDict):
+        return not display.unpacked and all(isinstance(defs.get(key), Constant) for key, _ in display.items)
+    return False
+
+
+def converts(call: Call, defs: Mapping[Value, Instruction], symbols: frozenset[SymbolId]) -> Value | None:
+    """The one positional argument of ``call`` when it calls one of ``symbols`` with
+    nothing else (``frozenset(x)``), otherwise ``None``."""
+
+    callee = defs.get(call.callee)
+    if not isinstance(callee, Symbol) or callee.symbol_id not in symbols:
+        return None
+    if len(call.arguments) != 1 or call.keywords or call.starred:
+        return None
+    return call.arguments[0]
+
+
+class ModuleCollectionsAnalysis(Analysis[frozenset[str]]):
+    """The module-level names bound once and never rebound (``module_bindings``) to an
+    immutable collection of constants: a tuple display, or ``frozenset`` of a display
+    whose members are constants (``constant_members``). A list, a set or a dict can still
+    change after it is bound, so it is not one."""
+
+    name: ClassVar[str] = "abstract.module_collections"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({PyIRAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext) -> frozenset[str]:
+        bound, defs = module_bindings(ctx)
+        found: set[str] = set()
+        for name, made in bound.items():
+            collection: Instruction | None = made
+            if isinstance(made, Call):
+                argument = converts(made, defs, frozenset({FROZENSET}))
+                collection = defs.get(argument) if argument is not None else None
+            elif not isinstance(made, BuildTuple):
+                continue
+            if constant_members(collection, defs):
+                found.add(name)
+        return frozenset(found)

coretrace_python/abstract/strings.py

@@ -9,24 +9,15 @@ from collections.abc import Mapping
 from types import MappingProxyType
 from typing import ClassVar
 
+from coretrace_python.abstract.module_constants import module_bindings
 from coretrace_python.analysis import Analysis, AnalysisContext, AnyAnalysis
-from coretrace_python.cfg import CFGError
-from coretrace_python.hir import nodes
-from coretrace_python.ir.lowering import (
-    MODULE_BODY,
-    LoweringError,
-    PyIRAnalysis,
-    analyzable_functions,
-)
+from coretrace_python.ir.lowering import PyIRAnalysis
 from coretrace_python.ir.model import (
     BinaryOp,
     BuildString,
     Constant,
-    ForNext,
     Global,
     Instruction,
-    SetGlobal,
-    StoreLocal,
     Value,
 )
 
@@ -59,40 +50,19 @@ def leading_text(value: Value, defs: Mapping[Value, Instruction], strings: Mappi
 
 
 class ModuleStringsAnalysis(Analysis[Mapping[str, str]]):
-    """The module-level names bound once, to a string literal, and never rebound: by no
-    other statement of the module body, no function assigning them as ``global``, no
-    definition of that name. A module that does not lower entirely has none."""
+    """The module-level names bound once and never rebound (``module_bindings``) to a
+    string literal, with that literal."""
 
     name: ClassVar[str] = "abstract.module_strings"
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({PyIRAnalysis})
 
     @classmethod
     def compute(cls, ctx: AnalysisContext) -> Mapping[str, str]:
-        try:
-            functions = [ctx.get(PyIRAnalysis, function) for function in analyzable_functions(ctx.module)]
-        except (LoweringError, CFGError):
-            return MappingProxyType({})
-        body = next((function for function in functions if function.name == MODULE_BODY), None)
-        if body is None:
-            return MappingProxyType({})
-        defs = {i.result: i for block in body.blocks for i in block.instructions if i.result is not None}
-        stored: dict[str, list[Value | None]] = {}
-        for block in body.blocks:
-            for instruction in block.instructions:
-                if isinstance(instruction, StoreLocal):
-                    stored.setdefault(instruction.name, []).append(instruction.value)
-            if isinstance(block.terminator, ForNext):
-                # A ``for`` binds its target to each item.
-                stored.setdefault(block.terminator.target, []).append(None)
-        rebound = {
-            i.name for function in functions for block in function.blocks for i in block.instructions
-            if isinstance(i, SetGlobal)
-        }
-        rebound |= {s.name for s in ctx.module.body if isinstance(s, nodes.Function | nodes.Class)}
-        found: dict[str, str] = {}
-        for name, values in stored.items():
-            value = values[0] if len(values) == 1 and name not in rebound else None
-            made = defs.get(value) if value is not None else None
-            if isinstance(made, Constant) and isinstance(made.value, str):
-                found[name] = made.value
-        return MappingProxyType(found)
+        bound, _ = module_bindings(ctx)
+        return MappingProxyType(
+            {
+                name: made.value
+                for name, made in bound.items()
+                if isinstance(made, Constant) and isinstance(made.value, str)
+            }
+        )

coretrace_python/bundled/models/python_stdlib/python_stdlib.py

@@ -62,6 +62,33 @@ class PythonStdlibModels(ModelPlugin):
         # The code is the first argument; the globals and locals it runs with are data.
         Sink(_sym("builtins.eval"), TaintKind.CODE, ((TaintKind.CODE, (0,)),)),
         Sink(_sym("builtins.exec"), TaintKind.CODE, ((TaintKind.CODE, (0,)),)),
+        # The module or the file the call imports or runs; its globals, its run name and
+        # the package of a relative name are data (#240).
+        *(
+            Sink(_sym(symbol), TaintKind.CODE, ((TaintKind.CODE, (0,)),), ((TaintKind.CODE, (keyword,)),), selects=True)
+            for symbol, keyword in (
+                ("importlib.import_module", "name"),
+                ("builtins.__import__", "name"),
+                ("importlib.__import__", "name"),
+                ("runpy.run_module", "mod_name"),
+                ("runpy.run_path", "path_name"),
+            )
+        ),
+        # The directory imports are looked up in, and the site directory whose ``.pth``
+        # files run; the index of ``insert`` is data (#240).
+        Sink(_sym("sys.path.insert"), TaintKind.CODE, ((TaintKind.CODE, (1,)),), selects=True),
+        Sink(_sym("sys.path.append"), TaintKind.CODE, ((TaintKind.CODE, (0,)),), selects=True),
+        Sink(_sym("sys.path.extend"), TaintKind.CODE, ((TaintKind.CODE, (0,)),), selects=True),
+        Sink(_sym("site.addsitedir"), TaintKind.CODE, ((TaintKind.CODE, (0,)),), ((TaintKind.CODE, ("sitedir",)),), selects=True),
+        # The name of the attribute ``getattr`` selects, when what it selects is called;
+        # the object and the default are data (#240).
+        Sink(
+            _sym("builtins.getattr"),
+            TaintKind.CODE,
+            ((TaintKind.CODE, (1,)),),
+            selects=True,
+            requires_called_result=TaintKind.CODE,
+        ),
         Sink(_sym("builtins.open"), TaintKind.PATH),
         Sink(_sym("os.remove"), TaintKind.PATH),
         Sink(_sym("os.unlink"), TaintKind.PATH),

coretrace_python/bundled/secrets/config_secrets/config_secrets.py

@@ -9,6 +9,7 @@ from collections.abc import Sequence
 from typing import ClassVar
 
 from coretrace_python.findings import Finding
+from coretrace_python.findings.context import path_in_project
 from coretrace_python.plugins import PluginContext, ProjectContext, ProjectPlugin
 from coretrace_python.plugins.secrets import (
     DEFAULT_CREDENTIAL_NAMES,
@@ -32,7 +33,7 @@ class ConfigSecrets(SecretDetector, ProjectPlugin):
             return ()
         findings: list[Finding] = []
         for value, name, span, function in config_literals(ctx.root):
-            finding = self.judge(value, name, span, function)
+            finding = self.judge(value, name, span, function, path=path_in_project(span.source_id, ctx.root))
             if finding is not None:
                 findings.append(finding)
         return findings

coretrace_python/bundled/security/code_injection/code_injection.py

@@ -1,14 +1,43 @@
 """Code injection: attacker-controlled input reaching a CODE sink, such as the code
-``eval`` or ``exec`` runs. ``dangerous-eval`` reports every such call; this rule reports
-the ones attacker input reaches."""
+``eval`` or ``exec`` runs, the module ``importlib.import_module``, ``__import__`` or
+``runpy.run_module`` imports, the file ``runpy.run_path`` runs, the directory
+``sys.path`` and ``site.addsitedir`` load code from, or the attribute ``getattr`` selects
+when it is called. ``dangerous-eval`` reports every ``eval`` or ``exec``; this rule reports
+the calls attacker input reaches.
+
+An import runs the top-level code of a module the input chooses among those that can be
+found, and a script path runs the file the input chooses: execution is possible, and
+how far it goes depends on what the input can reach. Their findings are titled for
+that. A constant package prefix (``"app.plugins." + name``) confines an import to the
+modules of that package: a hotspot. A directory added to ``sys.path`` runs code only
+when a later import resolves there: a hotspot. ``site.addsitedir`` runs the import lines
+of the directory's ``.pth`` files during the call: a vulnerability, exploitable when the
+directory holds files the attacker controls, as the finding states. The attribute
+``getattr`` selects runs at each call of its result, where the finding is placed: what
+runs depends on what the object exposes, a hotspot."""
 
 from __future__ import annotations
 
 from typing import ClassVar
 
+from coretrace_python.abstract.strings import ModuleStringsAnalysis, leading_text
+from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.findings import Severity
-from coretrace_python.plugins import TaintDetector
-from coretrace_python.taint import TaintKind
+from coretrace_python.findings.refutation import Status, Verdict
+from coretrace_python.hir import nodes
+from coretrace_python.ir.ssa import SSAAnalysis
+from coretrace_python.plugins import Assessment, PluginContext, TaintDetector
+from coretrace_python.semantic.symbols import SymbolId
+from coretrace_python.taint import TaintFlow, TaintKind
+
+_IMPORTS = frozenset(
+    SymbolId(f"python.{name}")
+    for name in ("importlib.import_module", "builtins.__import__", "importlib.__import__", "runpy.run_module")
+)
+_RUN_PATH = SymbolId("python.runpy.run_path")
+_IMPORT_PATHS = frozenset(SymbolId(f"python.sys.path.{name}") for name in ("insert", "append", "extend"))
+_SITE_DIRECTORY = SymbolId("python.site.addsitedir")
+_GETATTR = SymbolId("python.builtins.getattr")
 
 
 class CodeInjectionPlugin(TaintDetector):
@@ -17,3 +46,55 @@ class CodeInjectionPlugin(TaintDetector):
     kind: ClassVar[TaintKind] = TaintKind.CODE
     severity: ClassVar[Severity] = Severity.HIGH
     title: ClassVar[str] = "Code injection"
+    requires: ClassVar[frozenset[AnyAnalysis]] = TaintDetector.requires | {SSAAnalysis, ModuleStringsAnalysis}
+
+    def assess(
+        self, ctx: PluginContext, function: nodes.Function, flow: TaintFlow, verdict: Verdict
+    ) -> Assessment:
+        symbol = flow.sink.symbol
+        if symbol == _RUN_PATH:
+            return Assessment(verdict, self.severity, "Untrusted script execution")
+        if symbol in _IMPORT_PATHS:
+            if verdict.status is Status.VULNERABILITY:
+                verdict = Verdict(
+                    flow,
+                    Status.HOTSPOT,
+                    "the input chooses a directory imports are looked up in: code runs only when a later "
+                    "import resolves to a module the attacker placed there",
+                )
+            return Assessment(verdict, self.severity, "Untrusted import path")
+        if symbol == _GETATTR:
+            if verdict.status is Status.VULNERABILITY:
+                verdict = Verdict(
+                    flow,
+                    Status.HOTSPOT,
+                    "the input chooses the attribute called: what runs depends on what the object exposes",
+                )
+            lines: dict[str, str] = {}
+            if flow.invoked_at is not None and flow.sink_location is not None:
+                lines = {
+                    "selected_line": str(flow.sink_location.start_line),
+                    "invoked_line": str(flow.invoked_at.start_line),
+                }
+            return Assessment(verdict, self.severity, "Untrusted attribute call", lines)
+        if symbol == _SITE_DIRECTORY:
+            if verdict.status is Status.VULNERABILITY:
+                verdict = Verdict(
+                    flow,
+                    Status.VULNERABILITY,
+                    f"{verdict.evidence}; the import lines of the .pth files of the directory run during the "
+                    "call: exploitable when the input chooses a directory holding files the attacker controls",
+                )
+            return Assessment(verdict, self.severity, "Untrusted site directory")
+        if symbol not in _IMPORTS:
+            return Assessment(verdict, self.severity)
+        if verdict.status is Status.VULNERABILITY and flow.through is None:
+            ssa = ctx.get(SSAAnalysis, function)
+            defs = {i.result: i for block in ssa.blocks for i in block.instructions if i.result is not None}
+            prefix, whole = leading_text(flow.argument, defs, ctx.get(ModuleStringsAnalysis))
+            package = prefix.rpartition(".")[0]
+            if not whole and package and not prefix.startswith("."):
+                verdict = Verdict(
+                    flow, Status.HOTSPOT, f"the package is fixed by {prefix!r}, but the input chooses a module in it"
+                )
+        return Assessment(verdict, self.severity, "Untrusted module import")

coretrace_python/bundled/security/code_injection/plugin.toml

@@ -1,7 +1,7 @@
 name = "code-injection"
 version = "1.0.0"
 plugin_api = ">=1,<2"
-requires = ["taint.flows", "findings.refutation"]
+requires = ["taint.flows", "findings.refutation", "ir.ssa", "abstract.module_strings"]
 provides = ["vulnerability.code-injection"]
 
 [entrypoint]

coretrace_python/bundled/syntax/unsafe_xml/plugin.toml

@@ -1,7 +1,7 @@
 name = "unsafe-xml"
 version = "1.0.0"
 plugin_api = ">=1,<2"
-requires = ["interprocedural.callgraph", "ir.ssa"]
+requires = ["interprocedural.callgraph", "ir.ssa", "abstract.module_strings"]
 provides = ["vulnerability.unsafe-xml"]
 
 [entrypoint]

coretrace_python/bundled/syntax/unsafe_xml/unsafe_xml.py

@@ -1,35 +1,115 @@
-"""XML parsers of the standard library and lxml expand entities: a crafted document reads
-local files or exhausts memory. ``defusedxml`` offers the same functions safely."""
+"""XML parsers of the standard library and of lxml, each reported for what it risks.
+
+The standard library's parsers run on Expat, which never reads a local file or opens a
+connection, but expands the entities a document declares: a crafted document can exhaust
+memory with Expat older than 2.7.2, a fact of run time (``pyexpat.EXPAT_VERSION``). lxml
+resolves external entities by default before 5.0, and in ``iterparse`` and
+``ETCompatXMLParser`` before 6.1 (CVE-2026-41066), which lets a crafted document read
+local files; ``resolve_entities=True`` does so whatever the version, ``False`` never.
+``'internal'`` keeps external entities out only from lxml 5.0 on: an earlier lxml reads
+the string as true. ``defusedxml`` offers the same functions safely. XML content the
+project wrote itself, a string constant or a module-level string bound once given to a
+function that parses its argument as the document, is no attacker's: its finding is kept
+at low confidence. A path is not the document: whoever can write the file chooses it."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
+from coretrace_python.abstract.strings import ModuleStringsAnalysis
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.findings import Severity
+from coretrace_python.findings import Confidence, Severity
 from coretrace_python.interprocedural import CallGraphAnalysis
+from coretrace_python.ir.model import Call, Constant, Global, Instruction, Value
 from coretrace_python.ir.ssa import SSAAnalysis
-from coretrace_python.plugins import SymbolCallDetector
+from coretrace_python.plugins import CallReport, PluginContext, SymbolCallDetector
 from coretrace_python.semantic.symbols import SymbolId
 
-_PARSERS = (
+
+def _symbols(*paths: str) -> frozenset[SymbolId]:
+    return frozenset(SymbolId(f"python.{path}") for path in paths)
+
+
+_STANDARD_LIBRARY = _symbols(
     "xml.etree.ElementTree.parse", "xml.etree.ElementTree.fromstring", "xml.etree.ElementTree.iterparse",
     "xml.etree.ElementTree.XMLParser", "xml.etree.ElementTree.fromstringlist",
     "xml.dom.minidom.parse", "xml.dom.minidom.parseString",
     "xml.dom.pulldom.parse", "xml.dom.pulldom.parseString",
     "xml.sax.parse", "xml.sax.parseString", "xml.sax.make_parser",
     "xml.dom.expatbuilder.parse", "xml.dom.expatbuilder.parseString",
-    "lxml.etree.parse", "lxml.etree.fromstring", "lxml.etree.XMLParser", "lxml.etree.iterparse",
-    "lxml.etree.XML",
 )
+_LXML = _symbols("lxml.etree.parse", "lxml.etree.fromstring", "lxml.etree.XMLParser", "lxml.etree.XML")
+# Their default kept ``resolve_entities=True`` until lxml 6.1 (CVE-2026-41066).
+_LXML_UNTIL_6_1 = _symbols("lxml.etree.iterparse", "lxml.etree.ETCompatXMLParser")
+# The functions whose first argument is the XML itself, not a file, a URL or a stream.
+_CONTENT = _symbols(
+    "xml.etree.ElementTree.fromstring", "xml.etree.ElementTree.fromstringlist",
+    "xml.dom.minidom.parseString", "xml.dom.pulldom.parseString", "xml.sax.parseString",
+    "xml.dom.expatbuilder.parseString", "lxml.etree.fromstring", "lxml.etree.XML",
+)
+# A keyword that is not a constant: its value is unknown.
+_UNKNOWN = object()
+
+
+def _resolve_entities(call: Call, defs: Mapping[Value, Instruction]) -> object:
+    """The constant ``resolve_entities=`` of ``call``, ``None`` when it is not passed."""
+
+    for name, value in call.keywords:
+        if name == "resolve_entities":
+            made = defs.get(value)
+            return made.value if isinstance(made, Constant) else _UNKNOWN
+    return None
 
 
 class UnsafeXmlPlugin(SymbolCallDetector):
     name: ClassVar[str] = "unsafe-xml"
     rule_id: ClassVar[str] = "unsafe-xml"
-    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
-    symbols: ClassVar[frozenset[SymbolId]] = frozenset(SymbolId(f"python.{p}") for p in _PARSERS)
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis, ModuleStringsAnalysis})
+    symbols: ClassVar[frozenset[SymbolId]] = _STANDARD_LIBRARY | _LXML | _LXML_UNTIL_6_1
     severity: ClassVar[Severity] = Severity.MEDIUM
-    message_template: ClassVar[str] = (
-        "call to {symbol} parses XML with entity expansion enabled; use defusedxml"
-    )
+    message_template: ClassVar[str] = "call to {symbol} parses XML unsafely; use defusedxml"
+
+    def accepts(self, call: Call, symbol: SymbolId, defs: Mapping[Value, Instruction]) -> bool:
+        # ``resolve_entities`` is an lxml option; the standard library has none.
+        return _resolve_entities(call, defs) is not False
+
+    def describe(
+        self, ctx: PluginContext, call: Call, symbol: SymbolId, defs: Mapping[Value, Instruction]
+    ) -> CallReport:
+        if symbol in _STANDARD_LIBRARY:
+            risk = "expands the entities a document declares, which can exhaust memory with Expat older than 2.7.2"
+            advice = "use defusedxml"
+        elif _resolve_entities(call, defs) is True:
+            risk = "resolves external entities (resolve_entities=True), which lets a crafted document read local files"
+            advice = "use defusedxml"
+        elif _resolve_entities(call, defs) == "internal":
+            risk = (
+                "sets resolve_entities='internal', which keeps external entities out only from lxml 5.0 on: "
+                "before lxml 5.0 the string reads as true and external entities are resolved, which lets a "
+                "crafted document read local files"
+            )
+            advice = "use defusedxml or resolve_entities=False"
+        elif symbol in _LXML_UNTIL_6_1:
+            risk = (
+                "resolves external entities by default before lxml 6.1 (CVE-2026-41066), "
+                "which lets a crafted document read local files"
+            )
+            advice = "use defusedxml or resolve_entities=False"
+        else:
+            risk = "resolves external entities by default before lxml 5.0, which lets a crafted document read local files"
+            advice = "use defusedxml"
+        written = symbol in _CONTENT and self.written_by_the_project(ctx, call, defs)
+        confidence = Confidence.LOW if written else self.confidence
+        return CallReport(f"call to {symbol} {risk}; {advice}", confidence)
+
+    def written_by_the_project(self, ctx: PluginContext, call: Call, defs: Mapping[Value, Instruction]) -> bool:
+        """Whether the first argument of ``call``, which a ``_CONTENT`` function parses as
+        the document, is a string constant or a module-level name bound once to one."""
+
+        if not call.arguments:
+            return False
+        made = defs.get(call.arguments[0])
+        if isinstance(made, Constant):
+            return isinstance(made.value, str | bytes)
+        return isinstance(made, Global) and made.name in ctx.get(ModuleStringsAnalysis)

coretrace_python/cache.py

@@ -35,7 +35,6 @@ from coretrace_python.interprocedural import (
     Mutation,
     NonlocalWrite,
     PriorCall,
-    SummaryIndex,
     SymbolRead,
     Target,
     UnknownTarget,
@@ -43,7 +42,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import FileLocation, Location, SourceId, SourceSpan
 
-CACHE_FORMAT = 14
+CACHE_FORMAT = 16
 
 
 @dataclass(frozen=True)
@@ -155,16 +154,6 @@ def decode(data: Mapping[str, Any]) -> CachedModule:
     )
 
 
-def encode_index(index: SummaryIndex) -> dict[str, Any]:
-    """A summary index as plain data, to hand a worker process what it imports."""
-
-    return {str(symbol): _encode_summary(index.summaries[symbol]) for symbol in index.symbols}
-
-
-def decode_index(data: Mapping[str, Any]) -> SummaryIndex:
-    return SummaryIndex({SymbolId(_string(k)): _decode_summary(v) for k, v in data.items()})
-
-
 def _string(value: Any) -> str:
     if not isinstance(value, str):
         raise TypeError(f"expected a string, got {value!r}")
@@ -264,11 +253,13 @@ def _encode_call(call: ExternalCall) -> dict[str, Any]:
         "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],
+        "invoked_at": None if call.invoked_at is None else _encode_span(call.invoked_at),
     }
 
 
 def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
     site = data["call_site"]
+    invoked_at = data["invoked_at"]
     return ExternalCall(
         SymbolId(_string(data["symbol"])),
         tuple(_indices(deps) for deps in data["arguments"]),
@@ -278,6 +269,7 @@ def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
         _decode_arguments(data["given"]),
         tuple(_decode_cleared(c) for c in data["argument_cleared"]),
         tuple(_decode_cleared(c) for c in data["keyword_cleared"]),
+        None if invoked_at is None else _decode_span(invoked_at),
     )
 
 
@@ -308,7 +300,12 @@ def _encode_summary(summary: FunctionSummary) -> dict[str, Any]:
         ],
         "side_effects": sorted(summary.side_effects),
         "nonlocal_writes": [
-            {"name": w.name, "dependencies": sorted(w.dependencies), "externals": sorted(str(s) for s in w.externals)}
+            {
+                "name": w.name,
+                "dependencies": sorted(w.dependencies),
+                "externals": sorted(str(s) for s in w.externals),
+                "kept": w.kept,
+            }
             for w in summary.nonlocal_writes
         ],
         "static": summary.static,
@@ -336,7 +333,10 @@ def _decode_summary(data: Mapping[str, Any]) -> FunctionSummary:
         frozenset(_string(name) for name in data["side_effects"]),
         tuple(
             NonlocalWrite(
-                _string(w["name"]), _indices(w["dependencies"]), frozenset(SymbolId(_string(s)) for s in w["externals"])
+                _string(w["name"]),
+                _indices(w["dependencies"]),
+                frozenset(SymbolId(_string(s)) for s in w["externals"]),
+                bool(w["kept"]),
             )
             for w in data["nonlocal_writes"]
         ),

coretrace_python/cli.py

@@ -109,11 +109,13 @@ def build_parser() -> argparse.ArgumentParser:
         "them for modules unchanged since the previous run",
     )
     parser.add_argument(
+        "-j",
         "--jobs",
         type=int,
         default=None,
         metavar="N",
-        help="with --check on a directory, analyse independent modules in N processes",
+        help="with --check on a directory, analyse independent modules in N processes, "
+        "0 for one per available core; default: 1",
     )
     parser.add_argument(
         "--sbom",
@@ -214,8 +216,8 @@ def main(argv: list[str] | None = None) -> int:
     if args.jobs is not None and not (args.check and args.path.is_dir()):
         print("error: --jobs only applies to --check on a directory", file=sys.stderr)
         return EXIT_ERROR
-    if args.jobs is not None and args.jobs < 1:
-        print("error: --jobs must be at least 1", file=sys.stderr)
+    if args.jobs is not None and args.jobs < 0:
+        print("error: --jobs must be 0 (one per available core) or more", file=sys.stderr)
         return EXIT_ERROR
     if args.sbom is not None and not (args.check and args.path.is_dir()):
         print("error: --sbom only applies to --check on a directory", file=sys.stderr)
@@ -270,7 +272,7 @@ def main(argv: list[str] | None = None) -> int:
                     args.path,
                     plugin_roots,
                     cache=cache,
-                    jobs=args.jobs or 1,
+                    jobs=_processes(args.jobs),
                     advisory_files=args.advisories,
                     policy_file=args.policy,
                 )
@@ -301,7 +303,7 @@ def main(argv: list[str] | None = None) -> int:
                         encoding="utf-8",
                     )
             else:
-                file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots)
+                file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots, root)
                 findings, coverage = file_analysis.findings, file_analysis.coverage
                 suppressed = file_analysis.suppressed
                 components = ()
@@ -331,5 +333,31 @@ def main(argv: list[str] | None = None) -> int:
     return EXIT_CLEAN
 
 
+def _processes(jobs: int | None) -> int:
+    """The number of processes ``--jobs`` asks for: 0 is one per core the process may run
+    on, as ``runtime.jobs`` of ``ctrace``; none is one."""
+
+    if jobs is None:
+        return 1
+    if jobs == 0:
+        return _available_cores()
+    return jobs
+
+
+def _available_cores() -> int:
+    """The cores the process may run on, where Python can tell its affinity
+    (``os.process_cpu_count`` from 3.13, ``os.sched_getaffinity`` on Linux before), else
+    the cores of the machine."""
+
+    process_cpu_count = getattr(os, "process_cpu_count", None)
+    if process_cpu_count is not None:
+        cores: int | None = process_cpu_count()
+    elif hasattr(os, "sched_getaffinity"):
+        cores = len(os.sched_getaffinity(0))
+    else:
+        cores = os.cpu_count()
+    return cores or 1
+
+
 if __name__ == "__main__":
     raise SystemExit(main())