slopsquat-scanner

@guardbee/mcp-slopsquat-scanner

🇬🇧 英语 | 🇹🇷 土耳其语 | 🇨🇳 中文 | 🇯🇵 日语 | 🇰🇷 韩语 | 🇧🇷 葡萄牙语 | 🇪🇸 西班牙语 | 🇩🇪 德语

一个 MCP（Model Context Protocol）服务，用于将项目自身清单（package.json、requirements.txt、pyproject.toml）中声明的每项依赖与 npm/PyPI 真实注册表进行核对——不是查询本地数据库，而是实际联网查询。

LLM 编码助手会以可测量的比率臆造听起来合理的软件包名称——针对开源模型的研究显示，这一比例约为 21.7%。攻击者深知这一点，会在 npm/PyPI 上抢先注册这些名称，因此下一个照搬相同建议的人不会遇到安装错误，而是安装攻击者的代码。这就是 slopsquatting；与拼写抢注不同，它没有可供肉眼识别的拼写错误：臆造的名称往往听起来比原本想要的软件包名称更合理。

默认情况下，遥测功能关闭。设置 GUARDBEE_TELEMETRY=1 后，它会发送服务、工具、成功状态、耗时和较短的参数值（例如文件路径）；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

Claude ──► slopsquat-scanner ──► registry.npmjs.org / pypi.org
              │
              ├─ dependency_not_found            (name isn't published anywhere — critical)
              └─ dependency_recently_published    (exists, but published <30 days ago — low/informational)

---

为什么要查询实时注册表，而不是使用本地列表

无法为此维护本地“已知恶意”列表——slopsquat 的要点就在于它是一个新名称，专门注册来利用某个特定的臆造名称，而且可能在有人运行 npm install 前几小时就已注册。静态规则无法判断这一点；只有向注册表询问“这个确切名称现在是否存在”才行。本软件包只检查项目自身直接声明的依赖项（package.json 中的 dependencies/devDependencies/peerDependencies/optionalDependencies 部分，或 Python 项目的 requirements.txt/pyproject.toml），而不检查完整的已解析锁定文件依赖树。传递依赖已经由发布依赖它们的软件包的维护者审核；真正的风险时刻，是一个新名称被直接输入到你自己的清单中（无论是由人还是 AI 助手输入）。

完全不存在的名称明确无误，会被报告为严重——你或队友安装前请核实名称是否正确。确实存在但仅在过去 30 天内发布的名称，会被报告为低/信息提示，而非严重：真实的新软件包也经常如此；仅凭这一点无法证明存在恶意行为——这只是一个“值得再检查一下”的信号，而非定论。

---

功能

• 检查 npm 和 PyPI — package.json、requirements.txt 和 pyproject.toml（包括 PEP 621 的 [project] dependencies 和 Poetry 的 [tool.poetry.dependencies]）
• 仅检查直接依赖 — 速度快，也契合实际发生依赖名称抢注风险的时机
• 正确处理带作用域的 npm 包（@scope/name）— 开发过程中发现并修复了一个真实的 URL 编码错误（对整个名称使用 encodeURIComponent 会对注册表自身的 @scope%2Fname 约定进行双重编码，生成注册表无法识别为单个包的 URL）
• 无需 API 密钥 — 直接查询公开且无需身份验证的 npm 注册表和 PyPI JSON API
• 输出 SARIF 2.1.0 — 可集成 CI/CD（GitHub Code Scanning 等）
• 18 个单元测试，覆盖清单解析器（包括检查传递依赖的锁文件条目不会被纳入）和严重性分类逻辑；全部使用真实且确定的测试样例 — 不模拟网络调用，因为解析和分类都是纯函数，无需模拟。使用混合了真实包（react、vitest、requests）和刻意捏造的包名的测试样例，针对真实的 npm 和 PyPI 注册表完成端到端验证 — 成功发现两个捏造的包名，且未将任何真实包误报。还将本单体仓库自身的 package.json 文件作为自测对象：真实依赖零误报，并发现一个确实合理的低严重性问题（@guardbee/mcp-telemetry，当时在 npm 上发布仅约 2 周）— 正是预期的“值得看看，而非警报”的表现。

---

快速开始

Claude Desktop / MCP 客户端

{
  "mcpServers": {
    "guardbee-slopsquat-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-slopsquat-scanner"]
    }
  }
}

CLI（CI/CD）

npx @guardbee/mcp-slopsquat-scanner scan . --fail-on=critical --format=sarif > results.sarif

---

MCP 工具

工具	描述
scan_npm	检查目录中 package.json 声明的所有 npm 依赖
scan_pip	检查所有声明的 pip 依赖（requirements.txt / pyproject.toml）
check_package	根据 npm 或 PyPI 检查单个包名
scan_directory	自动检测并检查 npm 和 pip 清单

---

检测到的模式

模式	严重性	含义
dependency_not_found	严重	声明的包名在注册表中根本不存在
dependency_recently_published	低	包确实存在，但首次发布时间距今不到 30 天

---

配置（guardbee.yml）

slopsquat-scanner:
  fail-on: critical    # critical | low | none
  include-dev: false

---

限制（有意如此）

• 仅检查直接依赖。 传递依赖（即你所依赖的包自身依赖的包）中捏造或抢注的名称不会被检查 — 该包的维护者在发布时已经通过真实注册表验证过它。
• “最近发布”信号确实存在歧义。 新包不断发布；之所以将其标为低严重性，正是因为它不能证明任何事情，只是提示你“仔细看看”。
• 依赖网络。 每项检查都会向 npm/PyPI 注册表发起实时 HTTP 请求 — 依赖较多的项目会产生许多请求（同时最多处理 8 个），注册表故障或速率限制会显示为工具错误，而不是误报“包不存在”（注册表错误会与真实的 404 分开报告）。
• 不识别版本固定情况。 此工具检查的是名称是否存在，而不是你固定的特定版本范围本身是否可疑 — 这是另一个问题，已有工具覆盖（查看 @guardbee/mcp-dependency-auditor 以检查已知 CVE）。

---

开发

npm run build
npm test             # 18 unit tests

---

许可证

MIT — GuardBee

反馈

有问题、想法或遇到误报？请在 GitHub 讨论区中发起讨论，或提交问题。如果 GuardBee 对你有帮助，可以在代码仓库点个 ⭐，帮助其他人找到它。