coretrace-python-analyzer 0.1.0__py3-none-any.whl

coretrace_python/abstract/ranges.py

@@ -0,0 +1,285 @@
+"""Numeric range analysis (architecture §18, §24).
+
+Every value proven numeric gets an ``Interval``: numeric constants, arithmetic on
+numbers, the results of ``int()``, ``len()`` and friends. Comparisons refine the
+intervals of both sides on the branch they take, chained comparisons and ``and`` / ``or``
+included, and loops converge by widening. Values not proven numeric have no interval:
+the domain doubles as a proof of numeric type, which is what the refutation engine
+needs, since a number cannot carry an injection.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import ClassVar
+
+from coretrace_python.analysis import AnalysisContext, AnyAnalysis, FunctionAnalysis
+from coretrace_python.cfg import CFG, BlockId, CFGAnalysis
+from coretrace_python.dataflow import DataflowProblem, Direction, solve
+from coretrace_python.hir import nodes
+from coretrace_python.ir.model import (
+    BasicBlock,
+    BinaryOp,
+    BoolOp,
+    Branch,
+    Call,
+    Compare,
+    Constant,
+    ForNext,
+    FunctionIR,
+    Instruction,
+    Jump,
+    Phi,
+    Symbol,
+    UnaryOp,
+    Value,
+)
+from coretrace_python.ir.ssa import SSAAnalysis
+
+INF = float("inf")
+
+
+def _format(bound: float) -> str:
+    if bound in (INF, -INF):
+        return "inf" if bound > 0 else "-inf"
+    return str(int(bound)) if float(bound).is_integer() else str(bound)
+
+
+@dataclass(frozen=True)
+class Interval:
+    """A closed range of numbers; ``inf`` bounds mean unbounded."""
+
+    low: float
+    high: float
+
+    def join(self, other: Interval) -> Interval:
+        return Interval(min(self.low, other.low), max(self.high, other.high))
+
+    def widen(self, other: Interval) -> Interval:
+        """``self`` extended to ``other``, jumping to infinity on any side that grew."""
+
+        return Interval(
+            self.low if other.low >= self.low else -INF,
+            self.high if other.high <= self.high else INF,
+        )
+
+    def __str__(self) -> str:
+        return f"[{_format(self.low)}, {_format(self.high)}]"
+
+
+UNBOUNDED = Interval(-INF, INF)
+NON_NEGATIVE = Interval(0, INF)
+
+_NUMERIC_CALLS: Mapping[str, Interval] = {
+    "python.builtins.int": UNBOUNDED,
+    "python.builtins.float": UNBOUNDED,
+    "python.builtins.round": UNBOUNDED,
+    "python.builtins.len": NON_NEGATIVE,
+    "python.builtins.abs": NON_NEGATIVE,
+    "python.builtins.ord": Interval(0, 0x10FFFF),
+}
+_HULL_CALLS = frozenset({"python.builtins.min", "python.builtins.max"})
+
+State = Mapping[Value, Interval]
+
+
+def _times(a: float, b: float) -> float:
+    return 0.0 if a == 0 or b == 0 else a * b
+
+
+class RangeFacts:
+    def __init__(self, states: Mapping[BlockId, State]) -> None:
+        self._states: Mapping[BlockId, State] = MappingProxyType(
+            {block: MappingProxyType(dict(state)) for block, state in states.items()}
+        )
+
+    def at(self, block: BlockId) -> State:
+        """The intervals known at the end of ``block``; empty when it is unreachable."""
+
+        return self._states.get(block, MappingProxyType({}))
+
+
+class _RangeProblem(DataflowProblem[State]):
+    direction: ClassVar[Direction] = Direction.FORWARD
+
+    def __init__(self, function: FunctionIR) -> None:
+        self.function = function
+        self.blocks = {block.id: block for block in function.blocks}
+        self.defs: dict[Value, Instruction] = {
+            i.result: i for block in function.blocks for i in block.instructions if i.result
+        }
+        self._widened: dict[Value, Interval] = {}
+
+    def initial(self) -> State:
+        return MappingProxyType({})
+
+    def join(self, a: State, b: State) -> State:
+        return MappingProxyType(
+            {value: a[value].join(b[value]) for value in a if value in b}
+        )
+
+    def evaluate(self, block: BasicBlock, incoming: Mapping[BlockId, State]) -> State:
+        states = list(incoming.values())
+        state: dict[Value, Interval] = dict(states[0]) if states else {}
+        for other in states[1:]:
+            state = dict(self.join(state, other))
+        for instruction in block.instructions:
+            if instruction.result is None:
+                continue
+            found = (
+                self.phi(instruction, incoming)
+                if isinstance(instruction, Phi)
+                else self.instruction(instruction, state)
+            )
+            if found is None:
+                state.pop(instruction.result, None)
+            else:
+                state[instruction.result] = found
+        return MappingProxyType(state)
+
+    def flow(self, cfg: CFG, block_id: BlockId, incoming: Mapping[BlockId, State]) -> Mapping[BlockId, State]:
+        block = self.blocks[block_id]
+        state = self.evaluate(block, incoming)
+        exits = {target: state for target in block.exception_targets}
+        terminator = block.terminator
+        if isinstance(terminator, Branch):
+            return {
+                **exits,
+                terminator.then_block: self.refined(state, terminator.condition, True),
+                terminator.else_block: self.refined(state, terminator.condition, False),
+            }
+        if isinstance(terminator, Jump):
+            return {**exits, terminator.target: state}
+        if isinstance(terminator, ForNext):
+            return {**exits, terminator.body: state, terminator.exit: state}
+        return exits
+
+    # ------------------------------------------------------------------ transfer
+
+    def phi(self, phi: Phi, incoming: Mapping[BlockId, State]) -> Interval | None:
+        result: Interval | None = None
+        for value, predecessor in phi.incoming:
+            if predecessor not in incoming:
+                continue
+            found = incoming[predecessor].get(value)
+            if found is None:
+                return None
+            result = found if result is None else result.join(found)
+        if result is None:
+            return None
+        previous = self._widened.get(phi.result)
+        widened = result if previous is None else previous.widen(previous.join(result))
+        self._widened[phi.result] = widened
+        return widened
+
+    def instruction(self, instruction: Instruction, state: Mapping[Value, Interval]) -> Interval | None:
+        if isinstance(instruction, Constant):
+            value = instruction.value
+            if isinstance(value, bool | int | float) and value == value:  # noqa: PLR0124 - NaN
+                return Interval(float(value), float(value))
+            return None
+        if isinstance(instruction, BinaryOp):
+            left, right = state.get(instruction.left), state.get(instruction.right)
+            if left is None or right is None:
+                return None
+            return self.binary(instruction.operator, left, right)
+        if isinstance(instruction, UnaryOp):
+            operand = state.get(instruction.operand)
+            if instruction.operator == "not":
+                return Interval(0, 1)
+            if operand is None:
+                return None
+            if instruction.operator == "neg":
+                return Interval(-operand.high, -operand.low)
+            return operand if instruction.operator == "pos" else UNBOUNDED
+        if isinstance(instruction, Compare):
+            return Interval(0, 1)
+        if isinstance(instruction, Call):
+            callee = self.defs.get(instruction.callee)
+            if not isinstance(callee, Symbol):
+                return None
+            name = callee.symbol_id.canonical_name
+            if name in _NUMERIC_CALLS:
+                return _NUMERIC_CALLS[name]
+            if name in _HULL_CALLS and instruction.arguments and not instruction.keywords:
+                hull: Interval | None = None
+                for argument in instruction.arguments:
+                    found = state.get(argument)
+                    if found is None:
+                        return None
+                    hull = found if hull is None else hull.join(found)
+                return hull
+        return None
+
+    @staticmethod
+    def binary(operator: str, left: Interval, right: Interval) -> Interval | None:
+        if operator == "add":
+            return Interval(left.low + right.low, left.high + right.high)
+        if operator == "sub":
+            return Interval(left.low - right.high, left.high - right.low)
+        if operator == "mul":
+            products = [
+                _times(a, b) for a in (left.low, left.high) for b in (right.low, right.high)
+            ]
+            return Interval(min(products), max(products))
+        if operator in ("div", "floor_div", "mod", "pow", "bit_or", "bit_xor", "bit_and", "lshift", "rshift"):
+            return UNBOUNDED
+        return None
+
+    # ------------------------------------------------------------------ refinement
+
+    def refined(self, state: State, condition: Value, truth: bool) -> State:
+        overrides: dict[Value, Interval] = {}
+        self.refine(dict(state), condition, truth, overrides)
+        return MappingProxyType({**state, **overrides}) if overrides else state
+
+    def refine(
+        self, state: dict[Value, Interval], condition: Value, truth: bool, overrides: dict[Value, Interval]
+    ) -> None:
+        definition = self.defs.get(condition)
+        if isinstance(definition, UnaryOp) and definition.operator == "not":
+            self.refine(state, definition.operand, not truth, overrides)
+        elif isinstance(definition, BoolOp) and (definition.operator == "and") == truth:
+            for value in definition.values:
+                self.refine(state, value, truth, overrides)
+        elif isinstance(definition, Compare):
+            left, right = definition.left, definition.right
+            if left not in state or right not in state:
+                return
+            operator = definition.operator
+            if operator == "eq" and truth or operator == "not_eq" and not truth:
+                low = max(state[left].low, state[right].low)
+                high = min(state[left].high, state[right].high)
+                if low <= high:
+                    overrides[left] = overrides[right] = Interval(low, high)
+                    state[left] = state[right] = Interval(low, high)
+                return
+            if operator not in ("lt", "lt_eq", "gt", "gt_eq"):
+                return
+            ascending = (operator in ("lt", "lt_eq")) == truth
+            lower, upper = (left, right) if ascending else (right, left)
+            bounded_lower = Interval(state[lower].low, min(state[lower].high, state[upper].high))
+            bounded_upper = Interval(max(state[upper].low, state[lower].low), state[upper].high)
+            overrides[lower], overrides[upper] = bounded_lower, bounded_upper
+            state[lower], state[upper] = bounded_lower, bounded_upper
+
+
+def analyze_ranges(function: FunctionIR, cfg: CFG) -> RangeFacts:
+    problem = _RangeProblem(function)
+    solution = solve(problem, cfg)
+    states: dict[BlockId, State] = {}
+    for block in function.blocks:
+        if solution.reached(block.id):
+            states[block.id] = problem.evaluate(block, solution.incoming(block.id))
+    return RangeFacts(states)
+
+
+class RangeAnalysis(FunctionAnalysis[RangeFacts]):
+    name: ClassVar[str] = "abstract.ranges"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CFGAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> RangeFacts:
+        return analyze_ranges(ctx.get(SSAAnalysis, function), ctx.get(CFGAnalysis, function))

coretrace_python/abstract/values.py

@@ -0,0 +1,56 @@
+"""Abstract values (architecture §18).
+
+An ``AbstractValue`` records what is known about one SSA value: its constant on a flat
+lattice, the set of Python types it may have (``None`` when unknown) and the truthiness
+that follows. Taints, ranges, string constraints and nullability join this record as
+their analyses arrive.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from coretrace_python.dataflow import BOTTOM, TOP, Element, FlatLattice
+
+_CONSTANTS: FlatLattice[object] = FlatLattice()
+
+
+class Truth(Enum):
+    TRUE = "true"
+    FALSE = "false"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class AbstractValue:
+    constant: Element[object]
+    types: frozenset[str] | None
+
+    @classmethod
+    def of(cls, value: object) -> AbstractValue:
+        return cls(value, frozenset({type(value).__name__}))
+
+    @classmethod
+    def unknown(cls, types: frozenset[str] | None = None) -> AbstractValue:
+        return cls(TOP, types)
+
+    @classmethod
+    def bottom(cls) -> AbstractValue:
+        return cls(BOTTOM, frozenset())
+
+    @property
+    def truthiness(self) -> Truth:
+        if self.constant is TOP or self.constant is BOTTOM:
+            if self.types == frozenset({"NoneType"}):
+                return Truth.FALSE
+            return Truth.UNKNOWN
+        return Truth.TRUE if self.constant else Truth.FALSE
+
+    def join(self, other: AbstractValue) -> AbstractValue:
+        if self.constant is BOTTOM:
+            return other
+        if other.constant is BOTTOM:
+            return self
+        types = None if self.types is None or other.types is None else self.types | other.types
+        return AbstractValue(_CONSTANTS.join(self.constant, other.constant), types)

