watchdep
Sign inSource

watchdep / How it works

From the inventory to the decision.

watchdep watches every layer of an application’s dependencies: the packages your lockfiles pin, the packages those packages bring in, the runtimes and databases production runs on, and the operating system packages inside your container images. It has three pieces. The command line tool takes an inventory where the code already is, on your machine or in CI. The server keeps a copy of the public advisory data, matches every inventory against it every night, ranks what it finds, tells the right people, and keeps each finding until a person decides it. The GitHub Action runs the command line tool in your workflows. This page walks through each step, in the order it happens.

Applications and parts

An application is what you think of as the app. Its parts are the repositories, or folders inside a repository, that make it up: an API, a web client, a worker. watchdep shows findings per application, across every part, so the same flawed package in three services is one finding with three places, not three alerts.

Each part names its production branch when it is created. watchdep never assumes main.

The inventory

An inventory is what a part contains at one commit, and how watchdep found out. You can see one at any time with watchdep inventory, which makes no network call at all.

What it reads. watchdep walks the part’s folder, skipping version control folders, installed dependencies (node_modules, vendor, .venv and the like) and tool caches, and offers every file to the readers of OSV-SCALIBR, the open source inventory library. Every attempt is recorded: the files read, with how many packages each gave, and the files that could not be read, with the reason. A folder with no dependency files at all is never clean: watchdep gate says “Nothing was checked; this is not a clean result.” and the run is incomplete.

  • Symbolic links are followed only inside the part’s folder. A link to a file inside it is read under the link’s own path; a link to a folder inside it is not entered, since that folder is walked under its own path. A link that leads outside the folder, or nowhere, is never followed: when it is a folder, or a dependency file, Dockerfile or version file, it is listed as not read and the result is incomplete.

  • Lockfiles first. A lockfile’s exact versions win over a manifest’s ranges. A manifest with no lockfile in its folder or any folder above it (a package.json with no package-lock.json, yarn.lock, pnpm-lock.yaml or bun lockfile; a Gemfile with no Gemfile.lock) is listed as unpinned, with its declared ranges. Ranges are not checked, so the result is incomplete and the output says to add a lockfile.

  • Unsupported ecosystems are named, never skipped quietly: a build.sbt, a deps.edn or a shard.lock is listed with its ecosystem, and the result is incomplete.

  • Runtimes and databases come from .ruby-version, .nvmrc, .node-version, .python-version, .tool-versions, and the optional watchdep.yml, which can also name databases, hosting platforms and base images. A value that is not a version, such as lts/iron, is listed as written: watchdep never guesses a version. When two files disagree about a runtime, both are shown.

  • Images and operating system packages. watchdep reads the package database files (dpkg, apk, RPM) and the distribution’s release file from an image, without running anything in it. It can read a local image archive or pull from a registry (--image), or read a folder laid out like a root filesystem (--rootfs); a --rootfs folder with no package database in it is listed as not read. Without --image, it lists the base image of each Dockerfile’s final stage and the images named in watchdep.yml (a --rootfs folder does not stand in for them, since nothing says which image it came from). An image it cannot pull is listed as not read, with the reason. A distroless image with no package database is read and says so.

Dependency paths. For lockfiles that record which package needs which (Bundler, npm, yarn, pnpm, Composer, poetry, uv, Cargo, NuGet), watchdep keeps the five shortest paths from one of your direct dependencies to each package (“rails, which uses actionpack, which uses rack”) and counts the rest. Where a file records no paths, the package says “path not recorded”. watchdep never invents one.

Relation and scope. Each package is direct, transitive, or unknown when the file does not say. Its scope is production, or development when only development and test groups reach it. Scope comes only from what the files record. When the file that names the groups is missing, the package counts as production, the louder answer, and is marked as not recorded.

The full shape is in the inventory format, and every key of the optional file in watchdep.yml.

How an inventory reaches the server. Either watchdep scan, run in CI with the part’s token, sends it; or the server takes it itself through the GitHub App, on every push to the production branch and every night, fetching only the dependency files the same readers would read (GitHub, CI). Both routes give identical inventories from the same files.

What counts as production. By default, production is the head of the part’s production branch. Once your deploy step reports deployments (watchdep deployed), production is the last deployed commit. Inventories of other branches are stored and shown, but raise no findings on the application, with one exception: a malicious release on any branch is alerted at once, because its install scripts have already run on someone’s machine or in CI.

Sources

The server reads every public source on its own schedule and records each one’s health.

Source How often What it gives
OSV every hour advisories and affected versions for every ecosystem, including GitHub’s, the language databases, Debian, Ubuntu, Alpine and other distributions, and OpenSSF’s malicious packages
GitHub Advisory Database every hour unreviewed advisories that name a package before its affected versions are known
CISA Known Exploited Vulnerabilities every 6 hours which CVEs are being exploited now, and since when
EPSS every day the probability each CVE is exploited in the next 30 days
NVD every day, and after a production inventory with runtimes CVEs for each runtime and database version
endoflife.date every day, and after a new production inventory brings something it has not answered for when each release line stops getting security fixes
Node.js, Rails and PostgreSQL security announcements; the oss-security list every hour problems named before versions are mapped

OSV is mirrored in full, one export per ecosystem your inventories use, rather than asked package by package. Every production inventory is matched again every night with no network call per package, so a new advisory against a lockfile nobody touched is found overnight.

