depguard

depguard

npm リポジトリ向けの PR 時および依存関係変更の早期警告ツールです。Shai-Hulud / ChainDrop ワームファミリーは 2026 年に 500 以上の npm パッケージへバックドアを仕込み、preinstall ドロッパースクリプトを通じてインストール時に実行され、依存関係グラフを介して拡散しました。depguard は差分チェックツールです。リポジトリとベース（git ref または 2 つ目のマニフェストセット）を指定すると、package.json とロックファイルを比較し、追加、削除、変更されたすべての依存関係を証拠に基づいて評価します。変更がマージされる前にチェックできます。

基本判定は完全オフラインで決定的です。レジストリチェック（バージョンの経過時間、公開者の変更、プロベナンス、非推奨化）は、明示的に --online フラグまたは対応する MCP パラメーターを指定した場合にのみ実行されます。照会に失敗しても、ローカル判定が変わることはありません。

チェック項目

シグナル	ソース	ルール ID
リポジトリ独自の package.json に追加されたインストールスクリプト。内容がリモートコードを取得する、認証情報を読み取る、または文書化されている setup.mjs ドロッパー名を実行する場合は、リスクが引き上げられます	ローカル	INSTALL-SCRIPT-ADDED, INSTALL-SCRIPT-CHANGED
ロックファイルで、インストールスクリプトを持つものとして新たにマークされた変更済み依存関係。追加された依存関係に存在するインストールスクリプト	ローカル	INSTALL-SCRIPT-ADDED, INSTALL-SCRIPT-PRESENT
タイポスクワットの疑いがある追加名：リポジトリ独自の既存依存関係セットおよびパッケージに同梱された人気名リスト（約380件）との編集距離が1（長い名前の場合は2）	ローカル	TYPOSQUAT-SUSPECT, TYPOSQUAT-POSSIBLE
バージョンの異常：気付かれないダウングレード、安定版からプレリリースへの移行、セマンティックバージョニングに準拠しないバージョン、範囲の拡大（* または latest への拡大は高リスク）、新たに追加されたバージョン固定なしの範囲	ローカル	DOWNGRADE, PRERELEASE-JUMP, VERSION-PATTERN, RANGE-WIDENED, RANGE-UNPINNED
ロックファイルの不整合：マニフェストが変更されたのにロックファイルが同一、マニフェストが変更されていないのにロックファイルが変更、同じバージョンで解決先 URL のホストが変更、同じバージョンで整合性ハッシュが削除または変更	ローカル	LOCKFILE-DRIFT, LOCKFILE-ONLY-DRIFT, RESOLVED-HOST-CHANGE, INTEGRITY-REMOVED, INTEGRITY-CHANGED
ロックファイルのエントリがないマニフェスト依存関係（単一スナップショットモード）	ローカル	LOCK-MISSING
7日以内に公開されたバージョン、前のバージョンからの公開者またはメンテナーの変更、来歴証明の欠落、非推奨マーク、レジストリに存在しないバージョン	オンラインのみ	VERSION-AGE, MAINTAINER-CHANGE, NO-PROVENANCE, DEPRECATED, VERSION-NOT-FOUND
2つのバージョンの tarball の内容差分：インストールスクリプトを追加するバージョン更新、またはインストール時に実行されるファイル（スクリプトの対象とその相対インポート）に認証情報パス文字列、ネットワークエンドポイント、バイナリ、難読化されたコードらしきものを追加する更新。認証情報パスを読み込む preinstall を追加する目立たない更新は、追加されたシグナルを示して HIGH-RISK と判定されます。このようなシグナルがない無害なビルド用 postinstall は高リスクと判定されません	コンテンツモードのみ（--content）	CONTENT-INSTALL-SCRIPT-ADDED, CONTENT-INSTALL-SCRIPT-CHANGED, CONTENT-CRED-SIGNAL-ADDED, CONTENT-NETWORK-ENDPOINT-ADDED, CONTENT-BINARY-ADDED, CONTENT-OBFUSCATED-ADDED
レジストリの公開履歴：段階的なワームのパターン（0.0.0-stage のスタブ、囮に見えるリリース、その後 dist-tags.latest を保持する急速な回帰パッチ）、ステージスタブ、latest バージョンの回帰、急速な回帰クラスター、公開者とメンテナーの変更、リポジトリのスラッグの変更、来歴証明の消失	履歴モード（depguard history <name>）	HISTORY-STAGED-PATTERN, HISTORY-STAGE-STUB, HISTORY-LATEST-REGRESSION, HISTORY-RAPID-REGRESSION, HISTORY-MAINTAINER-CHANGE, HISTORY-REPO-CHANGE, HISTORY-PROVENANCE-DROP, HISTORY-PACKAGE-NOT-FOUND

ロックファイル：package-lock.json は完全に解析されます（v1 のレガシーツリーおよび v2/v3 の packages マップ）。yarn.lock と pnpm-lock.yaml は、解決済みのエントリとバージョンについてベストエフォートで解析されます。

判定：依存関係ごと、および全体の判定は CLEAR / REVIEW / HIGH-RISK です。各検出結果について、依存関係、変更内容、ルール ID、重大度、シグナルがローカルかオンラインかを示す証拠行が1つ出力されます。終了コードは、CLEAR の場合は 0、REVIEW または HIGH-RISK の場合は 1 です。

