Repository avatar
Other Tools
v0.1.0
active

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. lodahs vs lodash)
  • 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:

VerdictScoreWhat to do
🟢 GREENunder 40No strong risk signals. Go ahead.
🟡 YELLOW40–69Some suspicious signals. Check the name before installing.
🔴 RED70 or moreLooks 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 -i flag 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-xyz
  • I'm about to run npm install express lodahs. Is that OK?

Tools

ToolWhat 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 that java is on your PATH if you're not using Docker). Run claude --debug to 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.

OCI
ghcr.io/haseeb-xd/squatscan:0.1.0
Install Command
docker pull ghcr.io/haseeb-xd/squatscan:0.1.0:undefined