coretrace-python-analyzer 0.21.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.21.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/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+from pathlib import PurePath
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.dependency import DependencyAnalysis
+from coretrace_python.dependency import Advisory, DependencyAnalysis, Requirement
 from coretrace_python.dependency.correlation import (
     affected_entries,
     affected_symbols,
@@ -44,11 +45,7 @@ class VulnerableDependencyPlugin(ProjectPlugin):
                 findings.append(
                     Finding(
                         rule_id="vulnerable-dependency",
-                        message=(
-                            f"{advisory.id}: {advisory.package} {advisory.vulnerable} is "
-                            f"{'required' if pinned else 'allowed'} by {requirement.name}"
-                            f"{requirement.specifier or ''}: {advisory.summary}"
-                        ),
+                        message=_message(ctx, advisory, requirement),
                         severity=advisory.severity,
                         confidence=Confidence.HIGH if pinned else Confidence.MEDIUM,
                         span=requirement.span,
@@ -58,6 +55,26 @@ class VulnerableDependencyPlugin(ProjectPlugin):
         return findings
 
 
+def _message(ctx: ProjectContext, advisory: Advisory, requirement: Requirement) -> str:
+    """The evidence: for a locked package, the version the lock file pins and the
+    packages that require it; for a declared requirement, the specifier that allows or
+    requires a vulnerable version."""
+
+    if requirement.locked is None:
+        verb = "required" if requirement.pinned is not None else "allowed"
+        return (
+            f"{advisory.id}: {advisory.package} {advisory.vulnerable} is {verb} by "
+            f"{requirement.name}{requirement.specifier or ''}: {advisory.summary}"
+        )
+    lock = PurePath(str(requirement.span.source_id)).name
+    dependents = sorted(ctx.dependencies.required_by(requirement.name) or ())
+    required = f" (required by {', '.join(dependents)})" if dependents else ""
+    return (
+        f"{advisory.id}: {advisory.package} {requirement.locked}, pinned in {lock}, "
+        f"is in {advisory.vulnerable}{required}: {advisory.summary}"
+    )
+
+
 def _ruled_out(ctx: ProjectContext) -> dict[str, list[str]]:
     """By advisory, the calls to its entry points whose arguments contradict one of its
     conditions: the evidence that the requirement, imported, is not reached there."""

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]