supply-chain-audit

supply-chain-audit

npm／PyPI のサプライチェーン侵害を対象とする、読み取り専用のフォレンジックスキャナーです。ローカルマシンに対して 3 つの IOC フェーズを実行し、明確な PASS／FAIL 判定を出力します。

呼び出すタイミング

ユーザーがサプライチェーンのリスク、最近公表された npm／PyPI の侵害、自分のマシンが影響を受けているかどうかについて質問した場合、またはこのチェックを同僚と共有したい場合に使用します。「IOC をスキャンして」「ホストを監査して」といった技術的な表現にも、「もう詰んだ？」「これは安全？」「ya me hackearon?」といったくだけた表現にも、確実に反応します。

仕組み

IOC パックは iocs.json にあり、各キャンペーンと、永続化パス、ペイロードファイル名、ペイロードハッシュ、C2／タイポスクワット文字列、オプション依存関係マーカー、リポジトリアーティファクトのハッシュ、偽装コミットの作成者、侵害されたパッケージスコープ、攻撃期間をまとめたバージョン管理されたリストです。スキャナースクリプト scripts/scan.sh はこのファイルを読み込み、次の 4 つのフェーズを実行します。

• フェーズ A — 永続化：再起動後も残るアーティファクト（LaunchAgent／systemd／Windows Run キー／~/.local/bin のシム、~/.claude/setup.mjs／~/.vscode/setup.mjs のドロッパーファイル、指定されたロックファイル）。
• フェーズ B — コードとキャッシュ：設定されたプロジェクトルート配下のすべての node_modules に存在するパッケージバージョン、ディスク上の任意の場所にあるペイロードファイル名、ロックファイルやソース内の悪意あるコミットハッシュ／タイポスクワットドメイン／ペイロードの SHA256、GitHub の git ref に解決される optionalDependencies エントリ（TeamPCP のすり替えパターン）。
• フェーズ C — 期間：キャンペーンの公表された攻撃期間中に、いずれかの node_modules 配下で書き込まれたファイル。フェーズ C がクリーンであることは、ホストが侵害を回避したことを示す単独のシグナルとして最も強力です。
• フェーズ D — リポジトリアーティファクトと git 履歴：マルウェアがプロジェクトリポジトリ内に配置するファイル（.vscode/tasks.json、.claude/settings.json、setup.mjs — ファイル名が一般的すぎるため、存在確認だけでは判定しません。repo_artifact_hashes と完全一致する SHA256 がある場合にのみ FAIL とします）、およびルート配下のすべての git リポジトリにある、forged_commit_authors に含まれる偽装された ID が作成者となっているコミット（Shai-Hulud 3.0 のパターン：claude <[email protected]>）。

各チェックでは find／grep／jq／stat／shasum／git log を使用します。スキャナーは共有ファイルシステムのインベントリーを一度だけ構築し（IOC ごとではなく、アーティファクト種別ごとに 1 回スキャン）、/tmp/supply-chain-audit-* 作業ディレクトリ以外には対象マシン上の情報を書き込みません。

実行フロー

