supply-chain-risk-auditor

サプライチェーンリスク監査

プロジェクトの直接依存関係（npm、PyPI、Go）についてサプライチェーンリスクレポートを生成し、さらにロックファイルが解決するすべての依存関係を対象にアドバイザリーを一括調査します。測定は2つの決定論的なスクリプトが行います。自動化をあえて行わない判断を担うのは、あなたです。

スクリプトに測定を任せる理由

このレポートに記載する数値はすべて、他者のプロジェクトに関する主張です。このスキルをスクリプト中心に作り直す前は、手作業で収集した数値を誤って測定していました。たとえば、GitHub のコントリビューター数からは lodash を5人以上で保守しているように見えましたが、npm の ACL では1人でした。また、週に1億6,400万回ダウンロードされているパッケージのダウンロード数を gh で調べると、ゼロと表示されました。保守担当者数、ダウンロード数、古さ、CVE の履歴を gh、ウェブ検索、記憶から推定してはいけません。必ずコレクターを実行し、測定結果を引用してください。

スクリプトには、出力を読む前に知っておくべき2つのルールがあります。

• データが利用できないことは、リスクの証拠にはなりません。 各基準の結果は、評価済み・問題なし、評価済み・問題あり、または理由付きの評価不能のいずれかになります。
• 測定値がないことは、問題なしの判定にはなりません。 測定対象がなかった実行では、問題なしとするレポートを出力せず、ゼロ以外の終了コードを返します。

ワークフロー

1. 対象ディレクトリにマニフェストがあることを確認します。対象は package.json、pyproject.toml、requirements*.txt、go.mod です。どれもなければ、その旨を伝えて終了します。このコレクターが手作業では解析できないエコシステムを監査してはいけません。正確なバージョンと推移的依存関係の一括調査には、次のロックファイルを読み取ります。package-lock.json／npm-shrinkwrap.json、uv.lock、および Go 1.17 以降の go.mod。yarn.lock、pnpm-lock.yaml、poetry.lock は読み取りません。これらが存在する場合は、その旨をレポートに記載し、バージョンはピン留めされた値か最新リリースにフォールバックします。

2. gh auth status を確認します。GitHub に未認証の場合、リクエスト上限は1時間あたり5,000件ではなく60件です。コレクターは依存関係ごとに複数回リクエストするため、認証がないとリポジトリの基準は評価不能になることが予想されます。黙って修正するのではなく、その旨を伝えてください。

3. データを収集し、その後レポートを作成します。特に指定がない限り、出力先は監査対象のリポジトリの外にしてください。

   uv run {baseDir}/scripts/collect.py <project-dir> --json <out-dir>/findings.json
   uv run {baseDir}/scripts/render.py <out-dir>/findings.json --out <out-dir>/report.md
   

   依存関係が約50件の場合、完了まで数分かかる見込みです。依存関係ごとに複数の HTTP リクエストがあり、Go モジュールが多いとさらに増えます。また、認証済みの gh が使えない場合は、より時間がかかります。collect.py がゼロ以外の終了コードで終了した場合、レポートを出すことを拒否しています。再試行したり回避策を講じたりせず、メッセージをそのまま伝えてください。

4. report.md と findings.json を確認します。納品物はレポートです。個々の判定の根拠となったデータが必要な場合は、JSON を参照してください。

5. コレクターでは対応できない内容を、測定結果と明確に分けて追加します。

   • 読者に向けた簡潔な説明。まず何に対処すべきか、その理由を記載します。
   • アドバイザリーで問題が見つかった依存関係のアップグレード経路。修正に必要なのがパッチバージョンかメジャーバージョンかを確認します。
   • 放棄された依存関係やアーカイブ済みの依存関係の代替候補。候補を挙げる前にレジストリに存在することを確認し、測定結果ではなく判断であることを明記します。
   • インストールスクリプトに問題がある場合、このプロジェクトのビルドで npm ci --ignore-scripts が実行可能かどうか。

追加する内容の文体

追加する文章はセキュリティレポートの文体で記述し、レポートの追記と最終回答にも同じ文体を適用します。回答はそのままチケットやレポートに貼り付けられます。検出事項、根拠となるデータ、対応を明示します。

• 非人称かつ断定的に記述します。一人称や二人称（「コレクターを実行しました」「アップグレードしてください」）、短縮形、感嘆符は使いません。
• 能動態を使い、対象を主語にします。「axios を 1.19.0 にアップグレードすると、25 件すべての勧告が解消されます」のように記述し、「axios をアップグレードすることが推奨されます」とは書きません。
• 客観的に記述します。強調表現や主観的な枠付け（「非常に」「重大な」「幸いにも」）、プロジェクトが選択した理由についての推測は避けます。
• 時制は、監査で実施した内容には過去形、依存関係の状態には現在形、対応した場合またはしなかった場合の結果には未来形を使います。
• 建設的に記述します。推奨事項では、責任の所在を問わず、対応内容とそのコストを示します。

セッションで report-writing:writing-style スキルを利用できる場合は、それに従ってください。この文体の詳細版です。

レンダリングされたレポートには事実のみを記載します。以下の解釈ルールは、読者向けの内容ではなく、指示です。免責事項や前置きとして成果物に含めないでください。

レポートの読み方

• 評価不能はリスクではありません。 PyPI はメンテナーの ACL を公開しておらず、Go にはレジストリがありません。該当する行は、問題点ではなく、何が判明しなかったかを示しています。
• すべての主張には、カバレッジ表が適用されます。 「勧告なし」は「評価対象の中に勧告がない」という意味です。クリーンという判定を繰り返す前に、評価対象の件数を確認してください。
• 数値は一字一句そのまま引用します。 レポートの数値を再計算、丸め、誇張しないでください。すべての数値は成果物から再現できます。
• 検出事項に記載がないことは、推奨を意味しません。 検出事項がない依存関係も、これらの基準に照らして評価されたにすぎません。

退けるべき合理化

• 「gh を使えば、コレクターより早くメンテナー数を調べられる。」実測では誤りでした。リポジトリのコントリビューターと、レジストリで公開する権限を持つ人は別の集団です。
• 「検出事項がないので、依存関係は安全だ。」カバレッジ表を確認してください。PyPI と Go では、基準の半数が仕組み上評価不能です。
• 「評価不能の行は読者を混乱させるだけなので、削除する。」その行はレポートのすべての主張の境界を示しています。削除すれば部分的なカバレッジが完全に問題なしという判定にすり替わります。これこそ、このスキルが防ぐために再構築された失敗です。
• 「バージョンはおそらく十分近い。」最新リリース時点で確認した範囲と、ロックファイルで解決されたバージョンは別の主張です。レポートにはどちらの主張かが明記されています。その表記を維持してください。

使用しない場合

• ライセンスコンプライアンス監査。
• 対象自身のソースコードから脆弱性やシークレットをスキャンする場合。このスキルは依存関係のソースコードを読み取らず、レジストリ、勧告、リポジトリのメタデータのみを参照します。
• プロジェクトのインストールやビルドの可否を判断する場合。この監査は依存関係リスト（マニフェストとロックファイル）だけで実行できるよう設計されており、インストール、ビルド、実行は一切行いません。インストールの失敗やインポート時の不具合は対象外です。ユーザーがそれらも確認されると考えているようであれば、その旨を伝えてください。
• npm、PyPI、Go 以外のエコシステム。監査を即興で行わず、該当するエコシステムはサポート対象外だと伝えてください。