Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
71 changes: 60 additions & 11 deletions scripts/dependency_scan.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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"}

Expand All @@ -74,6 +78,7 @@ class Package:
lock: str
name: str
version: str
runtime: bool = True


@dataclass
Expand Down Expand Up @@ -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.

Expand All @@ -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
},
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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}

Expand All @@ -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:
Expand Down
106 changes: 106 additions & 0 deletions tests/test_dependency_scan.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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"])
Expand Down
Loading