Skip to content

feat: add a dependency scan for organization rulesets - #1

Merged
robertodr merged 3 commits into
mainfrom
feat/dependency-scan
Nov 19, 2026
Merged

robertodr merged 3 commits into
mainfrom
feat/dependency-scan

Conversation

@robertodr

@robertodr robertodr commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

🤖 AI text below 🤖

Adds the dependency scan that an organization ruleset will require on pull requests and in the merge queue of the repositories that need one.

Changes

  • .github/workflows/dependency-scan.yml checks out scripts/ of this repository at the commit of the workflow file (job.workflow_repository, job.workflow_sha), which the ruleset pins, and runs scripts/dependency_scan.py with uv run (inline metadata: Python 3.13, no dependencies).
  • The script reads the packages of every uv.lock that git tracks (those from a package index, with all extras and groups), and asks OSV's batch API about each name and version. Only name, ecosystem and version are sent, with Python's default User-Agent. It passes with a notice when there is no uv.lock.
  • The severity comes from the GHSA records that OSV mirrors. OSV's duplicate records of one vulnerability (GHSA, PYSEC) are merged, keeping the GHSA one. A finding blocks when it is high, critical or of unknown severity, unless .github/vulnerability-exceptions.toml lists it (id, issue, reason, all required). Moderate and low findings, withdrawn advisories and excepted findings are listed in the job summary without failing. Exceptions that match nothing give a warning. If OSV can't be read, the job fails.
  • tests/test_dependency_scan.py: the exceptions file, which findings block, merging aliases, which packages are looked up and exactly what is sent to OSV, the escaping of annotations, and end-to-end runs on real lock files (a clean lock passes; jinja2==2.10 fails until excepted; a second tracked uv.lock is scanned; a repository without one passes).
  • .github/workflows/ci.yml: actionlint, zizmor, ruff and the tests. .github/actionlint.yaml ignores job.workflow_*, which actionlint doesn't know yet. .github/dependabot.yml: weekly action updates with a week of cooldown.
  • README.md: how the scan works, what blocks, what leaves the repository, the exceptions file and the ruleset setup.

Validation

  • 26 tests pass, and actionlint, zizmor and ruff report nothing.
  • On a test lock with 65 known vulnerabilities, the script finds the same 65 as uv audit 0.13.7.
  • On this pull request, the workflow checks out scripts/ at the right commit and passes with a notice (this repository has no uv.lock). The run in another repository through a ruleset comes next, in Evaluate mode.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this shouldn't be here

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI text below 🤖

Removed in 322b9e1, and .gitignore now ignores __pycache__/, .pytest_cache/ and .ruff_cache/.

Comment thread .github/workflows/dependency-scan.yml Outdated
# The script is the body of this step, so the workflow is a single file: a ruleset
# runs this file in another repository, where no other file of this one exists.
shell: uv run --no-project --python 3.13 python {0}
run: |

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can't the script be saved in its own file? Maybe with inline dependencies for uv run to read them?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI text below 🤖

Yes, in 322b9e1: the scan is scripts/dependency_scan.py, with inline metadata that uv run reads (requires-python = ">=3.13", no dependencies: it only uses the standard library).

The catch was that a ruleset runs the workflow in the target repository, where this repository's files don't exist. The workflow now checks out scripts/ from job.workflow_repository at job.workflow_sha: the repository and commit of the workflow file, which GitHub documents for this use. The ruleset pins that commit, so the script always comes from the same reviewed commit as the workflow, and there's still a single pin. uv runs the script with --no-config, so a scanned repository's uv settings don't change how the script runs (they still apply to uv audit).

actionlint doesn't know job.workflow_* yet: .github/actionlint.yaml ignores that one message for this file. The checkout is verified only when a ruleset runs the workflow in another repository, in Evaluate mode.

dependency-scan.yml runs `uv audit` on every uv.lock that git tracks,
looks up the severity of each finding in GitHub's advisory database,
and fails on high, critical and unknown-severity findings that
.github/vulnerability-exceptions.toml doesn't approve. An organization
ruleset requires it on pull requests and in the merge queue; it runs in
the target repository, so the script is the body of a step and the
workflow is a single file.

The tests load the script from the workflow, and lock small projects
with known vulnerable packages to run it end to end. CI runs them with
actionlint, zizmor and ruff; Dependabot updates the actions.

Assisted-by: Pi:claude-opus-5-5
The scan is now a script of its own, with inline metadata that uv run
reads (Python 3.13, no dependencies). The workflow checks it out from
job.workflow_repository at job.workflow_sha, the commit of the workflow
file that the ruleset pins, so the script and the workflow can't
diverge. uv runs it with --no-config: the uv settings of the scanned
repository apply to `uv audit`, not to running the script.

Also drops a .pyc file that was committed by mistake, and adds a
.gitignore and ruff's line length.

Assisted-by: Pi:claude-opus-5-5
The script reads the packages of each uv.lock itself and asks OSV's
batch API about their names and versions, with Python's default
User-Agent: nothing else leaves the runner. The severity comes from the
GHSA records that OSV mirrors, so GitHub's API and the token are no
longer needed, and OSV's duplicate records of one vulnerability (GHSA,
PYSEC) are merged, the GHSA one kept.

This drops the dependency on `uv audit`, a preview feature whose
output could change between uv releases, and on the uv user agent,
which describes the runner. The results match `uv audit` on the test
projects.

Assisted-by: Pi:claude-opus-5-5
@robertodr
robertodr force-pushed the feat/dependency-scan branch from 58b4bf1 to 6ebd9e8 Compare November 19, 2026 13:03
@robertodr
robertodr merged commit c3421d9 into main Nov 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant