Npmguard
About
Pre-install risk gate for npm packages. Stops AI coding agents from running malicious or typosquatted packages before lifecycle scripts run.
Details
- Author
- AyoubTadlaoui
- Downloads
- 400
- Categories
- Other, Security
Jump to
- Pre-install risk scoring with composite score and verdict
- Eight risk signals: LifecycleScripts, PackageAge, MaintainerChurn, SoleMaintainer, RepoHealth, Typosquat, KnownCve, Deprecated
- Integrates OSV.dev malware namespace (MAL-*) for known malicious packages
- Single static Rust binary distributed outside npm for supply chain security
- MCP tool returns structured signals for AI agent decision-making
- Prebuilt binaries for macOS, Linux, and Windows
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
NpmguardCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Add Npmguard to your MCP host (Claude Code, Cursor, Windsurf) by adding a JSON entry with the path to the npmguard-mcp binary. It exposes one tool: install_package(name, version?) which returns { level, score, signals, recommendation }. AI agents can use the structured tool response to decide whether to proceed with an installation. The binary is installed by downloading a prebuilt release from GitHub Releases for your platform.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"npmguard": {
"npmguard": {
"command": "/usr/local/bin/npmguard-mcp"
}
}
}
}McpServers
{
"npmguard": {
"command": "/usr/local/bin/npmguard-mcp"
}
}What it does
A native pre-install risk gate for npm packages, with an MCP tool for AI coding agents. Pulls npm registry + OSV.dev (incl. MAL-\ malware namespace) + GitHub repo signals in parallel, computes a composite risk score, and returns anok
/ warn / block verdict before lifecycle scripts can execute.
Single static Rust binary, distributed via GitHub Releases — not via npm — so the gate itself cannot be compromised by the npm supply chain it's
protecting against.
## Live verdict against the npm registry
npmguard install lodahs (a real typosquat of lodash, flagged in OSV's malware namespace):
npmguard lodahs@0.0.1-security → score 115 / 200 (block)
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)
## MCP integration
Add to your MCP host (Claude Code shown, also works with Cursor / Windsurf):
```json
{
"mcpServers": {
"npmguard": {
"command": "/usr/local/bin/npmguard-mcp"
}
}
}
Exposes one tool: install_package(name, version?) → returns { level, score, signals, recommendation }. When an AI coding agent calls it, the
recommendation is fed back as a tool response — so even if the user said "just install whatever," the model has structured signal to stop and ask.
8 risk signals
- LifecycleScripts (30 pts) — package defines preinstall/install/postinstall
- PackageAge (25/10 pts) — version published < 7 / 30 days ago
- MaintainerChurn (20 pts) — dormant package resurrection
- SoleMaintainer (10 pts) — single-point-of-compromise
- RepoHealth (15/10 pts) — archived / no commits in 6 months
- Typosquat (25 pts) — one Damerau-Levenshtein edit from a popular name
- KnownCve (80/50/20/10/5 pts) — OSV.dev advisory, with MAL- malware-namespace escalation
- Deprecated (10 pts) — npm registry marks the version deprecated
Honest about scope (v0.1.2)
- ✅ Pre-install risk scoring + MCP verdict gate
- ❌ Not yet a real npm install wrapper (v0.2)
- ❌ Not yet sandboxing lifecycle scripts (v0.2)
- ❌ Not yet verifying npm provenance (v0.3)
- ❌ Doesn't replace npm audit, Snyk, Socket, Dependabot — it's an additional layer
Full roadmap: ROADMAP.md
Install
Prebuilt binaries for macOS (x86_64 + arm64), Linux (x86_64 + arm64), Windows (x86_64) — every release ships SHA256SUMS.txt:
github.com/AyoubTadlaoui/npmguard/releases/latest
Source
MIT licensed: github.com/AyoubTadlaoui/npmguardSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
