slopsquat-scanner

@guardbee/mcp-slopsquat-scanner

🇬🇧 英語 | 🇹🇷 トルコ語 | 🇨🇳 中国語 | 🇯🇵 日本語 | 🇰🇷 韓国語 | 🇧🇷 ポルトガル語 | 🇪🇸 スペイン語 | 🇩🇪 ドイツ語

プロジェクト独自のマニフェスト（package.json、requirements.txt、pyproject.toml）に宣言されたすべての依存関係を、ローカルデータベースではなく、実際にネットワーク経由で npm/PyPI レジストリに照会して確認する MCP（Model Context Protocol）サーバーです。

LLM コーディングアシスタントは、もっともらしいパッケージ名を一定の割合で幻覚します。オープンソースモデルに関する調査では、その割合は約 21.7％とされています。攻撃者はこれを知っており、まさにそうした名前を npm/PyPI に先回りして登録します。そのため、同じ提案をコピーする次の人はインストールエラーに遭遇するのではなく、攻撃者のコードを取得することになります。これがスロップスクワッティングです。タイポスクワッティングとは異なり、目で見つけられる誤字がありません。幻覚された名前は、多くの場合、対象となった実在のパッケージ名よりももっともらしく聞こえます。

テレメトリーはデフォルトでオフです。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)

---

ローカルリストではなく、レジストリにリアルタイムで照会する理由

スロップスクワットの要点は、特定の幻覚を狙って登録された新しい名前であることです。誰かが 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 件の単体テストを、実際の決定論的なフィクスチャですべて実施しています。解析と分類はネットワーク呼び出しを必要としない純粋関数であるため、ネットワーク呼び出しのモックは使用していません。実際の npm および PyPI レジストリを使ったエンドツーエンドの検証では、実在のパッケージ（react、vitest、requests）と、意図的にでっち上げたパッケージ名を混在させたフィクスチャを使用し、でっち上げた名前の両方を検出し、実在の名前では誤検出ゼロでした。また、ドッグフーディングの確認として、このモノレポ自体の package.json ファイルも対象に実行しました。実際の依存関係では誤検出がゼロで、正しい低重要度の検出が 1 件ありました（@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	critical	宣言されたパッケージ名がレジストリに存在しません
dependency_recently_published	low	パッケージは存在しますが、初回公開から 30 日未満です

---

設定（guardbee.yml）

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

---

制限事項（設計上のもの）

• 直接依存関係のみが対象です。 推移的依存関係（依存しているパッケージ自体が依存しているパッケージ）の中にある、でっち上げられた名前やスクワッティングされた名前はチェックされません。そのパッケージのメンテナーが公開時に、実在するレジストリ上のパッケージであることをすでに確認しているためです。
• 「最近公開された」というシグナルは、実際に判断が難しいものです。 新しいパッケージは常に公開されています。これは何かの証明ではなく、あくまで「詳しく確認してください」という促しにすぎないため、低重要度で報告されます。
• ネットワークに依存します。 チェックのたびに npm / PyPI レジストリへ HTTP リクエストを送信します。依存関係の多いプロジェクトではリクエスト数が増えます（同時実行数は最大 8 件）。レジストリの停止やレート制限は、誤った「存在しない」という検出ではなく、ツールエラーとして表示されます（レジストリエラーは、実際の 404 とは別に報告されます）。
• バージョン固定は考慮しません。 チェックするのはパッケージの名前が存在するかどうかであり、固定した特定のバージョン範囲自体に疑わしい点があるかどうかではありません。これは別の問題であり、すでに対応済みです（既知の CVE のチェックについては @guardbee/mcp-dependency-auditor を参照してください）。

---

開発

npm run build
npm test             # 18 unit tests

---

ライセンス

MIT — GuardBee

フィードバック

ご質問やアイデア、誤検知がありましたら、GitHub Discussionsでスレッドを開始するか、issue を作成してください。GuardBee が役に立った場合は、リポジトリに ⭐ を付けていただくと、ほかの方にも見つけてもらいやすくなります。