Dep Bouncer

npm install, reimagined for AI agents.

▶ Watch the demo film (2:32): https://youtu.be/w9Ax5KPUGD8

Try it in 30 seconds

Add this live URL as a remote MCP server in your client:

https://dep-bouncer-6ad22414-giberelin-heapify-global-community.app.nitrocloud.ai/mcp

Then ask: “Use the safe_install prompt, then add axios to this project.”

Or replay the axios incident directly (Bash / zsh):

curl -X POST 'https://dep-bouncer-6ad22414-giberelin-heapify-global-community.app.nitrocloud.ai/mcp' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2025-06-18' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bouncer_replay_incident","arguments":{"incident":"axios"}}}'

Works with (tested on the live server):

• NitroChat: verdict card rendered (screenshots below).
• Claude Code as an MCP client: claude mcp add --transport http dep-bouncer ; a real session called bouncer_check_package and bouncer_replay_incident, reported BLOCK with the evidence, and recommended a safe axios version.
• Claude Code guard hook: blocked the agent’s own npm install of a non-existent package (guard; Cursor hook config included).
• Any Streamable-HTTP MCP client via the URL (e.g. Cursor, NitroStudio, ChatGPT developer mode).

Dep Bouncer is an MCP server an AI coding agent calls before it installs or upgrades an npm package. It compares the release with the package’s own history (who published it, whether CI signed it, what runs at install time, which dependencies appeared, what code changed) and returns ALLOW / REVIEW / BLOCK with the evidence, plus the version to install instead.

• Live MCP endpoint: https://dep-bouncer-6ad22414-giberelin-heapify-global-community.app.nitrocloud.ai/mcp
• Demo video (2:32): https://youtu.be/w9Ax5KPUGD8
• Track: Developer Tools · Product reimagined: npm (npm install / npm audit)
• Built with NitroStack, deployed on NitroCloud.

---

The problem: agents install in seconds, advisories arrive in hours

AI coding agents now run npm install for us, mid-task, from the terminal. npm installs whatever was published a minute ago, and npm audit only knows about published advisories. For real hijacks, the free advisory database (OSV) needed hours to catch up:

Lags measured from the npm registry’s publish times and OSV’s published field. Two of these attacks went straight for AI agents: nx’s malware ran the victim’s claude, gemini and q CLIs with permission checks disabled, and the keyv worm planted Claude Code SessionStart hooks.

Before / after

In a real agent (NitroChat, connected to the live server): “Replay the axios incident with Dep Bouncer and tell me what to install instead.”

Why this needs MCP

A verdict is not one lookup. For each request the agent’s tool call makes Dep Bouncer gather the registry history (publishers, provenance, publish times), download and diff two tarballs, look up every newly added dependency, check the name against popular packages, and query OSV. Then the agent acts on the answer: it installs the safe version, asks the human (REVIEW), or refuses (BLOCK). The safe_install prompt teaches any agent that loop.

Tools, resources, prompt, widget

Agent guard: no install without a check

Agents forget to call tools. guard/ is a hook for Claude Code (PreToolUse) and Cursor (beforeShellExecution) that intercepts the agent’s own terminal commands (npm i, pnpm add, yarn add, bun add, npx, pnpm dlx, …), asks Dep Bouncer about each package, and denies BLOCK, asks the user on REVIEW, and emits no permission decision for ALLOW so the host keeps its own permission prompts.

Tested with a real headless Claude Code session asked to npm install react-codeshift-utils-pro chalk: the hook denied the command (“does not exist on npm”), the agent verified, did not work around the block, and installed only chalk.

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [
  { "type": "command", "command": "node /path/to/dep-bouncer/guard/dep-bouncer-guard.mjs" } ] } ] } }

How it decides

Weights: warn 15, high 35, critical 70. Any critical finding blocks; otherwise the sum decides: < 30 ALLOW, 30–69 REVIEW, ≥ 70 BLOCK. Versions with incomplete checks require at least REVIEW and are excluded from safe-version suggestions. Packages that don’t exist (hallucinated names), versions npm removed, and npm’s -security placeholders are blocked outright.

Benchmark

npm run bench replays the five hijacks and checks the latest release of the 200 most downloaded npm packages (presumed healthy; list in bench/packages.txt) to measure false positives. Latest run (bench/RESULTS.md):

• Replayed hijacks: 5 / 5 BLOCK, none of which OSV knew about at the replay time.
• 200 popular releases: 199 ALLOW, 1 REVIEW, 0 BLOCK. The REVIEW is TypeScript 7, a full rewrite published by a new account: exactly the kind of release a human should glance at. REVIEW means “ask the human”, not “block”. (An earlier 60-package sample also caught fresh webpack/next/vitest releases as REVIEW; results move as npm does.)

