pkgverdict

pkgverdict

npm パッケージをインストールする前にチェックします。コマンドは 1 つ、判定も 1 つです。GO、RISKY、FAKE、MISSING のいずれかを、AI コーディングエージェントにも読み取れる平易な言葉で返します。

pkgverdict は GHCR のコンテナーイメージとして提供されます（pkgverdict という名前の npm パッケージは存在しないため、npx pkgverdict は 404 になります。Docker を使用してください）。

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check react-markdown
# [GO] [email protected]
#   - 5y old, 38.4M/wk, no install scripts, no advisories, no lookalike name.

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check unused-imports
# [FAKE] [email protected]
#   - Flagged malicious: MAL-2025-48781. Do not install.
#   - Name rides on eslint-plugin-unused-imports (suffix of popular name) and the
#     package is barely downloaded — the classic typosquat shape.

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check react-super-hooks-plus
# [MISSING] react-super-hooks-plus
#   - react-super-hooks-plus is not on the npm registry. If an AI assistant
#     suggested it, the name was hallucinated.

理由

AI アシスタントは、開発者がインストールするパッケージの半数を選ぶようになりました。また、攻撃者がすでに登録した名前を幻覚で作り出すことがあります（スロップスクワッティング）。一方、タイポスクワッティングや乗っ取られたリリースでは、postinstall マルウェアが配布され続けています。npm audit が検出するのは公開済みのアドバイザリだけで、しかも事後です。pkgverdict はインストール前に、存在の有無、類似名、パッケージの経過年数、インストールスクリプト、メンテナー、ダウンロード数、OSV アドバイザリをチェックします。

AI コーディングツール内で使用する

コマンド 1 つでセットアップできます。プロジェクトディレクトリで、次を実行してください。

docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict init --agent claude-code

これにより、MCP サーバーの設定と、エージェントに唯一の行動ルールであるインストール前に pkgverdict をチェックすることを教える指示スニペットがインストールされます。対応ツールは claude-code、cursor、copilot（VS Code）、windsurf、cline、generic です（init --list ですべて表示、--all ですべてセットアップ、--dry-run で書き込みを行わずにプレビューできます）。ツールを再起動し、「MCP ツールを一覧表示して」というプロンプトで確認すると、2 つのツール（check_package、scan_dependencies）を備えた pkgverdict サーバーが表示されます。手動でインストールする場合は、基盤となるパックが integrations/ にあります。

CLI

# Verdict on one package (name or name@version)
docker run --rm ghcr.io/cloudcorprecords/pkgverdict check lodash

# Check every dependency in package.json, worst first
docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict scan
docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict scan ./my-app --no-dev

# Check your setup (Node version, registry + OSV reachability, cache)
docker run --rm ghcr.io/cloudcorprecords/pkgverdict doctor

# JSON output for scripting and CI
docker run --rm ghcr.io/cloudcorprecords/pkgverdict check left-pad --json

終了コード：すべてが GO の場合（または --strict を指定せずに RISKY がある場合）は 0、FAKE または MISSING のパッケージが見つかった場合は 1、使用方法に誤りがある場合は 2 です。疑わしいものがあれば CI ゲートで失敗させるには、pkgverdict scan --strict を実行してください。

判定

判定	意味
GO	広く利用されているパッケージで、危険な兆候はありません。安心してインストールできます。
RISKY	注意してください。インストールスクリプト、公開から間もない、知名度が低い、非推奨、リポジトリやライセンスがない、既知のアドバイザリがある、または問題のないパッケージによく似た名前です。インストール前によく確認してください。
FAKE	明らかに悪質な可能性があります。新しい、または知名度の低いパッケージのタイポスクワッティング風の名前、悪意のあるインストールスクリプト、または悪意のあるアドバイザリ（MAL- ID、MAL- エイリアス、もしくは詳細でパッケージ自体が悪意のあるもの／バックドア入りと示されている OSV レコード。例：GHSA ID で登録された [email protected] の侵害）などが該当します。インストールしないでください。
MISSING	レジストリに存在しません。入力ミス、または幻覚で作られた名前です。該当する場合は「もしかして」の候補を提示します。

検出シグナルは、npm レジストリ（メタデータ、ダウンロード数）、OSV データベース（アドバイザリ）、および類似名の検出に使用する同梱済みの有名パッケージ一覧から取得します。レスポンスは ~/.cache/pkgverdict にキャッシュされます（メタデータは 6 時間、アドバイザリは 1 時間）。最新の情報でチェックするには、このディレクトリを削除してください。

配布

pkgverdict の配布経路はちょうど 2 つで、どちらも意図的なものです。

1. GHCR：コンテナーイメージ ghcr.io/cloudcorprecords/pkgverdict。リリースごとに Publish container ワークフローがビルドしてプッシュします。
2. MCP Registry：リスティング io.github.CloudCorpRecords/pkgverdict。その server.json には OCI パッケージのみが記載され、同じ GHCR イメージを参照します。

npm パッケージは存在しません。これは意図したモデルであり、手順の漏れではありません。npx pkgverdict が 404 を返すのは想定どおりです。package.json のスコープなしの名前は、イメージのビルドと CLI のバージョン管理のために存在します。このパッケージは private に設定されているため、チェックアウトから誤って npm publish を実行しても、名前を確保することなくすぐに失敗します。また、リリースのたびに npm publish を実行していた古いテンプレートワークフローは、.github/workflows/publish.yml で無効化され、公開の代わりにこのモデルを出力します。将来 npm に公開するかどうかはメンテナーの判断となり、スコープ付きの名前と、その名前への権限を持つトークンが必要です。これらの事実は test/distribution.test.ts で固定されているため、残っている設定がひそかに復活することはありません。

Docker で実行する

GHCR イメージは主要な配布方法です：ghcr.io/cloudcorprecords/pkgverdict。

stdio MCP サーバーとして使用します：

docker run --rm -i ghcr.io/cloudcorprecords/pkgverdict

デフォルトの mcp 引数の代わりに、イメージ名の後に任意の CLI コマンドを指定できます：

docker run --rm ghcr.io/cloudcorprecords/pkgverdict <command> [args]

MCP サーバー

MCP クライアントの接続先を Docker（stdio）に設定します：

{
  "mcpServers": {
    "pkgverdict": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/cloudcorprecords/pkgverdict", "mcp"]
    }
  }
}

2 つのツールがあります：check_package（1 つのパッケージの判定）と scan_dependencies（プロジェクトの package.json に含まれる依存関係を、リスクが高い順に判定）。

開発

npm install
npm run build
npm test        # offline fixture corpus: every verdict rule pinned to a case

ライセンス

MIT。