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

coretrace_python/dataflow/solver.py

@@ -0,0 +1,96 @@
+"""Worklist solver over control-flow graphs (architecture §37 dataflow/worklist, solver).
+
+A problem sees, for each block, the states arriving on its executable incoming edges
+(keyed by the block they come from, or ``ENTRY`` for the initial state) and returns the
+states it sends along outgoing edges. Edges a problem does not return are pruned: the
+blocks behind them stay unreached unless another edge reaches them.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from enum import Enum
+from types import MappingProxyType
+from typing import ClassVar, Generic, TypeVar
+
+from coretrace_python.cfg import CFG, BlockId
+
+S = TypeVar("S")
+
+ENTRY = BlockId("<entry>")
+
+
+class Direction(Enum):
+    FORWARD = "forward"
+    BACKWARD = "backward"
+
+
+class DataflowProblem(ABC, Generic[S]):
+    direction: ClassVar[Direction] = Direction.FORWARD
+
+    @abstractmethod
+    def initial(self) -> S:
+        """State entering the entry block (forward) or leaving the exits (backward)."""
+
+    @abstractmethod
+    def join(self, a: S, b: S) -> S:
+        """Combine the states of two incoming edges."""
+
+    @abstractmethod
+    def flow(self, cfg: CFG, block: BlockId, incoming: Mapping[BlockId, S]) -> Mapping[BlockId, S]:
+        """States sent to the next blocks in the flow direction; omitted edges are pruned."""
+
+
+class Solution(Generic[S]):
+    def __init__(self, problem: DataflowProblem[S], edges: Mapping[BlockId, Mapping[BlockId, S]]):
+        self._problem = problem
+        self._incoming: Mapping[BlockId, Mapping[BlockId, S]] = MappingProxyType(
+            {block: MappingProxyType(dict(found)) for block, found in edges.items()}
+        )
+
+    def incoming(self, block: BlockId) -> Mapping[BlockId, S]:
+        return self._incoming.get(block, MappingProxyType({}))
+
+    def reached(self, block: BlockId) -> bool:
+        return bool(self._incoming.get(block))
+
+    def state(self, block: BlockId) -> S:
+        """Join of every state arriving at ``block``; raises for an unreached block."""
+
+        states = list(self.incoming(block).values())
+        if not states:
+            raise KeyError(block)
+        result = states[0]
+        for other in states[1:]:
+            result = self._problem.join(result, other)
+        return result
+
+    def edge(self, source: BlockId, target: BlockId) -> S:
+        return self._incoming[target][source]
+
+
+def solve(problem: DataflowProblem[S], cfg: CFG) -> Solution[S]:
+    forward = problem.direction is Direction.FORWARD
+    order = {block: position for position, block in enumerate(cfg.blocks)}
+    if forward:
+        starts = [cfg.entry]
+    else:
+        starts = [b for b in cfg.blocks if b in cfg.reachable() and not cfg.successors(b)]
+
+    incoming: dict[BlockId, dict[BlockId, S]] = {start: {ENTRY: problem.initial()} for start in starts}
+    worklist = list(starts)
+    queued = set(starts)
+    while worklist:
+        worklist.sort(key=lambda block: order[block], reverse=True)
+        block = worklist.pop()
+        queued.discard(block)
+        for target, state in problem.flow(cfg, block, MappingProxyType(incoming[block])).items():
+            edges = incoming.setdefault(target, {})
+            if block in edges and edges[block] == state:
+                continue
+            edges[block] = state
+            if target not in queued:
+                worklist.append(target)
+                queued.add(target)
+    return Solution(problem, incoming)

coretrace_python/dependency/__init__.py

@@ -0,0 +1,44 @@
+"""Dependency resolution and advisories (architecture §26)."""
+
+from coretrace_python.dependency.advisories import (
+    ADVISORY_FILE,
+    AdvisoryFileError,
+    dump_advisories,
+    import_osv,
+    load_advisories,
+    read_osv,
+)
+from coretrace_python.dependency.graph import (
+    DEPENDENCY_FILES,
+    Advisory,
+    DependencyAnalysis,
+    DependencyGraph,
+    Requirement,
+    Version,
+    normalize,
+    parse_dependencies,
+)
+from coretrace_python.dependency.policy import POLICY_FILE, Policy, apply_policy, load_policy
+from coretrace_python.dependency.sbom import render_sbom
+
+__all__ = [
+    "ADVISORY_FILE",
+    "DEPENDENCY_FILES",
+    "POLICY_FILE",
+    "Advisory",
+    "AdvisoryFileError",
+    "DependencyAnalysis",
+    "DependencyGraph",
+    "Policy",
+    "Requirement",
+    "Version",
+    "apply_policy",
+    "dump_advisories",
+    "import_osv",
+    "load_advisories",
+    "load_policy",
+    "normalize",
+    "parse_dependencies",
+    "read_osv",
+    "render_sbom",
+]

coretrace_python/dependency/advisories.py

@@ -0,0 +1,168 @@
+"""Local advisory files and the OSV import (architecture §26).
+
+The analysis never touches the network. ``import_osv`` converts the records of a public
+OSV dump into ``Advisory`` values, keeping the PyPI ecosystem and turning each range of
+events into a version specifier; ``dump_advisories`` writes them as a small JSON file
+that a project keeps at its root as ``advisories.json`` or passes with ``--advisories``.
+OSV records name no affected APIs, so imported advisories feed the requirement checks
+and the SBOM; a file completed by hand with ``affected_symbols`` also feeds the
+reachability and correlation checks.
+"""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from collections.abc import Iterable, Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from coretrace_python.dependency.graph import Advisory, normalize
+from coretrace_python.findings import Severity
+from coretrace_python.semantic.symbols import SymbolId
+
+ADVISORY_FILE = "advisories.json"
+ADVISORY_SCHEMA = 1
+
+_SEVERITIES = {
+    "LOW": Severity.LOW,
+    "MODERATE": Severity.MEDIUM,
+    "MEDIUM": Severity.MEDIUM,
+    "HIGH": Severity.HIGH,
+    "CRITICAL": Severity.CRITICAL,
+}
+
+
+class AdvisoryFileError(Exception):
+    """An advisory or policy file could not be read."""
+
+
+# --------------------------------------------------------------------------- OSV
+
+
+def read_osv(path: Path) -> Iterator[Mapping[str, Any]]:
+    """The records of an OSV dump: one JSON file (a record or a list), a directory of
+    JSON files, or a zip archive of them."""
+
+    if path.is_dir():
+        for file in sorted(path.glob("*.json")):
+            yield from _records(json.loads(file.read_text(encoding="utf-8")))
+    elif path.suffix == ".zip":
+        with zipfile.ZipFile(path) as archive:
+            for name in sorted(archive.namelist()):
+                if name.endswith(".json"):
+                    yield from _records(json.loads(archive.read(name).decode("utf-8")))
+    else:
+        yield from _records(json.loads(path.read_text(encoding="utf-8")))
+
+
+def _records(data: Any) -> Iterator[Mapping[str, Any]]:
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, Mapping):
+                yield item
+    elif isinstance(data, Mapping):
+        yield data
+
+
+def import_osv(records: Iterable[Mapping[str, Any]]) -> tuple[Advisory, ...]:
+    """The PyPI advisories of OSV records, one per affected range."""
+
+    advisories: list[Advisory] = []
+    for record in records:
+        identifier = record.get("id")
+        if not isinstance(identifier, str):
+            continue
+        summary = str(record.get("summary") or "").strip()
+        if not summary:
+            lines = str(record.get("details") or "").strip().splitlines()
+            summary = lines[0] if lines else identifier
+        aliases = tuple(str(a) for a in record.get("aliases") or [])
+        severity = _severity(record)
+        for affected in record.get("affected") or []:
+            package = (affected.get("package") or {}) if isinstance(affected, Mapping) else {}
+            if str(package.get("ecosystem", "")).lower() != "pypi" or not package.get("name"):
+                continue
+            name = normalize(str(package["name"]))
+            for specifier in _specifiers(affected.get("ranges") or []):
+                advisories.append(Advisory(identifier, name, specifier, summary, severity, (), aliases))
+    return tuple(advisories)
+
+
+def _severity(record: Mapping[str, Any]) -> Severity:
+    specific = record.get("database_specific") or {}
+    label = specific.get("severity") if isinstance(specific, Mapping) else None
+    return _SEVERITIES.get(str(label).upper(), Severity.MEDIUM)
+
+
+def _specifiers(ranges: Iterable[Mapping[str, Any]]) -> list[str]:
+    found: list[str] = []
+    for entry in ranges:
+        if entry.get("type") not in ("ECOSYSTEM", "SEMVER"):
+            continue
+        introduced: str | None = None
+        for event in entry.get("events") or []:
+            if "introduced" in event:
+                introduced = str(event["introduced"])
+            elif "fixed" in event or "last_affected" in event:
+                bound = f"<{event['fixed']}" if "fixed" in event else f"<={event['last_affected']}"
+                found.append(_clause(introduced, bound))
+                introduced = None
+        if introduced is not None:
+            found.append(_clause(introduced, None))
+    return found
+
+
+def _clause(introduced: str | None, bound: str | None) -> str:
+    parts: list[str] = []
+    if introduced is not None and introduced != "0":
+        parts.append(f">={introduced}")
+    if bound is not None:
+        parts.append(bound)
+    return ",".join(parts) if parts else ">=0"
+
+
+# --------------------------------------------------------------------------- local file
+
+
+def dump_advisories(advisories: Iterable[Advisory]) -> str:
+    document = {
+        "schema": ADVISORY_SCHEMA,
+        "advisories": [
+            {
+                "id": a.id,
+                "package": a.package,
+                "vulnerable": a.vulnerable,
+                "summary": a.summary,
+                "severity": a.severity.value,
+                "affected_symbols": [str(s) for s in a.affected_symbols],
+                "aliases": list(a.aliases),
+            }
+            for a in advisories
+        ],
+    }
+    return json.dumps(document, indent=2) + "\n"
+
+
+def load_advisories(path: Path) -> tuple[Advisory, ...]:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+        if document.get("schema") != ADVISORY_SCHEMA:
+            raise AdvisoryFileError(f"{path}: unsupported advisory schema {document.get('schema')!r}")
+        return tuple(_advisory(entry) for entry in document["advisories"])
+    except AdvisoryFileError:
+        raise
+    except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
+        raise AdvisoryFileError(f"{path}: {error}") from error
+
+
+def _advisory(entry: Mapping[str, Any]) -> Advisory:
+    return Advisory(
+        str(entry["id"]),
+        normalize(str(entry["package"])),
+        str(entry["vulnerable"]),
+        str(entry["summary"]),
+        Severity(entry["severity"]),
+        tuple(SymbolId(str(s)) for s in entry.get("affected_symbols") or []),
+        tuple(str(a) for a in entry.get("aliases") or []),
+    )

coretrace_python/dependency/correlation.py

@@ -0,0 +1,87 @@
+"""Correlation engine (architecture §27).
+
+A package required in a vulnerable version, an API the advisory affects, a call to that
+API reachable in the project, and attacker-controlled data reaching that call: the
+affected APIs become sinks of the ``ADVISORY`` taint kind, so the shared taint engine,
+the function summaries and the refutation engine do the work, and the flows they leave
+are correlated here into one high-confidence ``exploitable-vulnerability`` finding.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from coretrace_python.dependency.graph import Advisory, DependencyGraph
+from coretrace_python.findings import Confidence, Finding, Severity
+from coretrace_python.findings.refutation import Status, Verdicts
+from coretrace_python.semantic.symbols import SymbolId
+from coretrace_python.taint import Sink, TaintFlow, TaintKind
+
+
+def affected_symbols(
+    dependencies: DependencyGraph, advisories: Iterable[Advisory]
+) -> Mapping[SymbolId, Advisory]:
+    """The APIs affected by advisories whose package is required in a vulnerable version."""
+
+    affected: dict[SymbolId, Advisory] = {}
+    for requirement in dependencies.requirements:
+        for advisory in advisories:
+            if advisory.affects(requirement):
+                for symbol in advisory.affected_symbols:
+                    affected.setdefault(symbol, advisory)
+    return affected
+
+
+def advisory_sinks(affected: Mapping[SymbolId, Advisory]) -> tuple[Sink, ...]:
+    return tuple(Sink(symbol, TaintKind.ADVISORY) for symbol in affected)
+
+
+def correlate(
+    function: str,
+    flows: Iterable[TaintFlow],
+    verdicts: Verdicts | None,
+    affected: Mapping[SymbolId, Advisory],
+) -> tuple[Finding, ...]:
+    """Exploitable-vulnerability findings for the non-refuted ADVISORY flows of a function."""
+
+    findings: list[Finding] = []
+    for flow in flows:
+        if not flow.kinds & TaintKind.ADVISORY:
+            continue
+        advisory = affected.get(flow.sink.symbol)
+        if advisory is None:
+            continue
+        verdict = verdicts.verdict(flow) if verdicts is not None else None
+        if verdict is not None and verdict.status is Status.REFUTED:
+            continue
+        hotspot = verdict is not None and verdict.status is Status.HOTSPOT
+        message = (
+            f"{advisory.id}: {flow.source.label} input reaches {flow.sink.symbol}, affected in "
+            f"the required {advisory.package} {advisory.vulnerable}: {advisory.summary}"
+        )
+        metadata = {
+            "advisory": advisory.id,
+            "package": advisory.package,
+            "symbol": str(flow.sink.symbol),
+            "source": str(flow.source.symbol),
+            "source_label": flow.source.label,
+            "verdict": "hotspot" if hotspot else "vulnerability",
+        }
+        if verdict is not None:
+            metadata["evidence"] = verdict.evidence
+        if flow.through is not None and flow.sink_location is not None:
+            message += f" through {flow.through}"
+            metadata["through"] = flow.through
+            metadata["sink_line"] = str(flow.sink_location.start_line)
+        findings.append(
+            Finding(
+                rule_id="exploitable-vulnerability",
+                message=message,
+                severity=Severity.CRITICAL,
+                confidence=Confidence.MEDIUM if hotspot else Confidence.HIGH,
+                span=flow.location,
+                function=function,
+                metadata=metadata,
+            )
+        )
+    return tuple(findings)

