diff --git a/README.md b/README.md index 22ea0e6..4375faf 100644 --- a/README.md +++ b/README.md @@ -34,10 +34,18 @@ inline metadata says). The script: 4. writes a table of the findings to the job summary, and an error annotation for each one that blocks. -A finding **blocks the merge** when its severity is **high** or **critical**, or unknown (no -GHSA record): an unknown severity never lets a vulnerability through. Low and moderate -findings are listed without failing the job. A withdrawn advisory never blocks. If OSV can't -be read, the job fails. +A finding **blocks the merge** when it is in a **runtime dependency** and its severity is +**high** or **critical**, or unknown (no GHSA record): an unknown severity never lets a +vulnerability through. Low and moderate findings are listed without failing the job, and so +are findings in packages that only the dependency groups need (`dev`, `test`, `docs`, …), +which don't ship with the project. A withdrawn advisory never blocks. If OSV can't be read, +the job fails. + +The runtime dependencies are those of the projects of the lock (its editable or virtual +packages) and of their extras, followed through the lock, with the extras each dependency +asks for. Whatever a project lists in `[project] dependencies` counts, even tools that only +its developers use: move those to a dependency group. A lock without a project counts every +package as a runtime dependency. ### What leaves the repository diff --git a/scripts/dependency_scan.py b/scripts/dependency_scan.py index 2f6d909..040e226 100644 --- a/scripts/dependency_scan.py +++ b/scripts/dependency_scan.py @@ -5,9 +5,11 @@ """Check the packages locked in the uv.lock files of the repository against OSV. Each package from a package index is looked up by name and version in the OSV database -(https://osv.dev), which is all that leaves the runner. A finding blocks the merge when its -severity is high or critical, or unknown, unless .github/vulnerability-exceptions.toml lists -it. The severity is GitHub's, from the GHSA records that OSV mirrors. +(https://osv.dev), which is all that leaves the runner. A finding blocks the merge when it is +in a runtime dependency and its severity is high or critical, or unknown, unless +.github/vulnerability-exceptions.toml lists it. The severity is GitHub's, from the GHSA +records that OSV mirrors. Findings in packages that only dependency groups (dev, test, docs, +…) need are reported without blocking. """ from __future__ import annotations @@ -19,6 +21,7 @@ import tomllib import urllib.error import urllib.request +from collections import defaultdict from collections.abc import Callable from concurrent.futures import ThreadPoolExecutor from dataclasses import dataclass, field @@ -50,6 +53,7 @@ class Finding: aliases: list[str] summary: str fix_versions: list[str] + runtime: bool = True severity: str = "unknown" withdrawn: bool = False exception: Approval | None = None @@ -64,7 +68,7 @@ def ghsa(self) -> str | None: @property def blocking(self) -> bool: - if self.withdrawn or self.exception is not None: + if not self.runtime or self.withdrawn or self.exception is not None: return False return self.severity not in {"low", "moderate", "medium"} @@ -74,6 +78,7 @@ class Package: lock: str name: str version: str + runtime: bool = True @dataclass @@ -171,6 +176,40 @@ def lock_files(root: Path) -> list[Path]: return sorted(root / name for name in output.split("\0") if name) +def runtime_packages(packages: list[dict]) -> set[tuple[str, str | None]] | None: + """The (name, version) of the packages that the projects of a lock need at run time. + + The walk starts from the projects (editable or virtual sources) with their extras, and + follows the dependencies, and the extras they ask for, but not the dependency groups. + Without a project, it returns None: every package counts as a runtime dependency. + """ + by_name: dict[str, list[dict]] = defaultdict(list) + for package in packages: + by_name[package["name"]].append(package) + roots = [p for p in packages if {"editable", "virtual"} & set(p.get("source", {}))] + if not roots: + return None + pending = [(p, extra) for p in roots for extra in [None, *p.get("optional-dependencies", {})]] + seen: set[tuple[str, str | None, str | None]] = set() + while pending: + package, extra = pending.pop() + key = (package["name"], package.get("version"), extra) + if key in seen: + continue + seen.add(key) + if extra is None: + dependencies = package.get("dependencies", []) + else: + dependencies = package.get("optional-dependencies", {}).get(extra, []) + for dependency in dependencies: + for target in by_name[dependency["name"]]: + # with several versions locked, the dependency names the one it uses + if dependency.get("version", target.get("version")) != target.get("version"): + continue + pending += [(target, x) for x in [None, *dependency.get("extra", [])]] + return {(name, version) for name, version, _ in seen} + + def locked_packages(lock: Path, root: Path) -> list[Package]: """The packages of LOCK that come from a package index, with their versions. @@ -182,9 +221,15 @@ def locked_packages(lock: Path, root: Path) -> list[Package]: except tomllib.TOMLDecodeError as error: raise ScanError(f"{lock.relative_to(root)} is not valid TOML: {error}") from error name = str(lock.relative_to(root)) + runtime = runtime_packages(data.get("package", [])) return sorted( { - Package(name, package["name"], package["version"]) + Package( + name, + package["name"], + package["version"], + runtime is None or (package["name"], package["version"]) in runtime, + ) for package in data.get("package", []) if "registry" in package.get("source", {}) and "version" in package }, @@ -232,6 +277,7 @@ def find(packages: list[Package], osv: Osv) -> list[Finding]: lock=package.lock, package=package.name, version=package.version, + runtime=package.runtime, id=id, aliases=aliases, summary=record.get("summary") or record.get("details", "").split("\n")[0], @@ -279,13 +325,15 @@ def report(findings: list[Finding], exceptions: list[Approval], locks: list[str] lines.append("No known vulnerabilities.") else: lines.append( - f"{len(findings)} finding(s), {len(blocking)} blocking: high, critical or of " - "unknown severity, and not in `.github/vulnerability-exceptions.toml`." + f"{len(findings)} finding(s), {len(blocking)} blocking: in a runtime dependency, " + "high, critical or of unknown severity, and not in " + "`.github/vulnerability-exceptions.toml`. Findings in packages that only the " + "dependency groups need (dev, test, docs, …) don't block." ) lines += [ "", - "| | Package | Advisory | Severity | Fixed in | Summary |", - "|---|---|---|---|---|---|", + "| | Package | Needed at | Advisory | Severity | Fixed in | Summary |", + "|---|---|---|---|---|---|---|", ] order = {"critical": 0, "high": 1, "unknown": 2, "moderate": 3, "medium": 3, "low": 4} @@ -303,9 +351,10 @@ def key(f: Finding) -> tuple: status = "reported" link = f"[{f.id}](https://osv.dev/vulnerability/{f.id})" fixed = cell(", ".join(f.fix_versions) or "no fix yet") + needed = "run time" if f.runtime else "development" lines.append( - f"| {status} | {cell(f.package)} {cell(f.version)} (`{f.lock}`) | {link} | " - f"{f.severity} | {fixed} | {cell(f.summary)} |" + f"| {status} | {cell(f.package)} {cell(f.version)} (`{f.lock}`) | {needed} | " + f"{link} | {f.severity} | {fixed} | {cell(f.summary)} |" ) unused = [e for e in exceptions if not e.used] if unused: diff --git a/tests/test_dependency_scan.py b/tests/test_dependency_scan.py index 41d1e38..be120c8 100644 --- a/tests/test_dependency_scan.py +++ b/tests/test_dependency_scan.py @@ -257,6 +257,99 @@ def test_workflow_command_messages_are_escaped(scan) -> None: assert scan.command("50% done\nnext") == "50%25 done%0Anext" +# --- runtime and development dependencies ------------------------------------------------ + +LOCK = """ +version = 1 +[[package]] +name = "demo" +version = "0.1.0" +source = { editable = "." } +dependencies = [{ name = "requests", extra = ["socks"] }, { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" } }] +[package.optional-dependencies] +plot = [{ name = "matplotlib" }] +[package.dev-dependencies] +test = [{ name = "pytest" }, { name = "requests" }] +[[package]] +name = "requests" +version = "2.32.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [{ name = "urllib3" }] +[package.optional-dependencies] +socks = [{ name = "pysocks" }] +security = [{ name = "pyopenssl" }] +[[package]] +name = "urllib3" +version = "2.0.0" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "pysocks" +version = "1.7.1" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "pyopenssl" +version = "24.0.0" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "matplotlib" +version = "3.9.0" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "pytest" +version = "8.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [{ name = "pluggy" }] +[[package]] +name = "pluggy" +version = "1.5.0" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "scipy" +version = "1.17.1" +source = { registry = "https://pypi.org/simple" } +[[package]] +name = "scipy" +version = "1.18.1" +source = { registry = "https://pypi.org/simple" } +""" + + +def test_runtime_and_development_packages(scan, tmp_path: Path) -> None: + packages = scan.locked_packages(write(tmp_path / "uv.lock", LOCK), tmp_path) + runtime = {(p.name, p.version) for p in packages if p.runtime} + assert runtime == { + ("requests", "2.32.0"), + ("urllib3", "2.0.0"), # a dependency of a dependency + ("pysocks", "1.7.1"), # an extra that a dependency asks for + ("matplotlib", "3.9.0"), # an extra of the project itself + ("scipy", "1.17.1"), # only the version the project uses + } + development = {(p.name, p.version) for p in packages if not p.runtime} + # a dependency group, an extra nobody asks for, a version nobody at run time uses + assert development == { + ("pytest", "8.0.0"), + ("pluggy", "1.5.0"), + ("pyopenssl", "24.0.0"), + ("scipy", "1.18.1"), + } + + +def test_without_a_project_every_package_counts(scan, tmp_path: Path) -> None: + lock = 'version = 1\n[[package]]\nname = "pkg"\nversion = "1.0"\nsource = { registry = "https://pypi.org/simple" }\n' + [package] = scan.locked_packages(write(tmp_path / "uv.lock", lock), tmp_path) + assert package.runtime + + +def test_development_findings_never_block(scan) -> None: + package = scan.Package("uv.lock", "pkg", "1.0", runtime=False) + osv = fake_osv(scan, {("pkg", "1.0"): ["GHSA-crit-crit-crit"]}) + [f] = scan.find([package], osv) + scan.classify([f], [], osv) + assert f.severity == "critical" + assert not f.blocking + assert "| development |" in scan.report([f], [], ["uv.lock"]) + + # --- end to end: real lock files and OSV -------------------------------------------------- needs_network = pytest.mark.skipif( @@ -351,6 +444,19 @@ def test_a_vulnerable_lock_fails_until_excepted(script: Path, tmp_path: Path) -> assert "excepted" in result.summary +@needs_network +def test_a_vulnerable_development_dependency_passes(script: Path, tmp_path: Path) -> None: + repository = project(tmp_path / "devonly", ["packaging>=25"]) + with (repository / "pyproject.toml").open("a", encoding="utf-8") as file: + file.write('[dependency-groups]\ndev = ["jinja2==2.10"]\n') + subprocess.run(["uv", "lock", "--quiet"], cwd=repository, check=True) + git(repository, "add", "--all") + result = run(script, repository) + assert result.returncode == 0, result.stdout + result.stderr + assert "| development |" in result.summary + assert "❌ blocking" not in result.summary + + @needs_network def test_every_tracked_lock_is_scanned(script: Path, tmp_path: Path) -> None: repository = project(tmp_path / "monorepo", ["packaging>=25"])