Getting started
watchdep takes the inventory of a project (every package at every depth, the runtimes, and the operating system packages of its images) and checks it for known vulnerabilities and compromised releases. You can try it in two steps: first the command line on its own, with no account and no server, then a workspace that keeps findings until a person decides them.
Get the command line
The command line is one static binary per platform (Linux, macOS and Windows, on amd64 and arm64), released with a checksums file on the releases page. The latest is 0.1.0. On Linux amd64:
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
tar -xzf "watchdep_${v}_linux_amd64.tar.gz" watchdep
./watchdep version
Put watchdep somewhere on your path. Other platforms, and building from source: Install.
Try the gate, with no account
In any project folder:
watchdep gate
The gate takes the inventory, checks it against OSV, CISA KEV and EPSS directly, ranks every finding, and exits with a code a CI build can stop on. It needs no server and sends nothing anywhere but those public sources.
By default it fails only on what must be dealt with today: a malicious release in any scope, or a package listed in CISA KEV (exploited now) that ships to production. To be stricter:
watchdep gate --fail-on malicious,kev,severe
What it could not read always comes first. “No findings.” appears only when the check is complete; a file it could not read, an ecosystem it does not support, an image it could not pull or a source that did not answer makes the run incomplete, and it says so. So does a folder with no dependency files at all: “No dependency files found in this folder. Nothing was checked; this is not a clean result.” The exit codes:
| Code | Meaning |
|---|---|
| 0 | Nothing meets the threshold and the check is complete |
| 1 | A finding meets the threshold (this wins over incomplete) |
| 2 | Incomplete: something could not be read or checked |
| 3 | A usage or watchdep.yml error, including a path that does not exist or is not a folder |
To see only what watchdep found, with no network call at all, run watchdep inventory. Every command and flag is in the command line reference.
Sign up
The hosted service keeps one finding per advisory per application, matches every production inventory against its own copy of OSV every night, alerts the right people, and records every decision in a log that cannot be edited. It has not opened yet; when it does, its address will be on this site.
Sign up with your email and a password (or with GitHub or Google, where the service offers them). You get your own workspace and are its owner; others join by invitation. Until your address is verified, every screen says so. More in The hosted service.
Add an application and a part
An application is what you think of as the app, for example Prospec360. Its parts are the repositories, or folders inside one, that make it up: an api and a client, say.
- Add the application from the explorer’s “Add an application” (or from Settings).
- Add a part for each repository or folder. Each part must name its production branch: watchdep never assumes
main. Only inventories of the production branch raise findings on the application; other branches are stored and checked, and a malicious release on any branch is still shown in red. - On the part’s Tokens page, create a token. It starts
wdp_and is shown once, so copy it then. Only its digest is kept.
Send the first inventory
Where the code is (your laptop, or CI), from the part’s folder:
export WATCHDEP_SERVER=https://watchdep.example.com # the server's address
export WATCHDEP_TOKEN=wdp_...
watchdep scan
Only the inventory leaves the machine; the code never does. On your own machine you can store the token once instead, with watchdep login --server https://watchdep.example.com --token wdp_....
The server checks the inventory against its OSV mirror (syncing the ecosystems it needs the first time) and shows findings within a minute. Until a part sends an inventory, the screens say “Not looked yet”, never clean.
Where to go next
- The Action and CI: send an inventory on every push, gate pull requests, and open fix pull requests.
- Connecting GitHub: let the server fetch dependency files itself, with read-only access.
- Levels and lanes and Decisions: what severe means, and how a person closes a finding.
- Alerts: who is told, how and when.
- watchdep.yml: the production branch, runtimes, databases and images no lockfile states.
- The code check and Fixes: whether your code uses the flawed package, and pull requests that upgrade it.