Live endpoint smoke test: node scripts/smoke.mjs calls every tool, resource and prompt on the deployed server, plus 17 hostile inputs (path traversal, __proto__, broken JSON, oversized bodies, unknown versions). GitHub Actions runs it hourly and after every push; latest live run passes all must-checks (p50 0.4 s, p95 2.3 s).

How we got here: the first run flagged webpack and vitest as BLOCK (bundlers rename chunk files every release). Two independent security reviews found 16 issues in the first review and 10 in the second (Oct 17); all findings were fixed. The fixes include line-based code diffs, guard decisions limited to deny/ask while preserving host permission prompts, parsing wrapped commands and subshells, checking every package, API-key support, REVIEW for incomplete checks (excluded from safe-version suggestions), resolving npm aliases, flagging git/URL specs, and always checking packages even when publisher names match. Numbers will move as npm does; CI re-runs the replays on every push.

How it compares (honestly)

Replayed incidents are labelled reconstructions

npm removed the malicious versions. Each replay uses the real last-good release (manifests, files, publish times, fetched from the registry by scripts/build-fixtures.mjs) plus the documented changes of the bad release, with benign stand-in code that only mimics the structure of the attack. Every stand-in file starts with /* Dep Bouncer reconstruction: benign stand-in, not real malware. */, and every replay result says what is real and what was reconstructed, with sources. No malware was downloaded or stored.

Architecture

flowchart LR
  Agent[AI coding agent] -- MCP --> Tools[bouncer tools / resources / prompt / widget]
  Tools --> Bouncer[BouncerService]
  Bouncer --> Registry[NpmRegistryService\npackuments, downloads]
  Bouncer --> Tarball[TarballService\nin-memory tar.gz, size caps]
  Bouncer --> OSV[OsvService]
  Bouncer --> Analysis[AnalysisService]
  Analysis --> Signals[8 signals] --> Verdict[verdict engine]
  Bouncer --> Incidents[IncidentsService\nreplay fixtures]

src/
  modules/registry/    npm registry, downloads, OSV clients; tar.gz parser; semver; TTL cache
  modules/analysis/    signal contract, signals/*, code patterns, name similarity, verdict
  modules/incidents/   reconstructed incident fixtures + replay service
  modules/bouncer/     MCP tools, resources, prompt; orchestration service
  health/              system, npm registry and OSV health checks
  widgets/app/verdict-card/   the verdict widget
scripts/               build-fixtures, build-popular, benchmark, copy-assets
test/                  node:test suites (signals, parser, replays, semver, ...)

NitroStack features used: DI modules and @Injectable, @Tool / @Resource / @Prompt, @Widget, @RateLimit, @Cache, an interceptor (MetricsInterceptor), guards (ApiKeyModule + @UseGuards), MCP Tasks (taskSupport, progress, cancellation), @HealthCheck (system, npm registry, OSV), and the bouncer://stats resource for live per-tool latency, errors and verdict totals.

Safety: Dep Bouncer never executes package code; tarballs come only from registry.npmjs.org and are parsed in memory (25 MB compressed, 60 MB extracted, 5,000 files, path-traversal checks), with byte-budgeted caches, a 4-way download semaphore and redirect checks. No user data stored; metrics hold no request contents or IPs.

Authentication: the public demo is open on purpose (read-only, public data, rate-limited, so judges and agents can try it). Set DEP_BOUNCER_API_KEYS=key1,key2 to require an API key (NitroStack ApiKeyModule; clients send it in MCP _meta.apiKey). See .env.example.

Use it

Any MCP client (Claude, ChatGPT, Cursor, NitroChat): add a remote MCP server with the URL above. Cursor ~/.cursor/mcp.json:

{ "mcpServers": { "dep-bouncer": { "url": "https://dep-bouncer-6ad22414-giberelin-heapify-global-community.app.nitrocloud.ai/mcp" } } }

Then ask: “Use the safe_install prompt, then add axios to this project.”

Run locally:

npm install
npm run build
npm test            # 220 tests, offline (CI on Node 22 and 24)
npm run bench       # replays + false-positive scan (needs network)
npm run dev         # stdio, for NitroStudio

No environment variables are required. Optional (see .env.example): MCP_TRANSPORT_TYPE (stdio / http / dual), PORT, NITRO_LOG_LEVEL.

Limitations and roadmap

• Heuristics: a determined attacker can write code that avoids the patterns; the publisher, provenance, script and dependency signals still apply. Tarballs over 25 MB (e.g. next) skip the code diff and require REVIEW for incomplete coverage.
• npm only. Next: PyPI, lockfile/CI mode, org policies (e.g. “always REVIEW new publishers”).

Built with AI assistance

Harsha B S designed and directed the project. Claude Code and OpenAI Codex helped write and review code; every change was reviewed and tested. See the architecture walkthrough.

Team

Harsha B S (team Giberelin, Heapify Global Community) · MIT License