depstop — Zero-config CLI security gate for npm install scripts

depstop is a zero-config CLI security gate that blocks risky npm dependencies before install-time scripts can run.

When you run npm install or npm ci, dependencies can execute arbitrary code through npm lifecycle scripts like preinstall, install, postinstall, and prepare. That code can access CI secrets, cloud credentials, tokens, and your local developer environment.

Supply-chain attacks often exploit this exact behavior by publishing malicious package versions with install scripts, then removing them after a short window.

depstop sits between install and build and enforces one rule:

No implicit install-time risk.

Every package version that runs install-time code, or was published in the last 24 hours, must be explicitly approved before the build continues.

Why npm install scripts are risky

npm postinstall scripts and other npm lifecycle scripts run automatically during dependency install. In CI, this means third-party code can execute before your application even builds.

That install-time code execution is a common dependency supply-chain attack path. A compromised package can exfiltrate CI secrets or tokens, then disappear quickly.

depstop makes that risk visible and enforceable with lockfile-driven checks and explicit version approvals.

How depstop works

1. Install dependencies with scripts disabled (for npm: npm ci --ignore-scripts).
2. Run depstop to identify risky package versions.
3. Approve exact versions you trust (depstop approve <name@version>).
4. Rebuild and continue your build pipeline.

Install depstop

npm install -g depstop
# or run without installing:
npx depstop

Usage

Drop it into your build step:

npm ci --ignore-scripts
npx depstop
npm rebuild
npm run build

depstop should be run after installing with scripts disabled. It then tells you which dependencies require explicit approval before scripts are allowed to run.

For npm, use npm ci --ignore-scripts. For pnpm, yarn, and bun, use the equivalent install-without-scripts mode before running depstop.

You can also add depstop to your build script, but install should still run with scripts disabled:

{
  "scripts": {
    "build": "depstop && tsc"
  }
}

depstop reads your lockfile automatically — no config needed.

Who should use depstop?

Use depstop if you want to:

• prevent npm postinstall scripts from running silently in CI
• reduce exposure to dependency supply-chain attacks
• require explicit approvals for risky package versions
• make install-time code execution visible in code review

What depstop blocks

npm lifecycle scripts

Any package that defines preinstall, install, postinstall, or prepare is blocked. These scripts run automatically during install with full access to your environment.

Recently published package versions under 24 hours old

Malicious versions typically live only a few hours before being pulled. Blocking fresh publishes reduces exposure during the highest-risk window.

Output

When something is blocked:

Blocked:

  [email protected]        → published 2h ago
  [email protected]      → runs postinstall script

Fix: downgrade OR approve explicitly:

  depstop approve [email protected]
  depstop approve [email protected]

When everything is clean:

✓ depstop: 142 packages checked, 0 blocked

Approving packages

If you've reviewed a package and accept the risk:

depstop approve [email protected]

This writes an exact-version entry to depstop.json in your repo:

{
  "allow": ["[email protected]"]
}

Commit depstop.json — the approval is tracked in your repo history. Future runs skip approved packages. A different version of the same package is not covered; it must be approved separately.

Supported package managers and lockfiles

• Package managers: npm, pnpm, yarn (v1), bun
• Lockfiles: package-lock.json (npm v2/v3), pnpm-lock.yaml, yarn.lock (v1), bun.lock

CI example

# .github/workflows/ci.yml
- run: npm ci --ignore-scripts
- run: npx depstop
- run: npm rebuild
- run: npm run build

depstop exits 1 if blocked, which fails the CI step.

Exit codes

| Code | Meaning | |------|---------| | 0 | All packages clean (or approved) | | 1 | One or more packages blocked | | 2 | Error (no lockfile, parse failure) |

What depstop does NOT do

• CVE / vulnerability scanning (use npm audit for that)
• Provenance / signature verification
• Git or URL dependency checks
• Dashboards or org-wide policies

depstop is not a vulnerability scanner. It is a build gate for install-time code execution.

depstop solves one problem: silent install-time code execution. It turns hidden install-time risk into an explicit, version-tracked decision.

License

MIT