coretrace-python-analyzer 0.22.0__py3-none-any.whl → 0.24.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.24.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/dependency_policy/dependency_policy.py

@@ -2,17 +2,27 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.dependency import DependencyAnalysis
-from coretrace_python.findings import Confidence, Finding, Severity
+from coretrace_python.findings import Confidence, Finding, RuleDescription, Severity
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 
 
 class DependencyPolicyPlugin(ProjectPlugin):
     name: ClassVar[str] = "dependency-policy"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "denied-dependency": RuleDescription(
+            "Denied dependency",
+            "A requirement on a package the policy denies.",
+        ),
+        "unpinned-dependency": RuleDescription(
+            "Unpinned dependency",
+            "A requirement without an exact pin, when the policy requires pins.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py

@@ -4,7 +4,7 @@ template applies is a call to the function behind it, at the template's line."""
 
 from __future__ import annotations
 
-from collections.abc import Iterator, Sequence
+from collections.abc import Iterator, Mapping, Sequence
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
@@ -17,7 +17,7 @@ from coretrace_python.dependency.correlation import (
     evidence,
     suffix_index,
 )
-from coretrace_python.findings import Confidence, Finding
+from coretrace_python.findings import Confidence, Finding, RuleDescription
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 from coretrace_python.semantic.symbols import SymbolId
@@ -26,6 +26,12 @@ from coretrace_python.source import SourceSpan
 
 class ReachableVulnerabilityPlugin(ProjectPlugin):
     name: ClassVar[str] = "reachable-vulnerability"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "reachable-vulnerability": RuleDescription(
+            "Reachable dependency vulnerability",
+            "The project calls an API that an advisory of a vulnerable requirement affects.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from pathlib import PurePath
 from typing import ClassVar
 
@@ -15,13 +15,19 @@ from coretrace_python.dependency.correlation import (
     ruled_out,
     suffix_index,
 )
-from coretrace_python.findings import Confidence, Finding
+from coretrace_python.findings import Confidence, Finding, RuleDescription
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 
 
 class VulnerableDependencyPlugin(ProjectPlugin):
     name: ClassVar[str] = "vulnerable-dependency"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "vulnerable-dependency": RuleDescription(
+            "Vulnerable dependency",
+            "A requirement allows a version that an advisory affects.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

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,19 +1,107 @@
 """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 collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
-from coretrace_python.plugins import TaintDetector
-from coretrace_python.taint import TaintKind
+from coretrace_python.abstract.strings import ModuleStringsAnalysis, leading_text
+from coretrace_python.analysis import AnyAnalysis
+from coretrace_python.findings import RuleDescription, Severity
+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):
     name: ClassVar[str] = "code-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "code-injection": RuleDescription(
+            "Code injection",
+            "Attacker-controlled data chooses code that runs: the code eval or exec runs, the module an import loads, the script runpy runs, or the attribute getattr selects and the program calls.",
+        ),
+    }
     rule_id: ClassVar[str] = "code-injection"
     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/security/command_injection/command_injection.py

@@ -36,7 +36,7 @@ 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.findings import RuleDescription, Severity
 from coretrace_python.findings.refutation import Status, Verdict
 from coretrace_python.hir import nodes
 from coretrace_python.interprocedural import Arguments
@@ -398,6 +398,12 @@ class _Operands:
 
 class CommandInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "command-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "command-injection": RuleDescription(
+            "Command injection",
+            "Attacker-controlled data reaches a shell or process execution (os.system, subprocess, ...) where it can run or choose a command.",
+        ),
+    }
     rule_id: ClassVar[str] = "command-injection"
     kind: ClassVar[TaintKind] = TaintKind.COMMAND
     severity: ClassVar[Severity] = Severity.HIGH

coretrace_python/bundled/security/insecure_deserialization/insecure_deserialization.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class InsecureDeserializationPlugin(TaintDetector):
     name: ClassVar[str] = "insecure-deserialization"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "insecure-deserialization": RuleDescription(
+            "Insecure deserialization",
+            "Attacker-controlled data reaches a deserializer that can build arbitrary objects or run code: pickle, marshal, dill, jsonpickle, shelve, or a YAML loader without a safe loader.",
+        ),
+    }
     rule_id: ClassVar[str] = "insecure-deserialization"
     kind: ClassVar[TaintKind] = TaintKind.DESERIALIZATION
     severity: ClassVar[Severity] = Severity.CRITICAL

coretrace_python/bundled/security/nosql_injection/nosql_injection.py

@@ -5,15 +5,22 @@ sink; model plugins declare them."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class NoSqlInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "nosql-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "nosql-injection": RuleDescription(
+            "NoSQL injection",
+            "Attacker input that may hold a structure, such as a JSON body, reaches a NoSQL query, where an operator such as {\"$ne\": null} matches any value.",
+        ),
+    }
     rule_id: ClassVar[str] = "nosql-injection"
     kind: ClassVar[TaintKind] = TaintKind.NOSQL
     severity: ClassVar[Severity] = Severity.HIGH

coretrace_python/bundled/security/open_redirect/open_redirect.py

@@ -10,11 +10,12 @@ unproven, ``"/" + next`` included, stays a vulnerability.
 
 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 RuleDescription, Severity
 from coretrace_python.findings.refutation import Status, Verdict
 from coretrace_python.hir import nodes
 from coretrace_python.ir.ssa import SSAAnalysis
@@ -25,6 +26,12 @@ from coretrace_python.taint.urls import flow_url
 
 class OpenRedirectPlugin(TaintDetector):
     name: ClassVar[str] = "open-redirect"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "open-redirect": RuleDescription(
+            "Open redirect",
+            "Attacker-controlled data chooses the target of an HTTP redirect, which can send the user to another site.",
+        ),
+    }
     rule_id: ClassVar[str] = "open-redirect"
     kind: ClassVar[TaintKind] = TaintKind.REDIRECT
     severity: ClassVar[Severity] = Severity.MEDIUM

coretrace_python/bundled/security/path_traversal/path_traversal.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class PathTraversalPlugin(TaintDetector):
     name: ClassVar[str] = "path-traversal"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "path-traversal": RuleDescription(
+            "Path traversal",
+            "Attacker-controlled data reaches a file system path (open, send_file, os.remove, ...).",
+        ),
+    }
     rule_id: ClassVar[str] = "path-traversal"
     kind: ClassVar[TaintKind] = TaintKind.PATH
     severity: ClassVar[Severity] = Severity.HIGH

coretrace_python/bundled/security/plaintext_credentials/plaintext_credentials.py

@@ -5,15 +5,22 @@ a hint, so medium confidence."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Confidence, Severity
+from coretrace_python.findings import Confidence, RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class PlaintextCredentialsPlugin(TaintDetector):
     name: ClassVar[str] = "plaintext-credentials"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "plaintext-credential-storage": RuleDescription(
+            "Plaintext credential storage",
+            "A parameter named like a password is stored in a database without hashing.",
+        ),
+    }
     rule_id: ClassVar[str] = "plaintext-credential-storage"
     kind: ClassVar[TaintKind] = TaintKind.CREDENTIAL
     severity: ClassVar[Severity] = Severity.HIGH

coretrace_python/bundled/security/sql_injection/sql_injection.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class SqlInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "sql-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "sql-injection": RuleDescription(
+            "SQL injection",
+            "Attacker-controlled data reaches a database statement (cursor.execute, SQLAlchemy text, Django raw, ...) rather than a query parameter.",
+        ),
+    }
     rule_id: ClassVar[str] = "sql-injection"
     kind: ClassVar[TaintKind] = TaintKind.SQL
     severity: ClassVar[Severity] = Severity.HIGH