coretrace_python/analysis/__init__.py

@@ -0,0 +1,31 @@
+"""Analysis infrastructure: typed providers managed as a lazy, cached dependency DAG."""
+
+from coretrace_python.analysis.manager import (
+    AnalysisError,
+    AnalysisManager,
+    CyclicDependencyError,
+    MissingInputError,
+    UndeclaredDependencyError,
+    UnregisteredAnalysisError,
+)
+from coretrace_python.analysis.provider import (
+    Analysis,
+    AnalysisContext,
+    AnyAnalysis,
+    FunctionAnalysis,
+    TransformationPass,
+)
+
+__all__ = [
+    "Analysis",
+    "AnalysisContext",
+    "AnalysisError",
+    "AnalysisManager",
+    "AnyAnalysis",
+    "CyclicDependencyError",
+    "FunctionAnalysis",
+    "MissingInputError",
+    "TransformationPass",
+    "UndeclaredDependencyError",
+    "UnregisteredAnalysisError",
+]

coretrace_python/analysis/manager.py

@@ -0,0 +1,165 @@
+"""The Analysis Manager: registry, dependency DAG, lazy evaluation, cache, invalidation."""
+
+from __future__ import annotations
+
+from typing import Any, overload
+
+from coretrace_python.analysis.provider import (
+    Analysis,
+    AnyAnalysis,
+    FunctionAnalysis,
+    R,
+    TransformationPass,
+)
+from coretrace_python.hir import nodes
+from coretrace_python.source import SourceSpan
+
+
+class AnalysisError(Exception):
+    """Misuse of the analysis registry or dependency declarations."""
+
+
+class UnregisteredAnalysisError(AnalysisError):
+    pass
+
+
+class UndeclaredDependencyError(AnalysisError):
+    pass
+
+
+class CyclicDependencyError(AnalysisError):
+    pass
+
+
+class MissingInputError(AnalysisError):
+    """An analysis that must be provided by the engine was requested before being provided."""
+
+
+_CacheKey = tuple[AnyAnalysis, SourceSpan | None]
+
+
+class AnalysisManager:
+    """Compute registered analyses lazily, once, and share their results."""
+
+    def __init__(self, module: nodes.Module) -> None:
+        self._module = module
+        self._registry: set[AnyAnalysis] = set()
+        self._cache: dict[_CacheKey, Any] = {}
+        self._computing: list[AnyAnalysis] = []
+
+    @property
+    def module(self) -> nodes.Module:
+        return self._module
+
+    # ------------------------------------------------------------------ registry
+
+    def register(self, *analyses: AnyAnalysis) -> None:
+        for analysis in analyses:
+            self._registry.add(analysis)
+            self._check_acyclic(analysis)
+
+    def analysis(self, name: str) -> AnyAnalysis:
+        """Look a registered analysis up by its declared name."""
+
+        for analysis in self._registry:
+            if analysis.name == name:
+                return analysis
+        raise KeyError(name)
+
+    def dependencies(self, analysis: AnyAnalysis) -> frozenset[AnyAnalysis]:
+        """Transitive closure of ``analysis.requires``."""
+
+        found: set[AnyAnalysis] = set()
+        pending = list(analysis.requires)
+        while pending:
+            dependency = pending.pop()
+            if dependency not in found:
+                found.add(dependency)
+                pending.extend(dependency.requires)
+        return frozenset(found)
+
+    def _check_acyclic(self, root: AnyAnalysis) -> None:
+        path: list[AnyAnalysis] = []
+
+        def visit(analysis: AnyAnalysis) -> None:
+            if analysis in path:
+                cycle = [*path[path.index(analysis) :], analysis]
+                raise CyclicDependencyError(
+                    "dependency cycle: " + " -> ".join(a.name for a in cycle)
+                )
+            path.append(analysis)
+            for dependency in analysis.requires:
+                visit(dependency)
+            path.pop()
+
+        visit(root)
+
+    # ------------------------------------------------------------------ evaluation
+
+    @overload
+    def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
+
+    @overload
+    def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...
+
+    def get(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> Any:
+        self._check_target(analysis, function)
+        if analysis not in self._registry:
+            raise UnregisteredAnalysisError(f"analysis {analysis.name!r} is not registered")
+        if self._computing and analysis not in self._computing[-1].requires:
+            current = self._computing[-1]
+            raise UndeclaredDependencyError(
+                f"{current.name} requests {analysis.name} without declaring it in requires"
+            )
+
+        key = self._key(analysis, function)
+        if key in self._cache:
+            return self._cache[key]
+
+        self._computing.append(analysis)
+        try:
+            if function is None:
+                assert issubclass(analysis, Analysis)
+                result = analysis.compute(self)
+            else:
+                assert issubclass(analysis, FunctionAnalysis)
+                result = analysis.compute(self, function)
+        finally:
+            self._computing.pop()
+        self._cache[key] = result
+        return result
+
+    def provide(self, analysis: type[Analysis[R]], result: R) -> None:
+        """Supply the result of a module-level analysis the engine computes elsewhere."""
+
+        self._check_target(analysis, None)
+        if analysis not in self._registry:
+            raise UnregisteredAnalysisError(f"analysis {analysis.name!r} is not registered")
+        self._cache[self._key(analysis, None)] = result
+
+    def is_cached(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> bool:
+        self._check_target(analysis, function)
+        return self._key(analysis, function) in self._cache
+
+    # ------------------------------------------------------------------ invalidation
+
+    def run(self, transformation: type[TransformationPass]) -> None:
+        """Run a transformation, then drop every cached result it does not preserve."""
+
+        transformation.run(self)
+        self._cache = {
+            key: result for key, result in self._cache.items() if key[0] in transformation.preserves
+        }
+
+    # ------------------------------------------------------------------ helpers
+
+    @staticmethod
+    def _check_target(analysis: AnyAnalysis, function: nodes.Function | None) -> None:
+        if issubclass(analysis, FunctionAnalysis) and function is None:
+            raise TypeError(f"{analysis.name} is a function analysis and needs a function")
+        if issubclass(analysis, Analysis) and function is not None:
+            raise TypeError(f"{analysis.name} is a module analysis and takes no function")
+
+    @staticmethod
+    def _key(analysis: AnyAnalysis, function: nodes.Function | None) -> _CacheKey:
+        return (analysis, None if function is None else function.span)

coretrace_python/analysis/provider.py

@@ -0,0 +1,73 @@
+"""Typed analysis providers and the context they compute in (architecture §8, §12).
+
+An analysis is a class, not an instance: its ``name`` and ``version`` identify cached
+results, its ``requires`` declares the dependency DAG, and ``compute`` builds the
+result from an ``AnalysisContext``. Read-only analyses never modify shared IR; a
+``TransformationPass`` may, and must say what it preserves.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Generic, Protocol, TypeVar, overload
+
+from coretrace_python.hir import nodes
+
+R = TypeVar("R")
+
+
+class Analysis(ABC, Generic[R]):
+    """A module-level analysis producing one immutable result per module."""
+
+    name: ClassVar[str]
+    version: ClassVar[int] = 1
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
+
+    @classmethod
+    @abstractmethod
+    def compute(cls, ctx: AnalysisContext) -> R:
+        raise NotImplementedError
+
+
+class FunctionAnalysis(ABC, Generic[R]):
+    """A function-level analysis producing one result per function, on demand."""
+
+    name: ClassVar[str]
+    version: ClassVar[int] = 1
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
+
+    @classmethod
+    @abstractmethod
+    def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> R:
+        raise NotImplementedError
+
+
+AnyAnalysis = type[Analysis[Any]] | type[FunctionAnalysis[Any]]
+
+
+class TransformationPass(ABC):
+    """A pass that may change shared state and therefore invalidates cached results.
+
+    Every cached analysis not listed in ``preserves`` is dropped after the pass runs.
+    """
+
+    name: ClassVar[str]
+    preserves: ClassVar[frozenset[AnyAnalysis]] = frozenset()
+
+    @classmethod
+    @abstractmethod
+    def run(cls, ctx: AnalysisContext) -> None:
+        raise NotImplementedError
+
+
+class AnalysisContext(Protocol):
+    """What an analysis sees while computing: the module and its declared dependencies."""
+
+    @property
+    def module(self) -> nodes.Module: ...
+
+    @overload
+    def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
+
+    @overload
+    def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...

coretrace_python/bundled/dependency/dependency_policy/dependency_policy.py

@@ -0,0 +1,46 @@
+"""Requirements the project's policy denies or leaves unpinned."""
+
+from __future__ import annotations
+
+from collections.abc import 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.plugins import ProjectContext, ProjectPlugin
+
+
+class DependencyPolicyPlugin(ProjectPlugin):
+    name: ClassVar[str] = "dependency-policy"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis})
+
+    def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
+        findings: list[Finding] = []
+        for requirement in ctx.dependencies.requirements:
+            metadata = {"package": requirement.name, "specifier": requirement.specifier}
+            if ctx.policy.denies(requirement.name):
+                findings.append(
+                    Finding(
+                        "denied-dependency",
+                        f"{requirement.name} is denied by the dependency policy",
+                        Severity.HIGH,
+                        Confidence.HIGH,
+                        requirement.span,
+                        None,
+                        metadata,
+                    )
+                )
+            elif ctx.policy.require_pinned and requirement.pinned is None:
+                findings.append(
+                    Finding(
+                        "unpinned-dependency",
+                        f"{requirement.name}{requirement.specifier} is not pinned to one version",
+                        Severity.LOW,
+                        Confidence.HIGH,
+                        requirement.span,
+                        None,
+                        metadata,
+                    )
+                )
+        return findings

coretrace_python/bundled/dependency/dependency_policy/plugin.toml

@@ -0,0 +1,9 @@
+name = "dependency-policy"
+version = "1.0.0"
+plugin_api = ">=1,<2"
+requires = ["dependency.graph"]
+provides = ["policy.dependencies"]
+
+[entrypoint]
+module = "dependency_policy"
+class = "DependencyPolicyPlugin"

coretrace_python/bundled/dependency/reachable_vulnerability/plugin.toml

@@ -0,0 +1,9 @@
+name = "reachable-vulnerability"
+version = "1.0.0"
+plugin_api = ">=1,<2"
+requires = ["dependency.graph", "interprocedural.callgraph"]
+provides = ["vulnerability.reachable-vulnerability"]
+
+[entrypoint]
+module = "reachable_vulnerability"
+class = "ReachableVulnerabilityPlugin"