coretrace_python/dependency/graph.py

@@ -0,0 +1,274 @@
+"""Dependency resolution (architecture §26).
+
+Requirements declared in ``requirements.txt``, ``pyproject.toml`` (PEP 621 and Poetry)
+and pinned in ``poetry.lock`` or ``uv.lock`` become a ``DependencyGraph``. Versions are
+compared with a small PEP 440 subset (``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``,
+``~=`` and Poetry's ``^``), enough to decide whether a requirement may allow a version an
+advisory marks as vulnerable. Nothing is downloaded.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import PurePath
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+from coretrace_python.analysis import Analysis, AnalysisContext
+from coretrace_python.findings import Severity
+from coretrace_python.semantic.symbols import SymbolId
+from coretrace_python.source import SourceFile, SourceId, SourceSpan
+
+_REQUIREMENT = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*(.*)$")
+_CLAUSE = re.compile(r"^(===|==|!=|<=|>=|~=|<|>|\^)\s*([0-9][0-9A-Za-z.*+!-]*)$")
+
+
+def normalize(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+@dataclass(frozen=True, order=True)
+class Version:
+    parts: tuple[int, ...]
+
+    @classmethod
+    def parse(cls, text: str) -> Version:
+        parts: list[int] = []
+        for piece in text.strip().split("."):
+            digits = re.match(r"\d+", piece)
+            if digits is None:
+                break
+            parts.append(int(digits.group()))
+            if digits.end() != len(piece):
+                break
+        return cls(tuple(parts) or (0,))
+
+    def padded(self, length: int) -> tuple[int, ...]:
+        return self.parts + (0,) * (length - len(self.parts))
+
+    def satisfies(self, specifier: str) -> bool:
+        for clause in [c.strip() for c in specifier.split(",") if c.strip()]:
+            match = _CLAUSE.match(clause)
+            if match is None:
+                continue
+            operator, wanted = match.group(1), Version.parse(match.group(2))
+            if not self._satisfies_clause(operator, wanted, match.group(2)):
+                return False
+        return True
+
+    def _satisfies_clause(self, operator: str, wanted: Version, raw: str) -> bool:
+        length = max(len(self.parts), len(wanted.parts))
+        mine, theirs = self.padded(length), wanted.padded(length)
+        if operator in ("==", "==="):
+            if raw.endswith(".*"):
+                prefix = wanted.parts
+                return self.parts[: len(prefix)] == prefix
+            return mine == theirs
+        if operator == "!=":
+            return mine != theirs
+        if operator == "<":
+            return mine < theirs
+        if operator == "<=":
+            return mine <= theirs
+        if operator == ">":
+            return mine > theirs
+        if operator == ">=":
+            return mine >= theirs
+        if operator == "~=":
+            ceiling = list(wanted.parts[:-1]) if len(wanted.parts) > 1 else [wanted.parts[0]]
+            ceiling[-1] += 1
+            return mine >= theirs and self.padded(len(ceiling)) < tuple(ceiling)
+        if operator == "^":
+            ceiling = [0] * len(wanted.parts)
+            for index, part in enumerate(wanted.parts):
+                if part != 0 or index == len(wanted.parts) - 1:
+                    ceiling[index] = part + 1
+                    break
+            return mine >= theirs and self.padded(len(ceiling)) < tuple(ceiling)
+        return True
+
+
+def _lower_bounds(specifier: str) -> list[Version]:
+    bounds: list[Version] = []
+    for clause in [c.strip() for c in specifier.split(",") if c.strip()]:
+        match = _CLAUSE.match(clause)
+        if match is not None and match.group(1) in (">=", ">", "~=", "^", "==", "==="):
+            bounds.append(Version.parse(match.group(2)))
+    return bounds
+
+
+@dataclass(frozen=True)
+class Requirement:
+    name: str
+    specifier: str
+    span: SourceSpan
+    pinned: Version | None = None
+    optional: bool = False
+
+    @classmethod
+    def parse(cls, text: str, source_id: SourceId, line: int, optional: bool = False) -> Requirement | None:
+        cleaned = text.split("#", 1)[0].split(";", 1)[0].strip()
+        match = _REQUIREMENT.match(cleaned)
+        if match is None or not match.group(1):
+            return None
+        specifier = ",".join(part.strip() for part in match.group(3).split(",") if part.strip())
+        pinned = None
+        clauses = [c for c in specifier.split(",") if c]
+        if len(clauses) == 1 and clauses[0].startswith("==") and not clauses[0].endswith(".*"):
+            pinned = Version.parse(clauses[0].lstrip("="))
+        return cls(normalize(match.group(1)), specifier, SourceSpan(source_id, line, 1), pinned, optional)
+
+    def may_match(self, vulnerable: str) -> bool:
+        """Whether some version this requirement allows is in the ``vulnerable`` range."""
+
+        if self.pinned is not None:
+            return self.pinned.satisfies(vulnerable)
+        candidates = [Version((0,)), *_lower_bounds(self.specifier), *_lower_bounds(vulnerable)]
+        return any(v.satisfies(self.specifier) and v.satisfies(vulnerable) for v in candidates)
+
+
+@dataclass(frozen=True)
+class Advisory:
+    id: str
+    package: str
+    vulnerable: str
+    summary: str
+    severity: Severity
+    affected_symbols: tuple[SymbolId, ...] = ()
+    aliases: tuple[str, ...] = ()
+
+    def affects(self, requirement: Requirement) -> bool:
+        return requirement.name == normalize(self.package) and requirement.may_match(self.vulnerable)
+
+
+class DependencyGraph:
+    def __init__(self, requirements: Mapping[str, Requirement] | None = None, errors: tuple[str, ...] = ()) -> None:
+        self._requirements = MappingProxyType(dict(sorted((requirements or {}).items())))
+        self.errors = errors
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._requirements)
+
+    @property
+    def requirements(self) -> tuple[Requirement, ...]:
+        return tuple(self._requirements.values())
+
+    def requirement(self, name: str) -> Requirement | None:
+        return self._requirements.get(normalize(name))
+
+    def merge(self, other: DependencyGraph) -> DependencyGraph:
+        merged = dict(self._requirements)
+        for name, requirement in other._requirements.items():
+            current = merged.get(name)
+            if current is None:
+                merged[name] = requirement
+                continue
+            merged[name] = Requirement(
+                name,
+                current.specifier or requirement.specifier,
+                current.span if current.specifier else requirement.span,
+                requirement.pinned or current.pinned,
+                current.optional and requirement.optional,
+            )
+        return DependencyGraph(merged, self.errors + other.errors)
+
+
+def parse_dependencies(source: SourceFile) -> DependencyGraph:
+    """The requirements declared or pinned by one dependency file; other files are empty."""
+
+    name = source.path.name if source.path is not None else PurePath(str(source.source_id)).name
+    if name.startswith("requirements") and name.endswith(".txt"):
+        return _parse_requirements_txt(source)
+    if name == "pyproject.toml":
+        return _parse_toml(source, _pyproject_requirements)
+    if name in ("poetry.lock", "uv.lock"):
+        return _parse_toml(source, _lock_requirements)
+    return DependencyGraph()
+
+
+def _parse_requirements_txt(source: SourceFile) -> DependencyGraph:
+    found: dict[str, Requirement] = {}
+    for number, line in enumerate(source.text.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("#", "-")):
+            continue
+        requirement = Requirement.parse(stripped, source.source_id, number)
+        if requirement is not None:
+            found[requirement.name] = requirement
+    return DependencyGraph(found)
+
+
+def _parse_toml(source: SourceFile, extract: Any) -> DependencyGraph:
+    try:
+        data = tomllib.loads(source.text)
+    except tomllib.TOMLDecodeError as error:
+        return DependencyGraph(errors=(f"{source.source_id}: {error}",))
+    found: dict[str, Requirement] = {}
+    for requirement in extract(data, source):
+        found[requirement.name] = requirement
+    return DependencyGraph(found)
+
+
+def _line_of(source: SourceFile, key: str, default: int = 1) -> int:
+    for number, line in enumerate(source.text.splitlines(), start=1):
+        if key in line:
+            return number
+    return default
+
+
+def _pyproject_requirements(data: Mapping[str, Any], source: SourceFile) -> list[Requirement]:
+    found: list[Requirement] = []
+    project = data.get("project", {})
+    for text in project.get("dependencies", []) or []:
+        requirement = Requirement.parse(text, source.source_id, _line_of(source, text))
+        if requirement is not None:
+            found.append(requirement)
+    for group in (project.get("optional-dependencies", {}) or {}).values():
+        for text in group or []:
+            requirement = Requirement.parse(text, source.source_id, _line_of(source, text), True)
+            if requirement is not None:
+                found.append(requirement)
+    poetry = data.get("tool", {}).get("poetry", {})
+    for section, optional in (("dependencies", False), ("dev-dependencies", True)):
+        for name, spec in (poetry.get(section, {}) or {}).items():
+            if normalize(name) == "python":
+                continue
+            specifier = spec.get("version", "") if isinstance(spec, dict) else str(spec)
+            if specifier == "*":
+                specifier = ""
+            requirement = Requirement.parse(
+                f"{name}{specifier}", source.source_id, _line_of(source, name), optional
+            )
+            if requirement is not None:
+                found.append(requirement)
+    return found
+
+
+def _lock_requirements(data: Mapping[str, Any], source: SourceFile) -> list[Requirement]:
+    found: list[Requirement] = []
+    for package in data.get("package", []) or []:
+        name, version = package.get("name"), package.get("version")
+        if not isinstance(name, str) or not isinstance(version, str):
+            continue
+        line = _line_of(source, f'name = "{name}"')
+        found.append(
+            Requirement(normalize(name), "", SourceSpan(source.source_id, line, 1), Version.parse(version))
+        )
+    return found
+
+
+class DependencyAnalysis(Analysis[DependencyGraph]):
+    """The project's dependency graph, provided by the engine; empty for a lone file."""
+
+    name: ClassVar[str] = "dependency.graph"
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext) -> DependencyGraph:
+        return DependencyGraph()
+
+
+DEPENDENCY_FILES = ("pyproject.toml", "poetry.lock", "uv.lock")