Npmguard

I built this because it's wild how many vibe-coders just run the AI on auto-mode and let it install whatever it wants. npmguard screens them before a single install script runs.

Claude Code, Cursor, and Codex run npm install autonomously. Nobody pauses to ask "wait, is supabase-mcp-helper even real?" I built npmguard as an MCP server and CLI that scores every package (OSV malware data, typosquat/slopsquat, install-script analysis) and returns a verdict before lifecycle scripts fire.

It ships as one Rust binary, outside npm. That matters: the gate cant be poisoned by the supply chain its guarding.

CI Release Latest release License: MIT

npmguard install lodahs is a real typosquat of lodash, refused before lifecycle scripts can run:

_{Also available as GIF or MP4. Live verdict against the npm registry. lodahs is in OSV's malware namespace (MAL-2025-25502). Theme: atlas-ragnarok. Regenerate with sh docs/_theme/gen.sh (needs vhs, ffmpeg, webp, pillow, numpy).}

Why

Between 2025 and 2026 the npm ecosystem got hit by a string of worm-style supply chain attacks: Shai-Hulud (Sep 2025), SHA1-Hulud (Nov 2025), the Axios compromise (Mar 2026), Mini Shai-Hulud (May 2026). All of them ran inside preinstall / install / postinstall scripts the moment someone ran npm install. You win or lose before the install completes, not after.

The existing tools dont cover the gap I was staring at:

• npq, safe-npm / socket npm, npm-risk ship as npm packages. They run on the exact thing they're supposed to protect you from. If the wrapper gets compromised, you've made the situation worse.
• pnpm v10+, Bun disable lifecycle scripts by default, but only if you've already moved off npm. The npm majority is still exposed.
• npm audit, Snyk, Dependabot, lavamoat/allow-scripts do CVE scanning and allow-list management well. What they dont do is act as a pre-install heuristic gate, and none of them intercept AI coding assistants like Claude Code, Cursor, or Codex when they run npm install on your behalf.

That last one is the specific thing I wanted to fix: pre-install risk scoring that also gates AI agents, shipped as a single binary outside npm. Zero runtime dependencies beyond the registries it queries.

Install

curl -L -o npmguard.tar.gz \
  https://github.com/AyoubTadlaoui/npmguard/releases/latest/download/npmguard-v0.1.6-aarch64-apple-darwin.tar.gz
tar -xzf npmguard.tar.gz
# Edit the directory name below if the version has changed.
sudo mv npmguard-v0.1.6-aarch64-apple-darwin/npmguard-cli  /usr/local/bin/npmguard
sudo mv npmguard-v0.1.6-aarch64-apple-darwin/npmguard-mcp  /usr/local/bin/npmguard-mcp

curl -L -o npmguard.tar.gz \
  https://github.com/AyoubTadlaoui/npmguard/releases/latest/download/npmguard-v0.1.6-x86_64-apple-darwin.tar.gz
tar -xzf npmguard.tar.gz
# Edit the directory name below if the version has changed.
sudo mv npmguard-v0.1.6-x86_64-apple-darwin/npmguard-cli  /usr/local/bin/npmguard
sudo mv npmguard-v0.1.6-x86_64-apple-darwin/npmguard-mcp  /usr/local/bin/npmguard-mcp

curl -L -o npmguard.tar.gz \
  https://github.com/AyoubTadlaoui/npmguard/releases/latest/download/npmguard-v0.1.6-x86_64-unknown-linux-gnu.tar.gz
tar -xzf npmguard.tar.gz
# Edit the directory name below if the version has changed.
sudo mv npmguard-v0.1.6-x86_64-unknown-linux-gnu/npmguard-cli  /usr/local/bin/npmguard
sudo mv npmguard-v0.1.6-x86_64-unknown-linux-gnu/npmguard-mcp  /usr/local/bin/npmguard-mcp

curl -L -o npmguard.tar.gz \
  https://github.com/AyoubTadlaoui/npmguard/releases/latest/download/npmguard-v0.1.6-aarch64-unknown-linux-gnu.tar.gz
tar -xzf npmguard.tar.gz
# Edit the directory name below if the version has changed.
sudo mv npmguard-v0.1.6-aarch64-unknown-linux-gnu/npmguard-cli  /usr/local/bin/npmguard
sudo mv npmguard-v0.1.6-aarch64-unknown-linux-gnu/npmguard-mcp  /usr/local/bin/npmguard-mcp

https://github.com/AyoubTadlaoui/npmguard/releases/latest/download/npmguard-v0.1.6-x86_64-pc-windows-msvc.zip

cargo install --git https://github.com/AyoubTadlaoui/npmguard --bin npmguard-cli
cargo install --git https://github.com/AyoubTadlaoui/npmguard --bin npmguard-mcp

# bash / zsh
echo 'alias npmguard=npmguard-cli' >> ~/.bashrc   # or ~/.zshrc

Verify the download against the published checksums before extracting:

# Replace the filename to match your platform.
shasum -a 256 -c <(grep npmguard-v0.1.6-aarch64-apple-darwin.tar.gz SHA256SUMS.txt)

All prebuilt binaries are listed on the Releases page. Homebrew tap, Scoop bucket, and curl … | sh installer land with v0.2 alongside the sandbox layer.

Docker (npmguard-mcp only)

docker pull ghcr.io/ayoubtadlaoui/npmguard-mcp:latest
docker run --rm -i ghcr.io/ayoubtadlaoui/npmguard-mcp:latest

The Docker image is mainly there for MCP catalogs and CI. For local use, install the native binary. The image ships only npmguard-mcp (not the CLI), runs as a non-root user, and has no exposed ports. MCP hosts communicate over stdio.

Quickstart: CLI

# Evaluate the latest version, no install.
npmguard check axios

# Pinned version, JSON output (machine-readable for CI).
npmguard check --json @ctrl/[email protected]

# Install path: v0.1 prints the verdict and stops; v0.2 will run `npm install`
# inside the sandbox layer if the verdict allows it.
npmguard install [email protected]

# Auto-accept warn-level (still refuses block-level).
npmguard install --yes some-fresh-package

Sample output, real live verdict against the registry:

npmguard  [email protected]  →  score 115 / 200  (block, thresholds warn=30 block=70)
   10 pts  SoleMaintainer       single maintainer: adam_baldwin
   25 pts  Typosquat            name 'lodahs' is 1 edit away from popular package 'lodash'
   80 pts  KnownCve             1 CONFIRMED MALICIOUS by OSV for this version: MAL-2025-25502
blocked: refusing to install lodahs (score 115 ≥ block threshold 70)

All flags:

Quickstart: MCP

npmguard-mcp speaks the Model Context Protocol over stdio. Once the binary is on your PATH, register it with your agent using the instructions for your tool below.

Claude Code

Use the official claude mcp add CLI. No manual JSON editing required:

# Adds npmguard to your user-level config (~/.claude.json), available in all projects.
claude mcp add --transport stdio --scope user npmguard -- /usr/local/bin/npmguard-mcp

Verify it registered:

claude mcp list

To scope it to a single project instead (stored in .mcp.json in the project root, safe to commit):

claude mcp add --transport stdio --scope project npmguard -- /usr/local/bin/npmguard-mcp

Reference: Claude Code MCP docs

Cursor

Add an mcpServers block to your config. Use the global file to enable it in every workspace, or the project file to scope it to one repo.

Global (~/.cursor/mcp.json):

{
  "mcpServers": {
    "npmguard": {
      "command": "/usr/local/bin/npmguard-mcp"
    }
  }
}

Project-scoped (.cursor/mcp.json in the repo root):

{
  "mcpServers": {
    "npmguard": {
      "command": "/usr/local/bin/npmguard-mcp"
    }
  }
}

Edit the command path if you installed to a location other than /usr/local/bin/.

Reference: Cursor MCP docs

Codex CLI

Codex supports stdio MCP servers via ~/.codex/config.toml. Add a [mcp_servers.npmguard] table:

[mcp_servers.npmguard]
command = "/usr/local/bin/npmguard-mcp"

To scope it to a single project, create .codex/config.toml in the repo root with the same block (only works in projects Codex has marked as trusted).

Edit the command path if you installed elsewhere.

Reference: Codex MCP docs

What the MCP tool returns

npmguard-mcp exposes one tool, install_package(name, version?), returning a structured verdict the model can act on:

{
  "package": "lodahs",
  "resolved_version": "0.0.1-security",
  "level": "block",
  "score": 115,
  "signals": [
    { "kind": "SoleMaintainer", "points": 10, "detail": "single maintainer: adam_baldwin" },
    { "kind": "Typosquat", "points": 25, "detail": "name 'lodahs' is 1 edit away from popular package 'lodash'" },
    { "kind": "KnownCve", "points": 80, "detail": "1 CONFIRMED MALICIOUS by OSV for this version: MAL-2025-25502" }
  ],
  "recommendation": "Block: do NOT install this package without explicit user override. Present the signals and ask the user to confirm."
}

The model gets the recommendation in its own message. So even if the user said "just install whatever you need", the assistant has the structured signal to stop and ask.

Deterministic enforcement (Claude Code hook)

MCP is advisory. The hook is not.

The MCP integration (npmguard-mcp) lets Claude Code ask npmguard before installing a package. It works well: the model sees the risk verdict and can act on it. But it is still advisory. The model decides whether to call the tool, and an inattentive or jailbroken model can skip it.

The hook subcommand is different. Claude Code's harness runs PreToolUse hooks automatically on every Bash tool call before the command executes. The model has no say. It cant skip, bypass, or talk its way around a hook. That's what makes the blocking real rather than aspirational.

Setup (one command)

# Installs into ~/.claude/settings.json, active in every Claude Code project.
npmguard hook install

# Or scope it to a single project (writes .claude/settings.json in the cwd).
npmguard hook install --scope project

Then restart Claude Code (or reload the window). From that point on, every Bash command Claude Code tries to run passes through npmguard hook handle first.

To remove the hook:

npmguard hook uninstall          # user-level
npmguard hook uninstall --scope project

What the hook does

1. Claude Code wants to run a Bash command, e.g. npm install some-package.
2. The harness sends the command to npmguard hook handle via stdin (JSON).
3. npmguard parses the command for package-install invocations. Non-install commands (ls, git, npm run build, etc.) are passed through immediately with no network call.
4. For each detected package, the existing risk engine runs (same signals, same scoring as npmguard check).
5. npmguard writes a decision JSON to stdout:
   • block verdict → deny: Claude Code refuses the command and tells the model why.
   • warn verdict → ask: Claude Code surfaces the signals and asks the user to confirm.
   • ok verdict → allow: command proceeds silently.
   • network error → ask with a caution message. Never a silent allow on an unverified package, never a hard deny on an infra failure.

Honest limitations

Risk signals

Composite score is the sum (capped at 200). Default thresholds: warn ≥ 30, block ≥ 70. Tunable per project via config (planned for v0.2).

Weights are starting values, not science. They'll be tuned against corpus/ and published as part of each release. PRs welcome.

Versioning & releases

npmguard follows Semantic Versioning. While the project is 0.x:

• The CLI is treated as stable for end users. Flag names and exit codes wont change without a major bump.
• The MCP tool surface (install_package input/output schema) may make minor additive changes between 0.x releases. Anything breaking is called out in CHANGELOG.md.

Tagged releases publish prebuilt binaries to the Releases page (macOS x86_64 + arm64, Linux x86_64 + arm64, Windows x86_64) via a cross-platform GitHub Actions matrix.

[!NOTE] v0.1 is a risk checker + MCP verdict gate. It is not yet a real npm wrapper, installer, or sandbox. npmguard check and npmguard install both produce a verdict; the actual npm install subprocess execution and cross-platform sandbox land in v0.2. See the roadmap below.

Roadmap (full reasoning + considered-and-rejected scope in ROADMAP.md):

Runtime sandboxing (npmguard run npm test) is deliberately out of scope. See ROADMAP.md § Considered and kept out of scope for the reasoning.

Contributing

PRs and issues welcome. The short version:

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
NPMGUARD_CORPUS=1 cargo test --test corpus -- --nocapture   # live network test

Open the PR once that's clean.

License

MIT. See LICENSE.

About the author

Ayoub Tadlaoui (Atlas Kaisar). From Morocco, building software since 2016.

"High performance knows no part-time commitment."