watchdep / Trust
What watchdep reads, stores and never touches.
A tool that watches your dependencies sits close to your code, so this page says exactly what watchdep reads, what it sends, what it stores and what it never touches. It covers the command line tool and the hosted service, which is the watchdep server running in its hosted mode. Everything here describes the code as it is built today.
In short
- The server never reads your source code, never holds write access to a repository, never runs a package manager and never merges a pull request.
- What leaves your machine for the server is an inventory: package names, versions, file paths and the commit. Never file contents.
- The code check runs on your machine. By default it sends back file paths, line numbers and a short note, not code.
- Nothing reads across workspaces: every screen, API call and agent sees only its own workspace.
- Severe and high findings are reviewed by Claude (Anthropic) and Gemini (Google): the advisory and your dependency inventory go to them, with your names replaced and never your code. An owner turns it off in one place (AI review of findings).
- No analytics and no third-party scripts or fonts, here or in the service.
What the command line tool reads, and what it sends
watchdep inventory reads the part’s folder and makes no network call. It reads dependency files (lockfiles and manifests), runtime version files, Dockerfiles, watchdep.yml, and the branch and commit from the .git folder, without running git. It skips installed dependencies (node_modules, vendor, .venv and the like) and never reads your source files.
watchdep scan takes the same inventory and sends it to your watchdep server with the part’s token. The inventory holds:
- the part’s folder name, branch and commit, the production branch if
watchdep.ymlpins one, the tool’s version and when it was taken; - for each package: its ecosystem, name, version (or declared range), package URL, scope, relation, the path of the file it came from relative to the part, and up to five dependency paths made of package names and versions;
- operating system packages with their distribution and image, runtimes and databases with their versions and the file that named them, and image references;
- which files were read (path, ecosystem, reader, package count), which could not be read and why, unsupported files, manifests with no lockfile, and runtime versions that disagree.
Never the contents of a file. The full field list is in the inventory format. The token is kept in a credentials file only your user can read.
watchdep gate checks the inventory with no watchdep server. To do so it sends the ecosystem, name and version of every package with an exact version, and every operating system package, to OSV’s API, fetches the matching advisories by id, downloads CISA’s catalogue of exploited vulnerabilities whole, and sends the CVE ids of its findings to the EPSS API. With --mirror, OSV is answered from a local copy instead.
Images. scan and gate pull the base images your Dockerfiles and watchdep.yml name, using the machine’s own registry credentials, and read only their package databases. Nothing in an image is run.
The code check
watchdep check runs where your code already is, on your machine or in CI. It asks the server for the part’s open findings, reads your source files locally (by language, at most 1 MB each, skipping installed dependencies and build output), and looks for imports of each affected package and calls to the functions an advisory names.
For each finding it sends back a draft verdict (used, not used or unclear), a one-paragraph reason, and at most 20 pieces of evidence. Each piece of evidence is a file path, a line number and a note: “imports rack”, or “calls” followed by the name of a function the advisory named. No code.
- Snippets are sent only when the workspace’s owner turns on “Code check snippets” (off by default, and only the owner can change it). Then each piece of evidence also carries its line and two lines either side, which the server stores and shows on the finding page.
- The API for host applications and the agent tools return evidence without snippets.
--dry-runprints the verdicts and sends nothing back.- A verdict never changes a finding’s state. A person decides.
The assisted code check, with your own key
With watchdep check --assist, the command line tool asks the model you choose to sharpen each verdict: Anthropic’s Claude, Google’s Gemini or an OpenAI model (--provider, --model). The request goes from your machine straight to that provider’s API, with your own key (ANTHROPIC_API_KEY or your Anthropic login, GEMINI_API_KEY, OPENAI_API_KEY). For each finding it sends:
- the advisory’s id and summary;
- the package’s ecosystem, name, version and relation;
- the function names the advisory lists as affected;
- each piece of evidence (path, line and note) with the lines around it, three either side;
- the search’s draft verdict and reason.
The watchdep server never holds or sees the key you use here, and never sees the code the assistant reads. Google and OpenAI are asked to keep no copy of the request. The server stores only whether a verdict was assisted and by which model. The assistant can never turn a use the search found into “not used”; that becomes unclear.
What the server stores
All of it lives in the service’s own database.
| What | Stored |
|---|---|
| People | name, email address, password as a one-way hash, linked GitHub or Google identity (the provider’s id and email), authenticator secret, and sessions with the IP address and browser of each sign-in |
| Workspaces and access | workspace names and settings, memberships and roles, invitations (email and role) |
| Applications and parts | names, production branch, repository, folder and stack |
| Tokens | project, API and agent tokens as SHA-256 digests only, with the first ten characters of project and API tokens to tell them apart, and when each was last used |
| Inventories | each inventory as it was sent, and one row per package |
| Findings | findings, their places, decisions and the log |
| Code checks | verdict, reason, evidence (paths, line numbers, notes; snippets only when allowed), the commit, whether assisted and the model |
| Alerts | each alert with its channel, state and any error; each person’s alert settings; the webhook’s address and secret |
| GitHub | the App’s credentials, and each installation with its account name and a short-lived installation token |
| Fixes and deployments | fix settings, pull request records (number, address, branch, state), deployed commits |
| Agents | registered agent clients (name and return addresses), connections (person, workspace, scopes) |
Shared public data (advisories, the OSV mirror, exploited-now and exploit-probability scores, end-of-life dates, early warnings from feeds, NVD answers, source health) is stored once for the whole copy. No record in it names a workspace.
Encrypted at rest: authenticator secrets, the webhook secret, the GitHub App’s client secret, private key and webhook secret, and installation tokens. The keys are derived from the server’s SECRET_KEY_BASE, unless you give your own (WATCHDEP_ENCRYPTION_*). Tokens and invitation links are kept only as SHA-256 digests; passwords only as hashes. Inventories, findings and the log are not encrypted by watchdep: protect the database as you would any other.
What the server never does
- Never reads source code. It receives inventories. Through GitHub it fetches only dependency files (below). The code check runs only in the command line tool, where the code already is.
- Never holds write access. The GitHub App asks for read access only. Pull requests are opened by
watchdep fixin your own CI, with that repository’s own token. - Never runs a package manager. The only program it runs is the watchdep binary it carries. When
watchdep fixupgrades a package, your package manager runs on your CI runner, not on the server. What the server askswatchdep fixto change is checked first: a file outside the repository, a package name that could read as a flag, or a version that is not a plain version is refused. The package manager runs with install scripts off and with no token or other secret of the job in its environment (fixes). - Never merges a pull request. Neither the server nor the command line tool has a merge, approve or auto-merge call. A person merges.
- Never holds your command line tool’s key. The key
watchdep check --assistuses stays on your machine. The server’s own AI review uses the service’s keys, or a key a workspace’s owner chose to store in Settings, AI review (encrypted, below).
The same holds in hosted mode.
AI review of findings
The server reviews severe and high findings with two models, Claude Opus 5.5 (Anthropic) and Gemini 4 Carbon (Google), and any open finding when someone asks. A review only adds attention: it never lowers a level, closes, accepts or decides anything, and a person decides whether to raise a level it suggests.
What is sent, only while AI review is on, for a finding being reviewed, to the workspace’s chosen providers:
- the advisory’s text and ids, and the ids, summaries and fixed versions of related advisories;
- the affected package, its version and ecosystem, its dependency paths (package names and versions) and its scope;
- the level watchdep gave it and why, and its CISA KEV and EPSS facts;
- the part’s other packages (names and versions only), runtimes and databases;
- code check results: verdicts, file paths and line numbers, and the few lines around each only where the workspace’s owner switched snippets on.
Never sent: your source code (the server never has it), and any name of yours. The provider sees “application A, part 1”, never the workspace’s, an application’s, a part’s or a person’s name, an email address, a commit or a repository address. Google is asked to keep no copy of the request (store: false); so is OpenAI. Anthropic’s and Google’s paid APIs do not train on what they are sent.
Turning it off: the workspace’s owner, in Settings, AI review. Off stops all sending at once.
Your own keys: an owner may store their own Anthropic, Google or OpenAI key so reviews run on their account. It is encrypted at rest, shown afterwards only by its last four characters, never logged, sent only to its own provider, and deleted with the workspace.
Shared analyses: the part of a review that is about the advisory alone (what the flaw does, whether its fix is complete) is made once and reused for every workspace. It is built only from public advisory data, so it carries nothing of any workspace.
The GitHub App
Connecting through GitHub is optional; watchdep scan in CI gives the server no access to your repositories at all.
- Permissions: contents read and metadata read, and the push event. Nothing else, and no write.
- GitHub cannot limit an App to some files, so the App could read every file in the repositories you choose. watchdep fetches only dependency files: lockfiles, manifests, runtime version files, Dockerfiles and
watchdep.yml. - How it decides what to fetch: it reads the repository’s file list (paths and sizes, never contents), asks the watchdep binary which of those paths its readers would read, and fetches only those, at most 2,000 files of at most 25 MB each. They are written to a temporary folder that is removed once the inventory is taken. It also pulls public base images named in Dockerfiles and
watchdep.yml. - The calls it makes: create the App from its manifest, look up an installation and create its short-lived token, list the installation’s repositories, read a branch’s head commit, read the file list, and read a file. No other calls, and none that write to a repository.
- A push notification whose signature does not match is refused before it is read. An installation is claimed for a workspace only with a link signed for that workspace and person in the last hour.
- On the hosted service, the App is watchdep’s own; you install it only on the accounts and repositories you choose.
More in GitHub.
Outside services
These are every outside service watchdep calls, and what each call carries.
| Service | Called by | What is sent |
|---|---|---|
| OSV data exports | the server, every hour | nothing about you: it downloads the whole export of each ecosystem in use, by ecosystem name |
| OSV API | watchdep gate only |
the ecosystem, name and version of each package; advisory ids |
| GitHub Advisory Database | the server, every hour | nothing about you: it lists recently updated unreviewed advisories |
| NVD | the server | the product and exact version of each runtime and database in production, such as Node.js 20.11.1 |
| CISA KEV | the server and watchdep gate |
nothing: the whole catalogue is downloaded |
| EPSS | the server; watchdep gate |
the server downloads the whole daily file; gate sends the CVE ids of its findings |
| Anthropic (Claude) and Google (Gemini) | the server, while AI review is on | for a finding being reviewed: what AI review of findings lists, with names replaced; never code |
| OpenAI | the server, only for a workspace that stored its own OpenAI key and chose it | the same |
| Anthropic, Google or OpenAI | watchdep check --assist, from your machine, with your key |
the evidence and the lines around it (the assisted code check) |
| endoflife.date | the server | the names of the runtimes, databases and frameworks in use, such as nodejs or rails |
| Node.js, Rails and PostgreSQL security feeds; the oss-security list | the server, every hour | nothing: fixed public feeds |
| Container registries | scan, gate, and the server’s GitHub route |
the base image references being pulled |
| GitHub API | the server, only when the App is connected | as above |
| Anthropic’s API | the command line tool, only with --assist |
as above, with your key |
Requests to the sources carry a fixed user agent and nothing about the person or the project: one naming watchdep-server from the server’s own syncs, and watchdep-cli/<version> (+https://github.com/kimathinjoki/watchdep-cli) from the command line tool, including the copy of it the server runs to download the OSV exports. Keys for NVD and GitHub only raise those services’ rate limits.
Beyond these, the service talks only to its mail service, your workspace’s webhook if you set one, and GitHub or Google when you sign in with them.
Webhooks and private networks
- Each workspace may have one webhook. Every post is signed with HMAC-SHA256 over the timestamp and body, with a secret shown once and stored encrypted. Posts carry the user agent
watchdep-webhook. - Before each post, the webhook’s host is resolved. A private, loopback or link-local address is refused, unless the workspace’s owner ticked “Allow private network addresses” for an internal chat. Admins cannot change that setting.
- In hosted mode, a webhook never reaches a private network, whatever was ticked.
More in alerts.
Host applications and agents act only as people
- Host applications use a workspace API token an owner or admin creates. It reads its own workspace only, and writes decisions only if it was given that permission. Each decision names the person it is made for; the log records it as that person, via the host (“Jane Smith, via Prospec360”), and never claims watchdep checked who they are. When the person is a member, their role applies, so a viewer cannot decide through a host. A host never reaches settings, members, tokens, connections, fix settings or alerts (API).
- Agents (Claude Code, Claude Desktop or any MCP client) connect through the person’s own sign-in, and the person ticks what the agent may do: read always, decide only if ticked (off by default). The agent acts as that person, with their role, in the one workspace it was connected to, and the log says so (“D. Kim, through Claude Code”). No agent tool opens pull requests or changes settings, members, tokens or alerts. Access tokens last an hour; refresh tokens 30 days, each used once. Disconnecting is immediate, and a person who leaves the workspace takes their agents with them (agents).
- The log. No finding changes state without an entry in its log, written in the same transaction. The log is append-only: the database itself refuses to edit or delete an entry.
Isolation between workspaces
Every screen, API call, agent tool and search reads through the current workspace. On top of that, every workspace-owned record refuses to load inside a request for another workspace, so a query that forgot its scope answers “not found” rather than showing someone else’s data. A test requests every screen that takes an id, with every method, as a member of another workspace, and requires “not found” and no change.
Deleting a workspace deletes everything
The owner alone can delete a workspace, by typing its name. Everything of the workspace goes, in one transaction: applications, parts, tokens, inventories, findings, places, decisions, the log, code checks, pull request records, deployments, alerts, settings, the webhook, GitHub installations, invitations, memberships, API tokens and agent connections. People keep their accounts. Every other workspace’s log stays append-only: the database deletes a log entry only while its own workspace is being deleted.
The hosted service
The hosted service is the watchdep server in its hosted mode. Sign-up needs a verified email address, each person gets their own workspace, the GitHub App is watchdep’s own, and a webhook never reaches a private network. Everything else on this page holds unchanged. More in the hosted service.
No tracking
There is no analytics, no tracking and no third-party script or font: the service and this site serve their own. The service calls only the public sources above, GitHub when you connect it, its mail service, and your webhook.
How watchdep protects itself
A tool that checks other people’s dependencies must not become one of the compromised ones.
- Checksummed builds. The command line tool’s release build makes one static binary per system (Linux, macOS and Windows, on amd64 and arm64) and a SHA-256 checksum list.
- The Action verifies before it runs. The GitHub Action installs only command line versions whose checksums are committed in the Action’s own repository. It compares the download’s SHA-256 before unpacking it; a mismatch, or a version it has no checksums for, stops the step before anything runs. There is no “latest” and no default: the workflow names the version, and adding a version to the Action is a reviewed change. The checksums and the download address are fixed in the Action’s own files, never read from the job’s environment, so an earlier step cannot swap them. The first release, 0.1.0, is listed. Pin the Action itself by commit (CI).
- One container, built from source. The server’s container builds the watchdep binary from source rather than downloading one.
- Locked dependencies, checked in CI. The command line tool’s and the server’s own dependencies are locked to exact versions in their lockfiles. The server’s CI runs bundler-audit, Brakeman and the importmap audit on every pull request and every push to its main branch, and its gems and workflow actions get weekly update pull requests.