1. 文書概要
1-1. 目的
本設計書は、生成AIの利用を前提とした開発環境において、npmパッケージの導入・更新・運用に伴うサプライチェーンリスクを低減し、組織として安全かつ継続可能なOSS運用を実現することを目的とする。
1-2. 背景
近年、以下の生成AI支援開発ツールが一般化している。
- ChatGPT
- GitHub Copilot
- Cursor
- Claude Code
生成AIは開発速度を大幅に向上させる一方、以下を保証しない。
- npm packageの安全性
- packageの実在性（ハルシネーションによる架空パッケージの提示）
- maintainerの信頼性
- install scriptの安全性
- OSSライセンス適合性
- サプライチェーン上の安全性
AIが提案した npm install を検証なしで実行する行為は、
サプライチェーン攻撃の入口となる可能性がある。
2. 基本方針
2-1. 原則：npm install は「コード実行」である
npm packageは単なる静的なライブラリではなく、以下のライフサイクルスクリプトを通じて、インストール時に任意のコードを実行できる権限を持つ。
preinstallinstallpostinstallprepare
2-2. ゼロトラスト方針
以下を大前提とする。
外部npm packageは原則として信用しない
2-3. AI提案コードの扱い
生成AIが提案したpackageおよびコードは、すべて「参考情報」として扱い、安全性や実在性の判断をAIへ委譲してはならない。
3. 適用範囲
本ルールは以下のすべての開発および自動化環境に適用する。
- Node.js開発 / フロントエンド開発全般
- 主要フレームワーク環境（Vite / Vue / React / Next.js / Nuxt 等）
- 開発者のローカル環境
- CI/CD環境（GitHub Actions 等）
4. npmパッケージ導入ルール
4-1. AI提案packageの検証
生成AIが提案したpackageを導入する際は、事前に以下の検証を必須とする。
| 確認項目 | 内容 |
|---|---|
| 実在確認 | npm registry上の存在確認（レジストリ直接確認） |
| Repository確認 | GitHub等の公開Repositoryが存在し、コードが確認できるか |
| maintainer確認 | 単独maintainer、または身元不明の場合は警戒・注意 |
| 更新頻度確認 | 長期放置（1年以上更新がない等）されていないか |
| install script確認 | package.json 内に pre/postinstall 等の記述の有無を確認 |
| ライセンス確認 | 商用利用可能か（GPL等のコピーレフト、SSPL等に注意） |
| weekly downloads確認 | 極端に少なくないか（利用実績・コミュニティ規模の確認） |
| package公開日確認 | AI提案の直後に公開されたものでないか（タイポスクワッティング等の罠の警戒） |
4-2. 実在確認手順
npm install を手元で実行する前に、必ずブラウザ等で以下のURLへアクセスし、packageの存在および詳細を確認する。
https://www.npmjs.com/package/<package-name>
※確認前の安易な install コマンドの実行は禁止とする。
4-3. 注意事項
「packageが実在すること」と「安全であること」は同義ではない
特に以下の条件に該当する場合は導入を厳重に警戒する。
- AI提案の直後に公開されたpackage
- maintainerが単独（アカウント乗っ取り時のリスク高）
- Repositoryが未公開（ソースコードが隠蔽されている）
- READMEのみが不自然に充実している
- download数が極小
- install script（postinstall等）への依存度が高い
4-4. 初回検証時の原則
未知のpackageを初めて検証・動作確認する際は、ライフサイクルスクリプトの実行を抑止するため、以下を強く推奨する。
npm install <package-name> --ignore-scripts
4-5. sandbox環境の推奨
未知のpackageの動作検証は、可能な限り専用検証環境、コンテナ、仮想環境などの権限制限環境で行うこと。
5. install運用ルール
5-1. CI/CDの原則
CI/CD環境におけるパッケージインストールでは、確実な固定バージョンの再現と高速化のため、以下を必須とする。
npm ci
※CI/CD環境での npm install の実行は一律禁止とする。
5-2. lockfile管理
依存関係の一貫性を保証するため、以下を必ずGit管理（コミット対象）とする。
package-lock.json
※lockfile未コミットでのプルリクエスト作成、およびリリースは禁止する。
5-3. install scriptの制御
CI/CD環境では、予期せぬスクリプト実行による認証情報の窃取を防ぐため、原則として以下を利用する。
npm ci --ignore-scripts
5-4. 例外規定
ネイティブバイナリの生成、プラットフォーム依存ビルド、または postinstall がビルドに必須である主要なpackageについては、安全性を確認した上で例外利用を許可する。
【例外許可パッケージの例】 esbuild, swc, prisma, sharp, canvas など
※なお、上記に挙げる主要かつ実績のある共通パッケージは、組織の「共通Allowlist」として初期状態で利用を許可する。
5-5. 例外承認フロー
共通Allowlistにない未知のpackageにおいて install script の実行が必要な場合は、事前に以下の承認フローを通すものとする。
- install scriptの内容およびソースコードの確認
- maintainerの信頼性・公開実績の確認
- CI/CDおよびビルド環境への影響確認
- プロジェクト個別Allowlistへの登録申請
6. 依存更新ルール
6-1. 定期点検
以下のコマンドを用いた脆弱性診断およびパッケージのバージョン点検を定期的に実施する。
npm audit npm outdated
6-2. 脆弱性対応の優先順位
脆弱性が検知された場合、影響度と環境汚染リスクを踏まえ、以下の優先度に基づき対応する。
| 対象（区分） | Runtime影響 | 環境汚染・Secret窃取リスク | 対応優先度 |
|---|---|---|---|
| dependencies | 高 | 高 | 最優先 |
| build chain (ビルドツール等) | 中 | 高 | 高 |
| devDependencies (Linter等) | 低 | 中〜高 | 中 |
6-3. 注意事項
devDependencies であっても、CI/CD環境や開発端末上で実行される場合、トークンや環境変数などのSecret窃取、および環境汚染のリスクを同等に持つことを認識しなければならない。
7. 本番運用ルール
7-1. 本番dev serverの禁止
開発用のランタイムコードやソースマップの露出、不要なモジュール実行を防ぐため、本番環境での以下を禁止する。
npm run dev
本番環境のコンテナおよびサーバでは、事前ビルドされた成果物の配信、または以下を使用する。
npm run build
7-2. devDependencyの除外
本番環境でNode.jsサーバを稼働させるインストール時は、不要なパッケージを一切含めないよう、以下を必須または推奨とする。
npm install --omit=dev
8. CI/CD secrets管理
8-1. 原則
npm install (ci) を実行する時点で、不要な環境変数・Secretを注入しない
8-2. 実施事項
- IAM最小権限： クラウドプロバイダ（AWS/GCP等）との連携は最小権限に留める
- Short-lived Token： OIDC等を用いた、有効期限の短い一時的なトークンの利用
- Environment分離： 構築フェーズ（Build）と配置フェーズ（Deploy）の環境を分離
- Build専用credential： パッケージ取得・ビルド時にデプロイ用の強権限トークンを露出させない
- Secret Scope最小化： 必要なステップでのみ環境変数を結合する
9. OSS採用基準
9-1. 推奨条件
- maintainerが複数名、または信頼された組織（企業・公式団体）により管理されている
- 継続的にアップデートが行われている（コミット履歴が活発）
- 週間のダウンロード数など、十分な利用実績・多数のコミュニティサポートがある
- install script（postinstall等）への依存が最小限、または存在しない
- SBOM（Software Bill of Materials）に対応、あるいは依存関係がクリーンである
9-2. 注意・警戒条件（要追加レビュー）
- 生成AIのみが言及・提案するpackage
- 過去の実績に対して、短期間で突然不自然に人気化したpackage
- 過度な install script への依存
- maintainerが個人単独、あるいは身元が一切不明な場合
- 更新が長期間停止しているpackage
10. 責任分界（Boundaries）
10-1. 項目ごとの責任定義
| 項目 | 実行・選定者 | 承認・責任者 |
|---|---|---|
| 通常packageの選定・導入 | 開発者 | Tech Lead（PRレビュー時の担保） |
| AI提案packageの導入 | 開発者（4-1, 4-2検証の実施） | Tech Lead（実在・安全性確認の最終承認） |
| install script含むpackage | 開発者 | Tech Lead / 管理責任者（例外承認フロー） |
| CI/CD環境への組み込み・運用 | DevOps担当 / 開発者 | Tech Lead |
| 本番環境へのデプロイ・リリース | 開発者 / CI/CDパイプライン | 管理責任者（プロダクトマネジメント） |
10-2. AI提案packageのガバナンス
生成AIが提案したpackageは、レビューおよび上記検証を通過しない状態での導入を一ランク禁止とする。
10-3. install script packageの制約
ライフサイクルスクリプトを含むすべてのpackageは、5-5に定める例外承認フローの通過を必須とする。
11. 推奨最低ライン（チェックリスト）
- ✓ package-lock.json のGit管理必須化
- ✓ CI/CDにおける
npm ciの徹底 - ✓
npm auditによる定期的な脆弱性スクリーニング - ✓ Dependabot等の自動依存関係監視ツールの常時稼働
- ✓ 新規パッケージ導入時のコードレビュー担保
- ✓ 生成AI提案時の「実在性・安全性」の二重検証
- ✓
devDependencyおよび本番環境の厳密な分離 - ✓ 本番環境における
npm run devの完全実行禁止
