Operate
Security fixes for your packages
CLI checks the packages your app uses for known security problems every day, and can open the fix for you, tested in a throwaway copy before it goes anywhere.
Most apps are built on hundreds of packages written by other people. Now and then one of them turns out to have a security hole, and a fixed version comes out. Keeping up with that by hand is a chore nobody gets to.
CLI does it for apps deployed from GitHub. Once a day it reads the exact package versions your live app uses and checks them against osv.dev, the open database of known security problems. If something turns up, you get an alert saying which package, how serious it is and which version fixes it.
Switch it to Tell me and propose fixes and CLI goes a step further: it makes the smallest upgrade that fixes the problems, opens a pull request on GitHub, and builds that upgrade in a throwaway copy of your project to check the app still builds and starts. When it's ready you see Accept and merge. Pressing it merges the pull request, and the app deploys like after any other push. Nothing is merged unless a person says so.
How to do it: open an app, go to Settings, find Dependency security. Pick Off, Tell me, or Tell me and propose fixes, and how serious a problem has to be before CLI acts (High and up by default). Check now runs a check straight away.
"Are any of my app's packages known to be insecure? If there's a fix, open it and tell me when it's ready."
What's checked
Apps deployed from GitHub through the CLI app. CLI reads, at the commit that's live (or the newest deployed one):
| File | What's checked |
|---|---|
package-lock.json (v2 or v3) | every installed package and exact version, including ones pulled in by others |
package.json, when there's no lockfile | only exactly pinned versions ("4.18.2", not "^4.18.2") |
requirements.txt | pinned lines (name==1.2.3) |
They're read from the service's root directory. The versions go to OSV's batch API; for each problem, CLI works out the smallest version that fixes it from the ranges OSV gives. When a package has several problems, the fix is the highest of those versions.
Checks run once a day (the hourly job picks up apps not checked in 24 hours). The first check of a newly found problem raises a dependency_alert event (alerts, webhooks, phone), once per problem.
Settings
PUT /v1/services/:id/dependencies
{"mode": "propose", "minSeverity": "high"}| Field | Values |
|---|---|
mode | off; report (the default: check and alert); propose (also open fixes) |
minSeverity | low, moderate, high (default), critical: alerts and fixes ignore anything below it |
Owners and admins change settings. GET /v1/services/:id/dependencies returns the settings, the last check (scan.findings) and any fix waiting for review (open). POST /v1/services/:id/dependencies/scan checks now.
Fixes
POST /v1/services/:id/dependencies/fixCLI then:
- Edits
package.json: a package listed there gets the fixed version with the same prefix (^4.17.20→^4.17.21); one pulled in by another package gets anoverridesentry.requirements.txtpins are rewritten in place. - Regenerates
package-lock.jsonwithnpm install --package-lock-only --ignore-scripts(no install scripts run). If npm can't resolve the new versions together, the fix stops with a message saying so. - Commits that to a new branch
cli/dependency-fix-…and opens a pull request against the service's branch. - Proposes a change: a throwaway copy of the project, with personal data scrubbed from database copies, built at that commit. When it settles, the fix's status is
readyorfailed, and adependency_fix_readyevent goes out.
A fix that moves a package to a new major version is marked (major: true), since those can need code changes.
POST /v1/dependency-fixes/:id/accept
POST /v1/dependency-fixes/:id/dismissAccept (developer or above) squash-merges the pull request. With auto-deploy on, GitHub's push for the merge deploys it; otherwise CLI deploys the merge commit. If GitHub refuses (branch protection needing reviews or checks), the answer says so and the pull request stays open for you to merge there. A fix that failed its preview can only be merged by an owner or admin. Dismiss removes the preview; close the pull request on GitHub if you don't want it. Undecided fixes expire after seven days.
Agents use cli_dependencies (get, scan, settings, fix, accept, dismiss) and are told to ask the person before accepting.