1. iocs.json を読み、現在のキャンペーン一覧を把握します。--list が指定されている場合は、キャンペーンを要約して終了します。
2. プロジェクトルートを特定します。既定値は $HOME ですが、ユーザーが指定した、より限定的なパス（例：~/Clerk、~/Programming）を優先します。対象範囲が曖昧で、対象となるコードが 50GB を超える場合は、一度確認します。
3. bash scripts/scan.sh [root1 root2 ...] を実行します。スクリプトは構造化された Markdown レポートを標準出力に出力します。内容を取得します。
4. レポートを解析します。判定ロジック：FAIL の行のみが POTENTIALLY COMPROMISED の判定対象です。FAIL は、永続化アーティファクトの存在、ペイロードファイル名の検出、ペイロード SHA256 の一致、ロックファイル内の文字列 IOC、optionalDependencies による git ref のすり替え、リポジトリアーティファクトのハッシュ一致、git 履歴内の偽装された作成者によるコミット、またはフェーズ C の期間内ヒットなど、明確な侵害シグナルを意味します。インベントリー行（「ツリー内に @tanstack/query-core のコピーがあります」など）は REVIEW として出力され、判定を変えることはありません。2026 年 2 月に @tanstack/* がインストールされていることは、2026 年 5 月の悪意あるバージョンを取得したかどうかを示しません。それを判定するのがフェーズ C です。FAIL_COUNT > 0 の場合は POTENTIALLY COMPROMISED、それ以外は REVIEW > 0 であっても CLEAN です。
5. 以下の出力形式に従って、レポートをユーザーに提示します。

出力形式

必ず次の形式を使用してください。

# Supply-chain audit — <hostname> — <timestamp>

## Verdict: CLEAN  (or  POTENTIALLY COMPROMISED)

## IOC checklist
| Campaign | Check | Result |
|----------|-------|--------|
| ...      | ...   | PASS/FAIL/REVIEW/skipped |

## Inventory — packages from compromised scopes (REVIEW, not FAIL)
(only if Phase B found compromised scopes installed; list `name@version`, install date, path)

## Phase summary
- Phase A (persistence): N fail(s)
- Phase B (code & cache): N fail(s), M review(s)
- Phase C (time window): N fail(s) — authoritative exposure signal
- Phase D (repo artifacts & git history): N fail(s)
- Total: P PASS / F FAIL / R REVIEW / S skipped

## Next steps
<remediation block — see references/remediation.md>

REVIEW 行をユーザーに要約するときは、インストール日時を iocs.json のキャンペーンの攻撃期間と照合してください。インストール日が期間外で、かつ Phase C がクリーンな場合 → これらのパッケージは安全です。その旨を簡潔に伝えてください。インストール日が期間内の場合 → 該当行を「開示された悪意のあるバージョンの一覧と手動で照合が必要」に引き上げてください。

判定が POTENTIALLY COMPROMISED の場合、「次の手順」ブロックは必ず次の内容から始めてください。

GitHub PAT はまだ取り消さないでください。 Mini Shai-Hulud / TeamPCP ペイロードは、盗まれたトークンを監視し、api.github.com から 401 を検知した瞬間に rm -rf ~/ を実行するデッドマンスイッチをインストールします。まず https://github.com/settings/tokens でトークンのアクティビティを監査してください（直近 72 時間に見慣れない IP アドレスや User-Agent がないか確認します）。その後、別のクリーンなマシンからローテーションしてください。対象は npm パブリッシュトークン、クラウド認証情報（AWS/GCP）、SSH キー、Vault トークンです。疑わしいホストから移行を完了してから、疑わしい PAT を取り消してください。

判定が CLEAN の場合、「次の手順」ブロックで 48 時間のベイク期間を推奨してください。

npm config set min-release-age 2            # npm 11+
pnpm config set minimumReleaseAge 2880      # minutes
echo -e "[install]\nminimumReleaseAge = 172800" >> ~/.bunfig.toml   # seconds
yarn config set npmMinimalAgeGate 48h

完全な修復手順は references/remediation.md に記載されています。ユーザーが詳細を求めた場合は、そのファイルを読んでください。

IOC パックの更新

新しいキャンペーンが公表されたら、スキーマに従って iocs.json に新しいエントリーを追加してください。スキャナーが自動的に取得するため、スキル本体を編集する必要はありません。スキーマの参照先は iocs.json 自体の先頭を確認してください。version フィールドを今日の日付に更新してください。

ユーザーが IOC パックに含まれていないまったく新しいキャンペーンを報告している場合は、追加を提案してください。次の情報を尋ねてください。キャンペーン名、開示日、影響を受けるスコープ／パッケージ、ペイロードのファイル名、ペイロードのハッシュ（SHA256）、C2／タイポスクワットドメイン、永続化パス、攻撃期間（UTC）。その後、新しいエントリーを記述し、スキャンを再実行してください。

プラットフォームのサポート

• macOS：完全にサポートされています（LaunchAgent のパスはネイティブです）。
• Linux：完全にサポートされています（systemd-user のパス）。
• Windows：ベストエフォートです。WSL または Git Bash 経由で実行してください。Windows の Run キーのチェックでは、reg query が利用可能な場合はそれを使用し、利用できない場合は pass ではなく skipped としてマークします。

厳守事項

• 読み取り専用。 許可されるツール：find、grep、jq、stat、ls、shasum、awk、sed -n（出力のみ）、git log（ローカルの履歴を読み取る場合のみ。fetch／pull は禁止）、reg query（Windows）。禁止事項：/tmp/supply-chain-audit-* 作業ディレクトリ外に書き込むあらゆるリダイレクト、依存関係を解決するパッケージマネージャーコマンド（npm install、pnpm install、bun install）、api.github.com またはレジストリへのネットワーク呼び出し。
• 認証情報に触れないでください。 ~/.npmrc、~/.ssh/、~/.aws/、またはトークンのような文字列を含む環境変数を読み取ってはいけません。目的はマルウェアの検出であり、その過程でユーザー自身の秘密情報を流出させることではありません。
• デッドマンスイッチの警告を伝える前に、FAIL に対して取り消しを提案しないでください。 これは絶対厳守です。感染したホストで先に取り消すと ~/ が消去されます。

参考資料

• iocs.json — バージョン管理された IOC パック。唯一の信頼できる情報源です。
• references/campaigns.md — 各キャンペーンの説明、攻撃者の帰属、手法の連鎖。
• references/remediation.md — ベイク期間の完全な設定手順、侵害後の対応手順、認証情報のローテーション順序。
• scripts/scan.sh — スキャナー本体です。対象範囲を拡張する必要がある場合は読んでください。