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
6 changes: 6 additions & 0 deletions .github/actionlint.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
paths:
.github/workflows/dependency-scan.yml:
ignore:
# GitHub documents job.workflow_repository and job.workflow_sha (the repository and
# commit of the workflow file), but actionlint doesn't know them yet
- 'property "workflow_(repository|sha)" is not defined in object type'
12 changes: 12 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
# a new release waits a week, so a compromised one is likely found and pulled first
cooldown:
default-days: 7
groups:
github-actions:
patterns: ["*"]
56 changes: 56 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: CI

on:
pull_request:
push:
branches: [main]

# nothing by default: each job asks for the permissions it needs
permissions: {}

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
lint:
name: Lint
runs-on: ubuntu-slim
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false

- name: Check the workflows with actionlint
run: uvx --from actionlint-py==1.7.12.25 actionlint

- name: Audit the workflows with zizmor
run: uvx zizmor@1.32.0 --offline .github

- name: Lint and check the format of the Python code with ruff
run: |
uvx ruff@0.17.5 check scripts tests
uvx ruff@0.17.5 format --check scripts tests

test:
name: Test
runs-on: ubuntu-slim
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false

- name: Run the tests
run: uv run --no-project --python 3.13 --with pytest==9.* --with pyyaml==6.* pytest -v
52 changes: 52 additions & 0 deletions .github/workflows/dependency-scan.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: Dependency scan

# Checks the Python packages locked in uv.lock against the OSV database of known
# vulnerabilities, on every pull request and in the merge queue. An organization ruleset requires it ("Require workflows to
# pass before merging"), so it runs in the repository of the pull request, with that
# repository's files and token: see README.md.
#
# A ruleset ignores the filters of the triggers (branches, paths, types), so the job checks
# by itself whether there is anything to scan. The scan is scripts/dependency_scan.py of this
# repository, taken from the same commit as this file.
on:
pull_request:
merge_group:

permissions:
contents: read

jobs:
scan:
name: Dependency scan
runs-on: ubuntu-slim
timeout-minutes: 15
steps:
# the repository of the pull request, which the scan reads
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

# The script of the scan. With a ruleset, this workflow runs in another repository:
# `job.workflow_repository` and `job.workflow_sha` name this repository and the commit
# of this file, which the ruleset pins, so the script can't differ from the reviewed one.
# It goes next to the files of the pull request, untracked, so the scan doesn't see it.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ job.workflow_repository }}
ref: ${{ job.workflow_sha }}
path: .dependency-scan
sparse-checkout: scripts
persist-credentials: false

# runs the script with the Python of its inline metadata; no cache: the job must not
# restore files that another run could have written
- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false

- name: Check uv.lock against OSV
env:
EXCEPTIONS_FILE: .github/vulnerability-exceptions.toml
# --no-config: the uv settings of the repository (uv.toml, [tool.uv]) are not for the
# script, and --no-project: the repository's project isn't needed to run it
run: uv run --no-config --no-project .dependency-scan/scripts/dependency_scan.py
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
__pycache__/
.pytest_cache/
.ruff_cache/
93 changes: 93 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# security-workflows

GitHub Actions workflows that organization rulesets require in Algorithmiq's repositories.
They are public so that one ruleset can run them in every repository, public, internal or
private: a ruleset can only run a workflow whose repository is at least as visible as the
repositories it targets.

This repository holds generic workflow code only. It must never contain secrets, names of
private repositories or packages, or other organization-specific details: those come from the
repository the workflow runs in.

## Dependency scan

[`dependency-scan.yml`](.github/workflows/dependency-scan.yml) checks the Python packages
locked in `uv.lock` against the [OSV](https://osv.dev) database of known vulnerabilities, on
every pull request and in the merge queue.

### How it works

A ruleset runs the workflow in the repository of the pull request, with that repository's
files and `GITHUB_TOKEN` (read-only), and ignores the filters of its triggers. The scan is
[`scripts/dependency_scan.py`](scripts/dependency_scan.py) of this repository: the job checks
it out from the commit of the workflow file (`job.workflow_repository`, `job.workflow_sha`),
which the ruleset pins, and runs it with `uv run` (Python 3.13, standard library only, as its
inline metadata says). The script:

1. finds the `uv.lock` files that git tracks. With none, it passes with a notice;
2. reads the packages of each one that come from a package index, with their versions:
every extra and dependency group, whatever the index. The project itself and packages from
git, a URL or a local path are left out: they have no version on PyPI to look up;
3. asks OSV which vulnerabilities affect each name and version, and reads their records. OSV
lists a vulnerability once per database (GHSA, PYSEC, …): the GHSA record is kept, as it
carries GitHub's severity;
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.

### What leaves the repository

Only the name, the ecosystem (`PyPI`) and the version of each locked package, sent to
[OSV's API](https://google.github.io/osv.dev/post-v1-querybatch/) with Python's default
User-Agent; then the identifiers of the vulnerabilities found, to read their records. That
includes packages from private indexes: OSV matches by name, whatever the index. If a private
package shares its name with a public one that has advisories, the findings of the public one
are reported: record them as exceptions.

### Exceptions

A finding that is acceptable for a while (no fix yet, code that is never reached, a false
positive) goes in `.github/vulnerability-exceptions.toml` of the repository, one table per
vulnerability:

```toml
[[exception]]
id = "GHSA-xxxx-xxxx-xxxx" # the GHSA identifier, or any alias that the job summary shows
issue = "https://github.com/<owner>/<repository>/issues/<number>" # the issue that approves it
reason = "The vulnerable function is only used by the test suite."
```

All three keys are required; any other key is an error. Exceptions are reviewed in pull
requests like any other change, and the history of the file shows who approved what. An
exception that no longer matches a finding gives a warning: remove it.

### Setting it up (organization owners)

1. **Settings → Repository → Rulesets → New branch ruleset**, enforcement **Evaluate** at first.
2. **Target repositories**: by custom property, for example the repositories that must have a
dependency scan. **Target branches**: the default branch. The rule blocks direct pushes, so
only target branches that change through pull requests.
3. Rule **Require workflows to pass before merging**: repository
`Algorithmiq/security-workflows`, workflow `.github/workflows/dependency-scan.yml`, and the
**full commit SHA** of a reviewed version as the reference, not a branch: a change here
reaches every targeted repository only when the ruleset moves to it.
4. Once the runs in Evaluate mode look right, switch the enforcement to **Active**. Pull
requests opened before the ruleset existed run the workflow on their next push.

To move to a new version: review the change here, then update the SHA in the ruleset.

## Development

The tests run `scripts/dependency_scan.py` as the workflow does:

```sh
uv run --no-project --with pytest --with pyyaml pytest
```

The end-to-end tests lock small projects with known vulnerable packages and need the network
(PyPI and OSV); set `OFFLINE=1` to skip them. CI also runs ruff, actionlint and zizmor. Changes need a pull request and a review:
every targeted repository runs this code.
1 change: 1 addition & 0 deletions ruff.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
line-length = 100
Loading
Loading