CLI

depguard check [path] [--json] [--offline] [--online] [--content] [--base <ref>] [--base-path <dir>]
depguard package <name> [version] [--json] [--online] [--content]
depguard history <name> [--json] [--registry npm|pypi]
depguard mcp

history（v0.3.0、台帳 P-159）は、1 つのパッケージのレジストリ公開履歴を分析し、段階的なワームのパターンや関連するシグナルを検出します。レジストリのメタデータのみを読み取り、tarball はダウンロードしません。v0.4.0 以降では、--registry pypi（または check_history の registry パラメーター）を指定すると、JSON API を通じて PyPI の履歴を読み取ります。npm と同じタイムラインチェック（段階的なパターン、段階スタブ、最新バージョンでの回帰、急速な回帰）をバージョンごとのアップロード時刻に対して実行し、さらに、ファイルがすべて取り下げられたリリースについて PyPI 固有の HISTORY-YANKED-VERSION 検出結果を報告します。PyPI はこの API を通じてバージョンごとの公開者、メンテナー、リポジトリ、プロベナンスのデータを提供しないため、npm のこれらのチェックは PyPI の履歴では実行されません。

check は、デフォルトで現在のディレクトリを対象に、オフラインのコア機能を単一スナップショットとして実行します（すべてのマニフェスト依存関係を、現在の状態に基づいて評価します）。ベースとの差分を取るには、--base HEAD~1（任意の git ref）または --base-path <dir> を渡します。package はリポジトリなしで、1 つの名前を評価します。JSON レポートにはタイムスタンプがないため、入力が同じであればバイト単位で同一の出力が生成されます。

--content を指定すると、コンテンツベースの更新評価が追加されます（v0.2.0、台帳 P-158）。変更または追加された依存関係ごとに、また、以前に公開されたバージョンがあるスナップショットの固定バージョンごとに、depguard は npm レジストリから両方のバージョンの tarball を取得し、インストール時の対象範囲を静的に比較します。tarball はメモリ上でのみ展開されます。depguard が tarball から何かをインストールしたり実行したりすることはありません。package モードで --content を指定した場合、指定したバージョンを、それより小さい公開済みバージョンのうち最大のものと比較します。

MCP

1 つの実行ファイルで CLI と stdio MCP サーバー（depguard mcp）を提供します。ツール：

• guard_path(path, base?, base_path?, online?, content?)：完全な差分レポートを JSON で返します。
• check_package(name, version?, online?, content?)：単一のパッケージ名とバージョンを評価します。
• check_history(name)：パッケージのレジストリ公開履歴を分析し、段階的なパターンや関連するシグナルを検出します。

制限事項

• ルートのマニフェストのみが対象です。ネストされたワークスペースの package.json ファイルやネストされたロックファイルは、v0.1.0 では一覧に含まれません。（台帳 P-132、既知の制限事項。）
• pnpm-lock.yaml の解析はキーに基づくベストエフォートです。解決済みの tarball URL は、ロックファイルの構造上、インラインで公開されている場合にのみ取得されます。そのため、解決先ホストの変更の検出精度は、package-lock.json、yarn.lock、pnpm-lock.yaml の順に高くなります。
• 依存関係自体のインストールスクリプトは、ロックファイルに記録されている場合（package-lock の hasInstallScript）、またはオンライン時にレジストリのメタデータで宣言されている場合にのみ把握できます。コンテンツモード（--content、v0.2.0）ではさらに、2 つのバージョンの tarball をダウンロードしてインストール時の対象範囲を比較しますが、検査は静的なものに限られます。tarball はメモリ上で展開されますが、何もインストールされず、tarball のコードが実行されることもありません。オフラインモードとオンラインモードでは何もダウンロードしません。
• コンテンツモードでは、インストールスクリプトの対象とその相対インポートを深さ 3 まで追跡します。依存関係内部のグラフのさらに深い場所に埋もれているシグナルや、インストール時に生成されるシグナルは、このシグナルの検出範囲外です。
• タイポスクワッティングの検出は名前の形状のみを対象とします。それ自体が一般的な名前を取り込んだ名前は検出されず（台帳 P-130）、編集距離が 3 以上になるよう巧妙に選ばれた名前も、このシグナルでは設計上検出できません。
• オンラインのシグナルの精度はレジストリの packument の品質に左右されます。公開者の比較には、それより小さいバージョンのうち最大のものに記録された公開者が使われます。また、プロベナンスとはレジストリのメタデータにアテステーションのエントリーが存在することを意味し、検証済みであることを意味するものではありません。
• 上限は明示され、通知なしに適用されることはありません。ロックファイルの解析はエントリー数 50,000 件で停止し、64 MiB を超えるマニフェストファイルはスキップされます。どちらも出力に報告されます（JSON の caps、人間向け出力の上限行、警告）。

開発

npm install
npm run build
npm test

TypeScript、Node >= 20、tsx --test によるテストを使用します。ユニットテストではネットワークを使用せず、レジストリの応答には注入されたフィクスチャを使います。