The Action and CI
Most of watchdep’s work happens in CI, where the code already is: sending the inventory, checking whether the code uses a flawed package, stopping a build, opening fix pull requests and reporting deployments. On GitHub, watchdep-action installs a pinned, checksummed copy of the command line and runs one command. Anywhere else, you call the command line yourself.
watchdep-action
- uses: actions/checkout@v4
- uses: kimathinjoki/watchdep-action@18cbad45072956cbc9c9442b8dffe9e315934499 # v1, pinned by commit SHA
with:
version: 0.1.0 # a release listed in the Action's checksums/
command: gate
args: --fail-on malicious,kev,severe
Pin the Action by a full commit SHA, never by a moving tag, so neither the Action nor the command line it installs can change under you. The current Action, v1, is commit 18cbad45072956cbc9c9442b8dffe9e315934499 and carries command line 0.1.0.
Inputs
| Input | Default | What |
|---|---|---|
command |
(required) | scan, check, fix, gate or deployed |
args |
(empty) | More arguments for the command, for example --image app.tar or --sha ${{ github.sha }} |
working-directory |
. |
The part’s folder |
version |
(required) | The command line release to use. It must be one the Action carries checksums for. There is no default and no “latest”: without it the step stops and names the versions the Action carries. |
server |
(empty) | Your watchdep server’s address, for scan, check, fix and deployed |
token |
(empty) | The part’s token (wdp_...), from a secret, for scan, check, fix and deployed |
github-token |
${{ github.token }} |
The repository’s own token, which fix opens pull requests with |
Output
| Output | What |
|---|---|
exit-code |
The command’s exit code. The step also fails with it. |
The exit codes are the command line’s: 0 fine, 1 a finding meets the gate’s threshold, 2 incomplete (something could not be read or checked, or a source or the server did not answer), 3 a usage error.
The commands
| Command | Needs a server | What it does |
|---|---|---|
scan |
yes | Sends the part’s inventory. Only the inventory leaves the runner. |
check |
yes | Checks whether the code uses each open finding’s package and sends draft verdicts (used, not used, unclear) with file paths and line numbers. A verdict never closes a finding. See The code check. |
fix |
yes | For each finding your workspace set to be fixed by pull request, upgrades the package with the project’s own package manager and opens one pull request per finding per part, or updates the open one. See Fixes. |
gate |
no | Checks against OSV, CISA KEV and EPSS directly and fails the build when a finding meets the threshold (default --fail-on malicious,kev). |
deployed |
yes | Reports a deployment, so production becomes the deployed commit. |
Every flag of every command is in the command line reference.
How the Action verifies the command line
- It picks the one release file for the runner’s system (Linux, macOS or Windows) and architecture (amd64 or arm64).
- It looks up that file’s SHA-256 in
checksums/<version>.txt, committed in the Action’s own repository. A version with no committed checksums stops the step. - It downloads the file from the command line’s release into a fresh folder made for this run under
$RUNNER_TEMP, and compares the SHA-256. A mismatch stops the step and deletes the download; nothing runs. - Only then does it unpack
watchdep, put it on the path and run the command.
There is no “latest”. Adding a version to the Action is a reviewed change to its repository, and pinning the Action by commit SHA pins the checksums with it. The checksums and the release address are fixed in the Action’s own files and never read from the job’s environment, so an earlier step writing to $GITHUB_ENV cannot swap the release or the checksums it is checked against.
Example workflows
Each example uses <commit-sha> where you put the Action’s full commit SHA (v1 is 18cbad4…, above), 0.1.0 for the command line release, https://watchdep.example.com where you put your watchdep server’s address, and a repository secret WATCHDEP_TOKEN holding the part’s token.
Scan and check on every push to production
Sends each push’s inventory, then the code check’s draft verdicts.
# .github/workflows/watchdep.yml
name: watchdep
on:
push:
branches: [main]
permissions:
contents: read
jobs:
watchdep:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: scan
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: check
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
Use the part’s production branch in branches. Inventories of other branches are stored and checked but raise no findings on the application.
The gate on pull requests
Stops a pull request’s build on a malicious release, an exploited-now finding in production scope, or anything severe. No server and no token are needed.
# .github/workflows/watchdep-gate.yml
name: watchdep gate
on: [pull_request]
permissions:
contents: read
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: gate
args: --fail-on malicious,kev,severe
Daily fix pull requests
Opens, or updates, one pull request per finding the workspace wants fixed by pull request. fix needs write access to contents and pull requests, and the project’s package manager set up first, as your own CI does. The repository’s own token opens the pull requests; a person reviews and merges them. watchdep never merges, approves or turns on auto-merge.
# .github/workflows/watchdep-fix.yml
name: watchdep fix
on:
schedule:
- cron: "17 5 * * *"
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
fix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Set up the project's package manager first, as its own CI does.
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: fix
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
The deploy step
In the deploy job, after the deployment succeeds: scan what was deployed (here the built image, saved as app.tar), then report the deployment. From then on, production is the last deployed commit, and a merged fix reads “fix merged, not yet in production” until the deployed commit’s inventory shows the fixed version.
# ... after your image is built and saved (docker save -o app.tar ...) and deployed:
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: scan
args: --image app.tar
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
- uses: kimathinjoki/watchdep-action@<commit-sha>
with:
version: 0.1.0
command: deployed
args: --sha ${{ github.sha }}
server: https://watchdep.example.com
token: ${{ secrets.WATCHDEP_TOKEN }}
Run scan in the same job as deployed, so the deployed commit has an inventory. A deployed commit with no inventory is shown on the part in deep orange.
Other CI systems
The command line is one static binary and needs nothing else on the runner for scan, check, gate and deployed. Download a release in the job and check it against the release’s checksums (Linux amd64 here):
v=0.1.0
curl -fsSLO "https://github.com/kimathinjoki/watchdep-cli/releases/download/v$v/watchdep_${v}_linux_amd64.tar.gz"
curl -fsSLO "https://github.com/kimathinjoki/watchdep-cli/releases/download/v$v/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
mkdir -p bin && tar -xzf "watchdep_${v}_linux_amd64.tar.gz" -C bin watchdep
export PATH="$PWD/bin:$PATH"
Better still, copy checksums.txt into your own repository once and check against that copy, so a changed release cannot pass.
Then, with the server and the part’s token in the CI system’s secret variables:
export WATCHDEP_SERVER=https://watchdep.example.com
export WATCHDEP_TOKEN="$YOUR_SECRET_VARIABLE"
watchdep scan
watchdep check
watchdep gate --fail-on malicious,kev,severe
--server and --token work as well as the variables. To check the operating system packages production will actually run, read the built image: docker save -o app.tar <your image>, then watchdep gate --image app.tar or watchdep scan --image app.tar.
Things to know outside GitHub Actions:
deployedtakes the commit from--sha, falling back toGITHUB_SHA, which only GitHub Actions sets. Elsewhere, pass it explicitly, for examplewatchdep deployed --sha "$CI_COMMIT_SHA"on GitLab.fixopens pull requests on GitHub only. It needsGITHUB_TOKEN(contents and pull requests write) andGITHUB_REPOSITORY(owner/name), andGITHUB_API_URLfor GitHub Enterprise. On other hosts, the fix is still named on every finding.- Exit codes are what the build should act on: 1 a finding meets the threshold, 2 incomplete, 3 a usage or
watchdep.ymlerror (a path that does not exist or is not a folder included). A job that never checked the code out is not clean:gatefinds no dependency files, says “Nothing was checked; this is not a clean result.” and exits 2.gate --allow-incompleteexits 0 instead of 2 when nothing meets the threshold, though its output still says the check did not look at everything. --jsonswitches all output, errors included, to JSON. Colour is used only on a terminal, andNO_COLORturns it off.