feat: dependency analysis and reachable vulnerabilities

README.md

@@ -35,6 +35,11 @@ Given a directory, every Python file below it is analysed as one project: module
 named after their packages, and taint follows calls into functions defined in other files
 through a project-wide index of function summaries iterated to a fixpoint. Hidden and
 tooling directories (`.venv`, `node_modules`, `__pycache__`, `build`, `dist`) are skipped.
+The dependency files at the root (`requirements*.txt`, `pyproject.toml`, `poetry.lock`,
+`uv.lock`) are resolved into a dependency graph. Plugins may contribute advisories; the
+shipped `dependency/` plugins report a requirement that allows a vulnerable version at
+its line, and every call in the project to an API the advisory affects. The shipped
+advisory database is a small offline sample; a live OSV feed is future work.
 
 `--plugins` is a directory searched recursively for `plugin.toml` manifests and may be
 repeated. The repository ships a first set under `plugins/`: security models for the

plugins/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"

plugins/dependency/reachable_vulnerability/reachable_vulnerability.py

@@ -0,0 +1,56 @@
+"""Calls, anywhere in the project, to an API affected by a vulnerable requirement."""
+
+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
+from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
+from coretrace_python.plugins import ProjectContext, ProjectPlugin
+
+
+class ReachableVulnerabilityPlugin(ProjectPlugin):
+    name: ClassVar[str] = "reachable-vulnerability"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
+
+    def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
+        affected = {}
+        for requirement in ctx.dependencies.requirements:
+            for advisory in ctx.advisories:
+                if advisory.affects(requirement):
+                    for symbol in advisory.affected_symbols:
+                        affected.setdefault(symbol, advisory)
+        if not affected:
+            return ()
+        findings: list[Finding] = []
+        for module in ctx.modules:
+            graph = ctx.call_graph(module)
+            for function in graph.functions:
+                for site in graph.sites(function):
+                    if not isinstance(site.target, ExternalSymbol):
+                        continue
+                    advisory = affected.get(site.target.symbol)
+                    if advisory is None:
+                        continue
+                    findings.append(
+                        Finding(
+                            rule_id="reachable-vulnerability",
+                            message=(
+                                f"{advisory.id}: {site.target.symbol} is affected in the required "
+                                f"{advisory.package} {advisory.vulnerable}: {advisory.summary}"
+                            ),
+                            severity=advisory.severity,
+                            confidence=Confidence.HIGH,
+                            span=site.location,
+                            function=function,
+                            metadata={
+                                "advisory": advisory.id,
+                                "package": advisory.package,
+                                "symbol": str(site.target.symbol),
+                            },
+                        )
+                    )
+        return findings

plugins/dependency/sample_advisories/plugin.toml

@@ -0,0 +1,9 @@
+name = "sample-advisories"
+version = "1.0.0"
+plugin_api = ">=1,<2"
+requires = []
+provides = ["advisories.sample"]
+
+[entrypoint]
+module = "sample_advisories"
+class = "SampleAdvisories"

plugins/dependency/sample_advisories/sample_advisories.py

@@ -0,0 +1,64 @@
+"""A small, offline sample of published advisories (architecture §26).
+
+This is a demonstration database: a handful of well-known CVEs with the APIs they
+affect. A live OSV or GHSA feed belongs to a dedicated plugin.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from coretrace_python.dependency import Advisory
+from coretrace_python.findings import Severity
+from coretrace_python.plugins import ModelPlugin
+from coretrace_python.semantic.symbols import SymbolId
+
+
+def _sym(path: str) -> SymbolId:
+    return SymbolId(f"python.{path}")
+
+
+class SampleAdvisories(ModelPlugin):
+    name: ClassVar[str] = "sample-advisories"
+    advisories: ClassVar[tuple[Advisory, ...]] = (
+        Advisory(
+            "CVE-2020-1747",
+            "pyyaml",
+            "<5.4",
+            "yaml.load and full_load can execute arbitrary code from untrusted documents",
+            Severity.CRITICAL,
+            (_sym("yaml.load"), _sym("yaml.full_load"), _sym("yaml.unsafe_load")),
+        ),
+        Advisory(
+            "CVE-2018-18074",
+            "requests",
+            "<2.20.0",
+            "Authorization header is leaked on redirects to another host",
+            Severity.HIGH,
+            (_sym("requests.get"), _sym("requests.post"), _sym("requests.request"), _sym("requests.Session")),
+        ),
+        Advisory(
+            "CVE-2020-28493",
+            "jinja2",
+            "<2.11.3",
+            "regular expression denial of service in the urlize filter",
+            Severity.MEDIUM,
+            (_sym("jinja2.Environment"), _sym("jinja2.Template")),
+        ),
+        Advisory(
+            "CVE-2021-33503",
+            "urllib3",
+            "<1.26.5",
+            "regular expression denial of service when parsing authority in URLs",
+            Severity.HIGH,
+            (_sym("urllib3.PoolManager"), _sym("urllib3.request")),
+        ),
+        Advisory(
+            "CVE-2023-30861",
+            "flask",
+            "<2.2.5",
+            "session cookie may be leaked through caching proxies",
+            Severity.HIGH,
+            (_sym("flask.Flask"),),
+        ),
+    )

plugins/dependency/vulnerable_dependency/plugin.toml

@@ -0,0 +1,9 @@
+name = "vulnerable-dependency"
+version = "1.0.0"
+plugin_api = ">=1,<2"
+requires = ["dependency.graph"]
+provides = ["vulnerability.vulnerable-dependency"]
+
+[entrypoint]
+module = "vulnerable_dependency"
+class = "VulnerableDependencyPlugin"

plugins/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -0,0 +1,43 @@
+"""Requirements that allow a version an advisory marks as vulnerable."""
+
+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
+from coretrace_python.plugins import ProjectContext, ProjectPlugin
+
+
+class VulnerableDependencyPlugin(ProjectPlugin):
+    name: ClassVar[str] = "vulnerable-dependency"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis})
+
+    def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
+        findings: list[Finding] = []
+        for requirement in ctx.dependencies.requirements:
+            for advisory in ctx.advisories:
+                if not advisory.affects(requirement):
+                    continue
+                pinned = requirement.pinned is not None
+                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}"
+                        ),
+                        severity=advisory.severity,
+                        confidence=Confidence.HIGH if pinned else Confidence.MEDIUM,
+                        span=requirement.span,
+                        metadata={
+                            "advisory": advisory.id,
+                            "package": advisory.package,
+                            "specifier": requirement.specifier,
+                        },
+                    )
+                )
+        return findings

src/coretrace_python/dependency/__init__.py

@@ -0,0 +1,23 @@
+"""Dependency resolution and advisories (architecture §26)."""
+
+from coretrace_python.dependency.graph import (
+    DEPENDENCY_FILES,
+    Advisory,
+    DependencyAnalysis,
+    DependencyGraph,
+    Requirement,
+    Version,
+    normalize,
+    parse_dependencies,
+)
+
+__all__ = [
+    "DEPENDENCY_FILES",
+    "Advisory",
+    "DependencyAnalysis",
+    "DependencyGraph",
+    "Requirement",
+    "Version",
+    "normalize",
+    "parse_dependencies",
+]