
squatscan
io.github.haseeb-xd/squatscan
Detects slopsquatted/typosquatted npm packages before you install them.
Documentation
SquatScan
SquatScan is an MCP server that checks npm packages for signs of slopsquatting before you install them.
https://github.com/user-attachments/assets/bac28180-2958-4d56-9410-46e5d1373f4c
AI coding assistants sometimes suggest npm packages that don't exist. Attackers
register those made-up names and fill them with malware, so the suggested
npm install succeeds and installs the attacker's code. SquatScan catches these
packages before they are installed.
How it works
For each package name, SquatScan looks it up on the npm registry and combines these signals into a risk score from 0 to 100:
- whether the package exists at all
- how close the name is to a popular package (e.g.
lodahsvslodash) - how new the package is
- how many downloads it has
- whether it links to a source repository
- how many versions and maintainers it has
The score maps to a verdict:
| Verdict | Score | What to do |
|---|---|---|
| 🟢 GREEN | under 40 | No strong risk signals. Go ahead. |
| 🟡 YELLOW | 40–69 | Some suspicious signals. Check the name before installing. |
| 🔴 RED | 70 or more | Looks like a squatted package. Don't install it. |
Every result includes a reasons list that explains which signals affected the score.
Install
You need Docker installed and running.
Claude Code:
claude mcp add -s user squatscan -- docker run -i --rm ghcr.io/haseeb-xd/squatscan:0.1.0
Claude Desktop (or any MCP client): add this to your config file (Settings → Developer → Edit Config), then fully restart the app:
{
"mcpServers": {
"squatscan": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/haseeb-xd/squatscan:0.1.0"]
}
}
}
The
-iflag is required. Without it, Docker closes stdin and the server exits immediately.
SquatScan is also listed in the MCP Registry
as io.github.haseeb-xd/squatscan.
Run without Docker (Java 17+)
./mvnw clean package -DskipTests
mkdir -p ~/.squatscan && cp target/squatscan-0.1.0.jar ~/.squatscan/squatscan.jar
claude mcp add -s user squatscan -- java -jar "$HOME/.squatscan/squatscan.jar"
On Windows, use an absolute path with forward slashes, e.g.
C:/Users/<you>/.squatscan/squatscan.jar.
Usage
Start a new Claude session, then ask things like:
Is lodahs safe to install?Check react, reqeusts and some-hallucinated-pkg-xyzI'm about to run npm install express lodahs. Is that OK?
Tools
| Tool | What it does |
|---|---|
check_package(name, version?) | Checks one package |
check_packages(names[]) | Checks several packages at once |
check_install_command(command) | Reads a command like npm install a b c and checks every package in it |
Make Claude check every time (recommended)
Claude decides for itself when to call an MCP tool, and it often skips SquatScan.
To make it check every time, add this to ~/.claude/CLAUDE.md:
Before recommending or installing ANY npm package, check every package name with the
squatscan MCP tools. RED: don't install it and suggest the intended package.
YELLOW: warn me and ask before continuing. GREEN: go ahead.
Troubleshooting
- Shows "failed" in
/mcp: make sure Docker is running (or thatjavais on your PATH if you're not using Docker). Runclaude --debugto see startup errors. - New tools don't appear: start a new Claude session. Sessions that are already running don't pick up newly added servers.
Scope
npm packages only. Runs entirely on your machine; the only network calls go to the public npm registry. No accounts or data collection.
ghcr.io/haseeb-xd/squatscan:0.1.0docker pull ghcr.io/haseeb-xd/squatscan:0.1.0:undefined