Runtimes and databases (Node.js, Ruby, Python, PHP, Go, PostgreSQL, MySQL, Redis, MariaDB, MongoDB, Elixir, Deno, Rust) are checked against NVD by their exact version. A version file that names only a line, such as 20, is shown as not checked, with a note to give the exact version in watchdep.yml.

End of life. For runtimes, databases and the major frameworks (Rails, Django, Laravel, Symfony, Spring Boot, React, Angular, Vue, Next.js, Nuxt), a release line past the end of security support, or within 90 days of it, is a high finding with the line to move to.

Two lanes. A confirmed finding means the exact version in use is listed as affected. An early warning means a source has named a package, runtime or database you use, but no affected versions are published yet. Early warnings are matched by exact package name, never by fuzzy text; the oss-security list matches only package names of five characters or more, as whole words. They are labelled unconfirmed and kept in their own view, so they never read as confirmed. When the details arrive, an early warning becomes a confirmed finding (same history) or is withdrawn; with no details in 30 days, it is withdrawn.

Silence is not safety. A source with no good sync in 24 hours is shown in deep orange on every screen and alerted to the workspace’s owners and admins. A failed sync keeps the last good data.

The build gate, watchdep gate, needs no server: it asks OSV, CISA KEV and EPSS directly and fails the build on what you choose (CI).

Matching

  • Each exact version is compared with each advisory’s affected ranges by the ecosystem’s own version rules (RubyGems, PyPI, Maven, Debian and so on). Debian packages are checked under their source package (liblzma5 as xz-utils), Alpine packages under their origin.
  • Advisories that name each other are one finding. A CVE, its GitHub advisory and a distribution’s entry for it join into one finding per application, shown by its CVE where it has one.
  • Malicious releases are recognised by an OpenSSF malware report (an id starting MAL-) or by GitHub’s “embedded malicious code” class.
  • Each finding lists every place it appears: part, file or image, package, version, scope, dependency paths, and the fix, which is the lowest fixed version on the major line you are on, or the lowest overall marked as a new major version, or “no fixed version published”.
  • A place is marked gone only where the new inventory actually looked. A lockfile that became unreadable can never make a finding read as fixed.

Ranking

Four levels: severe, high, medium and low. Severe is narrow on purpose: exploited now, a malicious release, or critical and likely to be exploited. Missing data errs toward the louder answer, with a label: a critical finding with no exploit score yet is severe and marked provisional until the score arrives. Development-only findings drop one level, except malicious ones. The command line tool and the server rank with the same rules, tested against the same cases. The full table is in levels and lanes.

Alerts

Each person chooses, per level, how they are told: immediately by email, in a daily digest, in a weekly digest, or on screen only. The defaults are severe immediately, high daily, medium weekly and low on screen.

  • A finding alerts each person once, again when its level goes up, and again if it reopens. A level going down is quiet.
  • A malicious release is always told immediately to everyone in the workspace, whatever they chose.
  • A workspace can add one signed webhook, which Slack and Teams incoming webhooks can show as it is.
  • An email that fails, or a copy with no email settings, is recorded and shown on the finding. Nothing is dropped silently.

More in alerts.

Decisions and the log

A finding stays until a person decides it, or production shows it fixed.

  • Acknowledge: seen, being looked at.
  • Accept the risk until a date, at most a year away, with a reason. On that date the finding reopens.
  • Not affected, with a reason. watchdep check can help: run where the code is, it looks for the package’s imports and the affected functions an advisory names, and sends back a draft verdict (used, not used or unclear) with file paths and line numbers. A verdict is a draft; it never changes a finding’s state (code check).

A decision covers only the places present when it was made. If the same advisory later appears in a new part, file or dependency path, the finding reopens for the new places. Fixed means production no longer has an affected version; a merged pull request is not fixed until production shows it.

Every change, by a person, the command line tool, the system, a host application or an agent acting for a person, writes an entry to the finding’s log in the same transaction. The log is append-only, and the database refuses to edit or delete it. More in decisions, the API and agents.

Fixes

By default watchdep names the fix on every finding. For any level, an application can choose to open a pull request instead.

Pull requests are opened by watchdep fix in your own CI, through the GitHub Action, with that repository’s own token. The server only says what to upgrade: it never holds write access and never runs a package manager. watchdep fix upgrades a direct dependency, or uses the package manager’s own override for one that comes in through another package (npm, yarn, pnpm, bun, Composer, Bundler, pip, poetry, uv, pipenv, Go modules, Cargo, and Dockerfile base images pinned by digest). It takes a fresh inventory to check the fix landed, and opens one pull request per finding per part. The description says why it matters and what changes. A person merges every pull request: watchdep has no merge, approve or auto-merge call at all. More in fixes.

“No findings” never means “did not look”

Every gap is shown, in deep orange, and never read as clean:

  • a dependency file that could not be read, with the reason;
  • an ecosystem present that no reader supports, or that no advisory source covers;
  • a manifest with no lockfile;
  • an image that could not be pulled or read;
  • a source that did not answer, or has not synced in 24 hours;
  • a part that never sent an inventory.

An incomplete gate exits with its own code, 2, never 0 (command line). On screen, “No open findings. Every part’s production inventory was checked.” appears only when it is true. Otherwise the screen says what was not looked at, and that this is not a clean result.

Ready to try it? Start with getting started.