robert-auger/safer-dependenciesAIコーディングアシスタント向けの自動依存関係セキュリティレイヤー。npm、PyPI、RubyGems、Maven、Go、Rustエコシステム全体で、パッケージのCVE、タイポスクワッティング、放置、バージョン経年問題、ハッシュ整合性を監査します。
ClaudeのようなAIコーディングアシスタントがプロジェクトにパッケージを追加するとき、多くの場合、既知のセキュリティ脆弱性があるかどうか、パッケージがまだ積極的にメンテナンスされているかどうか、あるいは名前が悪意のある偽物とタイプミス1文字違いではないかどうかを確認せずに、適当に聞こえるバージョンを選びます。
safer-dependenciesはClaude Codeのセキュリティレイヤーです。Claudeとマニフェストファイルの間に位置し、セキュリティチェックを自動的に実行します。脆弱なインストールは実行前に拒否され、マニフェストに書き込まれたリスクのあるバージョンは書き込み直後にディスク上で修正されます。CVE、タイポスクワット、放棄されたパッケージ、バージョンの古さの問題に加え、新規リリースに対するクールダウン期間を検出して修正し、npm、PyPI、RubyGems、Maven、Go、Rust、PHP（Composer）に対応しています。正確に何がカバーされ、何がカバーされていないかはCAPABILITIES.mdを参照してください。
初めての方ですか？ GETTING-STARTED.mdでは、約5分でゼロから動作するインストールまでを案内します。
セキュリティとプライバシー： SECURITY.md（脆弱性の開示）、PRIVACY.md（データ外部送信、テレメトリなし）、CAPABILITIES.md（このツールが防御するものとしないもの）を参照してください。
ライセンス（ソース利用可能 — OSI「オープンソース」ではありません）： 自分の目的のために自由に使用・変更できます。営利目的・社内利用、販売する製品の構築を含みます。ソフトウェア自体を収益化する場合 — 販売、販売される製品やサービスへの同梱、または第三者への機能提供（ホステッド/SaaS/APIを含む）に対する有料提供 — にはのみ、別途有料ライセンスが必要です。再配布および派生物はライセンスを保持し、このプロジェクトへのクレジットを記載する必要があります。LICENSE（商用制限についてはセクション4）を参照してください。商用ライセンスのリクエストはgithub.com/robert-augerまで。
**GETTING-STARTED.mdでは、前提条件、対話型インストール、検証を含め、約5分でゼロから動作するインストールまでを案内します。完全なインストールリファレンス（グローバル/プロジェクト/手動インストール、Windows固有の詳細、権限許可リスト、更新、アンインストール）については、INSTALLATION.md**を参照してください。
日常的な使用： フックがインストールされると、実行するものは何もありません — safer-dependenciesはバックグラウンドで自動的に動作します。Claudeがパッケージを追加またはインストールする際、リスクのある依存関係にフラグを立て、脆弱なバージョンをその場で安全なものにアップグレードし、既知の脆弱なインストールは実行前にブロックします — そのため、安全でないパッケージはあなたが依頼しなくても検出・修正されます。いつでも直接呼び出すこともできます：「[email protected]は安全ですか？」、「safer-dependenciesのセットアップを確認して」、「safer-dependenciesの統計情報を表示して」。
Claudeがプロジェクトにパッケージを追加しようとするとき、safer-dependenciesはインターセプトして5つのチェックを実行します：
--hash=sha256:...ピンを含むPyPI requirements.txt行について、宣言されたハッシュがPyPIの公開ハッシュと照合され、不一致はWARNINGを発しますpaperclip、request、pycrypto、github.com/dgrijalva/jwt-go）は、代替案の提案とともに即座にハードブロックされます。2年以上安定版リリースがないパッケージには、アドバイザリのSTALE:警告が発行されます。ハードブロックされたパッケージはマニフェストから削除され、Claudeが今後の進め方を尋ねます。陳腐化のみのパッケージはそのまま残されます。問題が見つかった場合、Claudeは警告を発し、より安全なバージョンに戻ることがあります。すべてのチェックは~/.claude/safer-dependencies-audit-YYYY-MM.log（暦月ごとに1ファイル）に記録されます。
このスキルは、Claudeが以下の操作を行うときに自動的に発動します：
マニフェスト / インストール操作
package.json、requirements.txt、Gemfile、pom.xml、build.gradle、Cargo.toml、go.mod、その他の対応マニフェストでパッケージを追加または更新import、require、useを書き込むnpm install、bundle install、poetry install、uv sync、go mod tidyなど）— インストール前はコマンド引数を監査し、インストール後は結果のロックファイルを監査DockerfileまたはCIワークフロー（.github/workflows/*.ymlなど）を書き込む選択・推奨に関する質問
使用意図の表明（追加前）
パッケージの健全性と信頼性に関する質問
スキャフォールディングコマンド
npx create-react-app、npm create vite@latest、django-admin startproject、rails new、cargo new + cargo add、「新しいFastAPIプロジェクトをブートストラップ」暗黙のパッケージ追加（新しい依存関係を意味する機能リクエスト）
移行と移植
以下の場合には発動しません：
os、fs、java.util.*など）これはスキル + フックのバンドルであり、単一のスキルファイルではありません。完全なインストールでは以下の要素が展開されます：
| ファイル | 役割 |
|---|---|
skills/safer-dependencies.md | スキル（インストール後はSKILL.md）。監査手順を説明し、インストール/統計のための管理モードを含みます。 |
skills/safer-dependencies-shim.sh | PostToolUse:Write/Editフック — マニフェストとロックファイルの書き込みを監査し、脆弱なバージョンをその場で自動修正します（インターセプトモード）。 |
skills/safer-dependencies-pretooluse-bash.sh | PreToolUse:Bashフック — パッケージマネージャーのインストールコマンドの事前OSV監査。インストール実行前に脆弱な具体的ピンを拒否します（インストール前モード）。 |
skills/safer-dependencies-posttooluse-bash.sh | PostToolUse:Bashフック — Bashコマンド後の事後監査。新しく書き込まれたロックファイル、sed/jq/スクリプトで編集されたマニフェスト、および素のpip installの解決済み環境における推移的CVEを捕捉します（インストール後モード）。 |
skills/safer-dependencies-pretooluse-agent.sh + skills/safer-dependencies-posttooluse-agent.sh | PreToolUse:Agent + PostToolUse:Agentフックペア — サブエージェントのカバレッジギャップを解消します。モード2〜4はルートセッションのツール呼び出しでのみ発動するため、サブエージェントが書き込むマニフェストはこれらをバイパスします。Post-Agentは各Agentツール呼び出しが戻った後にサブエージェントが書き込んだものを監査します（エージェント後モード）。 |
skills/scripts/ | すべてのフックで使用される共有Pythonライブラリ（safedep/）とスタンドアロンのリゾルバースクリプト。 |
skills/scripts/safer_dependencies_manager.py | 対話型インストール、使用統計、セットアップ検証のための管理モジュール。 |
スキルファイルだけでは不十分です — フックがなければ、自動呼び出しはClaudeがスキルに手を伸ばすかどうかに依存します。完全なカバレッジのために5つの要素すべてをインストールしてください。多くのスキルやスラッシュコマンドは内部的にサブエージェントをディスパッチするため、明示的にサブエージェントを起動しなくてもPost-Agentペアは重要です。（スキル単独ではカバレッジを保証できない理由についてはFAQ.mdを参照してください。）
| エコシステム | マニフェスト | ロックファイル |
|---|---|---|
| npm | package.json | package-lock.json、yarn.lock、pnpm-lock.yaml |
| PyPI | requirements.txt、pyproject.toml、Pipfile、setup.py、setup.cfg | Pipfile.lock、poetry.lock、uv.lock |
| RubyGems | Gemfile、*.gemspec | Gemfile.lock |
| Maven | pom.xml、build.gradle、libs.versions.toml | -- |
| Go | go.mod | go.sum |
| Rust | Cargo.toml | Cargo.lock |
| PHP（Composer） | composer.json | composer.lock |
プロジェクトに初めて参加しますか？**GETTING-STARTED.md**から始めてください。簡単なバージョンは以下の通りです：```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install
インストーラーは、スコープ（グローバルかプロジェクトか）と有効にするフックをプロンプトで尋ね、その後、フックエントリ**と**、スキルのチェックコマンドが監査のたびに承認プロンプトなしで実行できるようにする権限許可リストの両方を`settings.json`に書き込みます。
インストール関連のその他すべては**[INSTALLATION.md](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md)**に記載されており、インストールの仕組みに関する唯一のリファレンスです：手動でのファイル単位のインストール（グローバルおよびプロジェクトレベル）、Windows固有の事項、Post-Agentフック、[権限許可リスト](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md#permissions-allowlist)、セットアップの検証、更新、リリースタグへの固定、アンインストールについて説明しています。
インストール後、日常的な管理はClaudeへの自然言語で行います — `install safer-dependencies`（再実行／フックの変更）、`show safer-dependencies stats`、`check safer-dependencies setup` — または`/safer-dependencies`メニューを使用します。更新もセッション内で行います：`/safer-dependencies update`で最新リリースを適用します（`update --check`でドライラン、`update --rollback`で元に戻す）。信頼モデルについては[INSTALLATION.md](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md#in-session-self-updater-safer-dependencies-update)を参照してください。
> **プラットフォームに関する注意：** macOS、Linux、Windowsがサポートされています。WindowsではGit for Windows（bashを提供）と`PATH`上のPython 3が必要です — WSLは不要です。これまでの実機テストは**macOSとWindows**に重点を置いています。Linuxサポートは自動化されたCIマトリックスで検証されています。
### 設定
インストール後に設定可能な項目は2つあります：
- **権限許可リスト** — スキルの読み取り専用チェックコマンド（完全一致形式の`npm audit` / `bundle audit`ルールとスキル自身のリゾルバスクリプト）を事前承認し、監査が毎回承認プロンプトなしで実行されるようにします。`curl`は決して事前承認されず、`npm view` / `pip-audit`はConvenienceプロファイル経由でオプトインとなります。対話型インストーラーがコアエントリを書き込みます。手動インストールでは完全なブロックを手動で追加します。完全なブロックと根拠：[INSTALLATION.md → 権限許可リスト](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md#permissions-allowlist)。
- **セキュリティポリシー** — リリース経過期間のクールダウンウィンドウ／モードと、各チェックタイプに対する`off`/`warn`/`block`の階層。`/safer-dependencies config`で編集し、`~/.config/safer-dependencies/config.toml`に保存されます。スキーマと階層の意味論：[`skills/references/configuration.md`](https://github.com/robert-auger/safer-dependencies/blob/main/skills/references/configuration.md)。
### クールダウン期間の変更
クールダウン（設定では**cooloff**と呼ばれる）は、スキルがリリースを選択する前に経過しなければならない最小期間です — デフォルトは**7日**です。変更するには、Claudeに依頼するか、設定コマンドを直接実行します：```
/safer-dependencies config set cooloff.days 14 # require releases to be 14+ days old
/safer-dependencies config set cooloff.mode block # gate strength: off | warn | block (default: warn)
/safer-dependencies config unset cooloff.days # revert to the 7-day default
/safer-dependencies config # show effective values and where each comes from
同じ動詞はClaudeセッション外でも機能します：```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14
設定は `~/.config/safer-dependencies/config.toml`（`[cooloff]` セクション）に保持されます。`SAFE_DEP_COOLOFF_DAYS` と `SAFE_DEP_COOLOFF_MODE` 環境変数は、セッションごとにファイルを上書きします。知っておくべき3つの動作: `mode = "off"` はバージョン選択から期間フィルタを完全に削除します。CVE駆動の書き換えはゲートをバイパスするため、セキュリティ修正が新しすぎるという理由で保留されることはありません。また、このゲートは npm、PyPI、RubyGems、crates.io を対象とし、Maven と Go は意図的にゲート対象外です。完全なセマンティクス: [`skills/references/configuration.md`](https://github.com/robert-auger/safer-dependencies/blob/main/skills/references/configuration.md)。
## 警告レベル
| レベル | 意味 | 例 |
|-------|---------|---------|
| CRITICAL | 停止してユーザーに確認 | タイポスクワット検出、署名改ざん |
| HIGH | 警告して続行 | 既知のCVE、公開から30日未満のパッケージ |
| MEDIUM | 警告して続行 | 公開から7日未満のバージョン、署名なし |
| LOW | 警告して続行 | 未署名のRuby gem（想定内） |
## 仕組み
このスキルは5つのモードで動作します（以下に要約。最も深い設計根拠は `skills/safer-dependencies.md` にあります）:
### 通常モード（手動）
Claude が `import` を記述しようとする、マニフェストにパッケージを追加しようとする、またはロックファイルを更新しようとするとき、スキルはセッション内でインライン実行されます:
1. パッケージレジストリに安定版を問い合わせる
2. 公開から7日以上経過した最新バージョンを自動選択する（決定論的 — LLMの判断なし）
3. エコシステムツールとOSV APIを通じて既知の脆弱性をチェックする
4. 利用可能な場合はパッケージ署名を検証する
5. 問題が見つかった場合は警告を発し、正確なバージョンを固定する
6. 結果を監査証跡に記録する
バージョン選択は、ルールを解釈するLLMではなく、スキルに同梱されたスタンドアロンのPythonスクリプトによって処理されます。コマンドは `SELECTED: <version>` を出力し、Claude はそのバージョンを正確に使用します。
### インターセプトモード（自動）
`.claude/settings.json` に `PostToolUse` フックを設定して、自動的かつ透過的なパッケージ検証を有効にします:
1. Claude が元々リクエストされたバージョンでマニフェストファイル（例: `package.json`）を書き込む — ファイルはディスクに保存される
2. `PostToolUse` フックは書き込み完了直後に発火し、`safer-dependencies-shim.sh` を呼び出す
3. シムはファイルを読み取り、宣言されたパッケージを解析し、すべてのセキュリティチェック（タイポスクワット、放棄、CVE、陳腐化、ハッシュ固定）を実行する
4. 修正が必要な場合、シムは安全なバージョンで**マニフェストをその場で書き換える**（または安全なバージョンがないエントリを削除する）
5. シムは `hookSpecificOutput.additionalContext` を介してstdoutにシグナル（`UPDATED:`、`BLOCKED:`、`WARNING:`、`STALE:`、`MAJOR-UPDATE-CONFIRM:`、`REFACTOR-REQUIRED:`、`REGRESSION:`、`TYPOSQUAT-CONFIRM:`、`VERIFY:`、`CLEAN:`）を発する。監査ログが同じ（ファイル、パッケージ）が以前に同じ安全なターゲットに修正されたことを示す場合、`REGRESSION:` は `MAJOR-UPDATE-CONFIRM:` の前に付きます — つまり、サブエージェントまたは古いプランが既知の脆弱なバージョンを再導入したため、オーケストレーターはメジャーバンプを再決定するのではなく、以前に承認されたバージョンを復元する必要があります。
6. Claude はそれらのシグナルをシステムリマインダーとして受け取り、フォローアップ作業（影響を受けるインポートの検索、テストの実行、破壊的変更のためのリファクタリング）を実行する
**設計ノート — Shape C（書き込み後修正）:** フックは書き込みをブロックしません。各脆弱なバージョンはまずディスクに保存され、その後同じツール使用サイクル内で自動修正されます。これは `PreToolUse` ブロッキング設計に対する意図的な選択です — トレードオフについては [FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/main/FAQ.md#why-posttooluse-post-write-corrective-instead-of-pretooluse-pre-write-blocking-for-the-manifest-path) を参照してください。
**シグナルの例:**```
UPDATED: aiohttp 3.8.5 → 3.9.0 (HIGH: 33 CVEs fixed)
親エージェントはこれらのシグナルを使用して影響を受けるコードを特定し、必要に応じてリファクタリングします。
パッケージマネージャーのインストールコマンドの事前監査を有効にするには、.claude/settings.json に PreToolUse:Bash フックを設定します。これはインターセプトモードを補完するものであり（置き換えるものではありません）、両者を組み合わせることで多層防御を形成します。
npm install [email protected]）PreToolUse フックが発火し、safer-dependencies-pretooluse-bash.sh を呼び出しますgit status / ls / npm test はホットパス上で無視できるコストしか発生しませんnpm/pnpm/yarn の install/i/add）では、ヘルパーが shlex でトークン化し、各 pkg@version 引数を抽出してOSVにPOSTしますpermissionDecision: "deny" を返し、検出結果ごとのGHSA-ID + CVSS + サマリーに加え、safer-dependenciesスキルを呼び出すヒントを返しますインターセプトモードに加えてこれが存在する理由: 書き込み後シムはBashを認識できません。npm install [email protected] は監査が発火する前に完了まで実行され（postinstallスクリプトも実行されます）。npm install -g typosquat-pkg はプロジェクトのマニフェストを一切書き込みません。インストール前モードはこれらのギャップを構造的に埋めます。
インストール前モードは、ユーザーが入力した内容（コマンドライン上の pkg@version 引数）のみを認識します。リゾルバが実際にインストールする推移的な依存ツリーは認識できません。インストール後モード（下記）は、インストール完了後にロックファイルを監査します — この2つのモードは補完的であり、冗長ではありません。
対象範囲: ここでカバーされるパッケージマネージャーCLIは5つのエコシステムに及びます（npm/pnpm/yarn/bun/npx/deno、pip/pip3/pipx/pipenv/uv/uvx/poetry、gem/bundle、go、cargo）。さらにMavenはインターセプトモード経由でカバーされます（Mavenの依存関係は通常、CLI動詞で追加されるのではなく、pom.xml/build.gradle で宣言されます）。
既知のギャップ: Maven CLIは
mvn dependency:get -Dartifact=group:art:versionおよびmvn dependency:copyによる直接ダウンロードをサポートしています。このフックはまだこれらの呼び出しを認識しません。これらを定期的に使用する場合、既存の書き込み後シムがマニフェストに書き込まれた内容を引き続き捕捉しますが、フェッチ前保護は上記のエコシステムにのみ適用されます。フォローアップとして追跡されています。
認識されるエコシステム別の構文:
| PM | 動詞 | 具体的なピン構文 |
|---|---|---|
npm, pnpm, yarn, bun | install, i, add（さらに yarn/pnpm dlx、bun x、yarn create） | [email protected], @scope/[email protected] |
npx | （動詞なし — パッケージは最初の位置引数） | [email protected] |
deno | add, install | npm:[email protected]（npmプレフィックス付きスペック） |
pip, pip3, pipx, pipenv, uv, uvx, poetry | install（pip/pip3/pipx/pipenv）/ add（uv/poetry）/ 動詞なし（uvx） | pkg==1.2.3（エクストラ pkg[extra]==X も処理） |
gem, bundle | install（gem）/ add | -v 1.2.3, --version 1.2.3, --version=1.2.3（別フラグ） |
go | get, install | [email protected]（Goモジュールの規則により v プレフィックス必須） |
cargo | add, install | [email protected] |
範囲ピン（npm ^4.17、pip >=、poetry ^/~、Go @latest）およびバージョン未指定のものは、インストール後にインターセプトモードへ通過します — 書き込み後シムがリゾルバが選択した内容を監査します。安全なバージョンへの自動書き換えはフォローアップとしてキューに入っています。
障害モード: フェイルオープン。エラー（Python欠落、ネットワーク障害、不正な入力）は出力なしで終了コード0を返し、bashの続行を許可します。インターセプトモードはインストール後も実行されるため、事前チェックの失敗は既存の保護へグレースフルに縮退します。
拒否の例:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:
### インストール後モード（Bashフック）
`.claude/settings.json` に `PostToolUse:Bash` フックを設定すると、Bashコマンド実行後の監査が有効になります。このフックは、コマンドの `cwd` に対して**3つの独立したスキャン**を実行し、それぞれが他のフックでは対応できないギャップを埋めます。
- **スキャンA — ロックファイル。** インストール動詞（`npm install`、`bundle install`、`poetry install`、`uv sync`、`go mod tidy` など）の成功後、新しく変更されたロックファイル（`package-lock.json`、`Gemfile.lock`、`poetry.lock`、`uv.lock`、`go.sum`、`yarn.lock`、`pnpm-lock.yaml`、`Pipfile.lock`）を監査します。これにより、Pre-Installでは見えない**推移的CVEギャップ**を埋めます。ユーザーは `pkg@version` と入力しましたが、リゾルバは誰も指定していない多数の推移的依存関係を取り込んだ可能性があります。
- **スキャンB — マニフェスト。** 読み取り専用の拒否リスト（`ls`、`cat`、`git status` など）にないBashコマンドの実行後、新しく変更されたマニフェストを監査します。これは、`sed -i`、`jq`、またはスクリプトによるマニフェスト編集に対する**唯一の**フォールバックです。これらの編集は、Intercept Modeがフックする `Write`/`Edit` ツールをバイパスします。
- **スキャンC — 解決済み環境。** 通常の `pip install` / `pip install -r requirements.txt` はロックファイルを書き込まないため、スキャンAは解決済みツリーを認識できません。pip形式のインストール後、スキャンCは同じpipを読み取り専用の `list --format=json` で再呼び出しし、解決済み環境全体（直接＋推移的）をOSVチェックします。
スキャンの実行方法:
1. ClaudeがBashツール呼び出しを実行
2. `PostToolUse` フックがコマンド完了*後*に発火し、`safer-dependencies-posttooluse-bash.sh` を呼び出します
3. 純粋なBashによる早期フィルタが、約115msでどのスキャンゲートにも一致しないコマンドを短絡します（Pre-Installと同じ高速パス規約）。そのため、`ls` / `git` / `cat` のコストは無視できる程度です
4. 各スキャンは `find -maxdepth 5` で `cwd` を走査し（モノレポ構成に対応。`node_modules`、`.git`、`.venv`、`venv` は除外）、直近60秒以内に変更されたファイルを探します — `SAFE_DEP_POSTINSTALL_MTIME_WINDOW` で上書き可能
5. 新しく変更された各ファイル（スキャンA/B）について、フックは合成の `PostToolUse:Write` ペイロードを偽造し、既存のシムにパイプします — シムのロックファイル監査とマニフェスト監査は変更なしで実行され、ロジックの重複はありません
6. ファイルごとのシグナルが連結され、1つの `hookSpecificOutput` JSONとして親エージェントに送信されます
**Pre-Installでは検出できないもの:** 推移的脆弱性。一見クリーンな `bundle install` でも、`sinatra` の推移的依存関係として `[email protected]`（CVE-2025-27610）を取り込む可能性があります — ユーザーは `rack` と入力していないため、Pre-Installでは検出できませんが、Post-Installは解決済みの `Gemfile.lock` を読み取り、CVEを報告します。
**スコープ:** スキャンAは解決済みバージョンを書き換えません — 自動修正契約は、Claudeが直接書き込んだマニフェストにのみ適用されます。推移的CVEの場合、修正は通常「推移的依存関係を所有する直接依存関係を更新する」ことであり、人間の判断が必要です。スキャンBは*自動修正*を行います。Intercept Modeと同じシムパスを通じてマニフェストを監査するためです。スキャンAは、`transitive` チェック層が `off` に設定されている場合（`config set checks.transitive off`）はスキップされます。
**障害モード:** 他のフックと同様にフェイルオープンです。エラー（シムの欠落、ペイロードの不正、Pythonが利用不可）はすべてサイレントに終了コード0を返します。
**WARNINGの例:**```
WARNING: [email protected] in lock file has GHSA-29mw-wpgm-hmr9, GHSA-35jh-r3h4-6jhm
上記の4つのモードは、ルートセッションのツール呼び出しに対してのみ発火します。ルートセッションがサブエージェントをディスパッチする場合（Agentツール経由 — 多くのスキルやスラッシュコマンドが内部的にこれを行います）、サブエージェントのWrite/Edit/Bash呼び出しはこれらすべてをバイパスします。ポストエージェントモードは、そのギャップに対するリアクティブなセーフティネットです。
PreToolUse:Agentフック（safer-dependencies-pretooluse-agent.sh）が各Agentディスパッチの直前に実行され、/tmp/.safer-deps-agent-<PPID>-<session_id>.sentinelにセンチネルファイルを作成します（セッションIDが利用できない場合はPPIDのみの名前にフォールバック）PostToolUse:Agentフック（safer-dependencies-posttooluse-agent.sh）がAgent呼び出しの戻り後に実行され、センチネルより新しいすべてのマニフェストとロックファイルをfindし、同じshimパスを介してそれぞれを監査しますadditionalContextとしてルートセッションの次のターンに表示されます。センチネルは削除されますネストされたサブエージェントは自動的にカバーされます — ルートのPostToolUse:Agentは、外側のエージェントのすべての作業（それがディスパッチしたものを含む）がディスクに書き込まれた後にのみ発火します。唯一のギャップは、マニフェストやロックファイルを書き込まないグローバルインストール（npm install -g …）です。スキャンするものがありません。他のフックと同様に、フェイルオープンします — エラー（センチネル欠落、shim欠落、ペイロード読み取り不能）はすべてサイレントに終了コード0で終了します。完全な設計根拠はskills/safer-dependencies.mdにあります。
すべてのチェックは~/.claude/safer-dependencies-audit-YYYY-MM.log（暦月ごとに1ファイル、YYYY-MMはUTCの年月）に単一のJSON行として記録されます。完全なパスはSAFE_DEP_AUDIT_LOG環境変数で上書きできます（設定時は日付サフィックスは追加されません）。ファイルはSAFE_DEP_LOG_MAX_BYTES（デフォルト10 MiB、0に設定すると無効化）を超えた場合にもサイズローテーションされます。SAFE_DEP_MODELを設定すると、各エントリのsource.modelに書き込まれるモデル値を上書きできます — モデルバージョン間のA/B比較に便利です。
5つのモードすべてが同じファイルに追記します。各エントリには、どのコンポーネントが書き込んだかを識別する**sourceブロック**（スキーマ2.2）が含まれます：
source.component | 書き込み元 | トリガー |
|---|---|---|
shim.posttooluse | shim.sh | マニフェストまたはロックファイルの書き込み（インターセプトモード、ポストインストールディスパッチ） |
shim.install_error | shim.sh | shimプリフライトインストール失敗 |
bash.pretooluse | pretooluse-bash.sh | Bashインストールコマンド（プリインストールモード） |
bash.posttooluse | posttooluse-bash.sh | ポストインストールBashフック自体（shimに到達する前にフェイルオープンした場合） |
agent.pretooluse | pretooluse-agent.sh | プリエージェントフェイルオープンイベント用に予約（フック自体は現在成功時にサイレント） |
agent.posttooluse | posttooluse-agent.sh | ポストエージェントフックのフェイルオープンイベント（例：shim欠落、python_missing） |
manual.skill | ノーマルモードで実行中のClaude | インラインで呼び出される手動監査 |
source.modelは、セッションでアクティブなClaude Codeモデル（例："claude-sonnet-4-6"）を記録します。スキーマ2.1以降に存在します。古いインストールによって書き込まれたエントリはこのフィールドを省略します。statsコマンドは、このフィールドが存在しない場合、"unknown"にグレースフルにフォールバックします。
jqでsource.componentによるフィルタリング：```bash
jq -r '.source.component' audit.log | sort | uniq -c | sort -rn
jq -c 'select(.source.component == "bash.pretooluse")' audit.log
jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log
解析ログを手動で行う代わりに、より簡単な分析のためにClaudeに使用統計を依頼してください。```
"Show safer-dependencies stats for the last month"
これは、これらの監査ログから抽出されたアクティビティ、セキュリティへの影響、およびパフォーマンス指標の人間が読める要約を提供します。
エントリの形状（スキーマ2.2）。 3つの異なる形状が同じ ts / schema / source ヘッダーを共有します：
| 形状 | 書き込まれるタイミング | 識別フィールド |
|---|---|---|
| 監査エントリ | マニフェスト / ロックファイル / bashインストール監査 | file、ecosystem、checked、findings、abandoned、stale、typosquat、unknown、signatures、notes、clean |
| インストールエラーエントリ | Shim事前チェックのインストールエラー（コンポーネント shim.install_error） | install_error、shim_dir、scripts_dir |
| フェイルオープンエントリ | helper_missing / shim_missing / python_missing が原因で、フックのエントリポイントが早期終了する場合。source.mode は "fail_open" | fail_open: { reason, detail? } |
監査エントリ：インターセプトモードは完全なパイプライン（来歴、バージョン経過期間、OSV、abandoned/stale、typosquat、署名）を実行するため、すべての配列が入力されます。プリインストールモードは現在OSVのみを実行するため、abandoned / stale / typosquat / signatures は常に空です。ポストインストールディスパッチ（ロックファイル監査）は shim.posttooluse の下に書き込み、findings にはロックファイル監査ツールからの WARNING: 文字列が入力されます。notes 配列には情報提供用の NOTE: シグナル（例：マニフェストがピン留めされていないためスキップ）が格納されます。
スキーマ2.2では、ロックファイル監査エントリに4つのフィールドが追加的に（加算的に）追加されました：lockfile、manifest_ref、relation_summary（フラグが立てられた各パッケージの、対応するマニフェストに対する直接/推移的/不明の分類）、および有効な transitive 層を記録する policy ブロックです。この変更は後方互換性があります：2.1エントリのリーダーは新しいフィールドを許容し、source.model フィールドは2.1以降も引き続き存在します。```json
{
"ts": "2026-04-19T12:34:56Z",
"schema": "2.2",
"source": {
"component": "shim.posttooluse",
"script": "shim.sh",
"hook": "PostToolUse:Write",
"tool": "Write",
"mode": "intercept",
"model": "claude-sonnet-4-6"
},
"file": "/path/to/project/package.json",
"ecosystem": "npm",
"checked": ["[email protected]", "[email protected]"],
"findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"],
"abandoned": [],
"stale": [],
"typosquat": [],
"unknown": [],
"signatures": [],
"notes": [],
"clean": ["[email protected]"]
}
Pre-Install モードの例（Bash フック、脆弱なピンが拒否された場合）：```json
{
"ts": "2026-04-23T06:56:21Z",
"schema": "2.2",
"source": {
"component": "bash.pretooluse",
"script": "pretooluse-bash.sh",
"hook": "PreToolUse:Bash",
"tool": "Bash",
"mode": "intercept",
"model": "claude-sonnet-4-6"
},
"file": "bash:npm install [email protected] [email protected]",
"ecosystem": "npm",
"checked": ["[email protected]", "[email protected]"],
"findings": [
"BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
],
"abandoned": [],
"stale": [],
"typosquat": [],
"unknown": [],
"signatures": [],
"notes": [],
"clean": ["[email protected]"]
}
フェイルオープンモードの例（隣接するシムがない状態で呼び出されるインストール後Bashフック — インストールが壊れている場合）：```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }
A fail-open entry says: "this hook fired but exited early without auditing because something prerequisite was missing." Use the jq filter above (`select(.source.mode == "fail_open")`) to surface every silent loss-of-protection event in your log.
When the shim runs in dry-run mode (`SAFE_DEP_DRY_RUN=1`), entries also include `"mode": "dry_run"` so post-hoc analysis can filter audit-only invocations.
## Requirements
- Python 3.9+ (the hooks probe for this and fail-open on older interpreters)
- `curl` (for registry API calls and OSV vulnerability checks)
- Ecosystem tools (optional, skill falls back to OSV API if missing):
- `npm` for npm packages
- `pip-audit` for Python packages
- `bundle` for Ruby packages
- `dependency-check` for Java packages
## FAQ
Design-decision rationale (why `PostToolUse` instead of `PreToolUse`, why signatures aren't verified, why scripts and shim are duplicated, skill-loading gotchas, etc.) is documented in [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/main/FAQ.md).