Heisenberg Dependency Health Checkは、プルリクエストで導入された新規または変更された依存関係のみを検査するGitHub Actionです。ロックファイルやマニフェストの変更を解析し、deps.devやその他のヒューリスティクスから健全性とリスクのシグナルを収集して、詳細な依存関係ヘルスレポートをプルリクエスト上に直接投稿します。疑わしい、低品質、または異常に新しいパッケージを、メインブランチに到達する前に強調表示します。
概要
現代のサプライチェーン攻撃は、日常的な開発ワークフローを通じて悪意のある、または信頼度の低い依存関係を導入することにますます依存しています。従来のスキャナーは定期的に実行され、既知の脆弱性に焦点を当てることが多いため、初期のリスク兆候を見逃します。Heisenbergは異なるアプローチを取ります。プルリクエストに直接フックし、追加または更新されたパッケージを検出して、それらを個別にレビューします。マージ時に実行されることで、意思決定が行われるまさにそのタイミングで、レビュー担当者に実用的なリスクシグナルを提供します。
このツールはエコシステム非依存で、Python、JavaScript、Goの依存関係形式をサポートします。異常な公開タイミング、メンテナンス上の危険信号、人気度の問題、疑わしいスクリプト、その他サプライチェーン侵害に関連するパターンを検出できます。設定次第では、リスクしきい値を超えるプルリクエストにラベルを付けたり、ブロックしたりすることも可能です。
機能
- 差分ベースのスキャン: 依存関係グラフ全体を再スキャンするのではなく、新規または変更された依存関係のみを評価します。
- マルチエコシステム対応:
poetry.lock、requirements.txt、uv.lock、package-lock.json、yarn.lock、go.modに対応します。 - リスクおよび健全性シグナル: アドバイザリ、メンテナンス指標、人気度データ、依存先（dependents）、そして拙速または疑わしいリリースを示唆し得る「驚くほど最近の公開」を取得します。
- npmスクリプトチェック: 攻撃者が頻繁に悪用するpost-installスクリプトの挙動を強調表示します。
- プルリクエストレポート: パッケージのインテリジェンス情報源へのリンク付きで、構造化された依存関係ヘルスコメントを投稿します。
- ポリシー制御: リスクの高いパッケージが導入された場合に、セキュリティレビューのラベルを追加したり、ジョブを失敗させたりできます。
インストール
以下のワークフローはHeisenbergのドキュメントから直接引用したもので、リポジトリ内の.github/workflows/に配置してください。標準的な依存関係ファイルを監視し、それらのいずれかが変更されるたびにアクションを実行します。
name: Heisenberg Health Check
on:
pull_request:
paths:
- "**/poetry.lock"
- "**/uv.lock"
- "**/package-lock.json"
- "**/yarn.lock"
- "**/requirements.txt"
- "**/go.mod"
permissions:
contents: read
pull-requests: write
issues: write
jobs:
deps-health:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Detect changed manifest
id: detect
run: |
git fetch origin ${{ github.base_ref }} --depth=1
LOCK_PATH=$(git diff --name-only origin/${{ github.base_ref }} | \
grep -E 'poetry.lock$|uv.lock$|package-lock.json$|yarn.lock$|requirements.txt$|go.mod$' | head -n1 || true)
echo "lock_path=$LOCK_PATH" >> $GITHUB_OUTPUT
- name: Heisenberg Dependency Health Check
uses: AppOmni-Labs/heisenberg-ssc-gha@v1
with:
package_file: ${{ steps.detect.outputs.lock_path }}使い方
ワークフローが有効になると、処理は自動で行われます:
- プルリクエストが依存関係マニフェストを変更します。
- ワークフローが変更を検出し、該当ファイルをHeisenbergに渡します。
- Heisenbergは追加または変更されたパッケージのみを評価します。
- ヘルスレポートがプルリクエストへのコメントとして表示されます。
- 任意: リスクの高い変更はラベル付けをトリガーしたり、ジョブを失敗させてマージをブロックしたりできます。
Clawsのような追加のGitHub Action強化ツールを使用しているチームは、HeisenbergをワークフローLintと組み合わせることで、自動化の悪用と侵害された依存関係の両方に起因するリスクを低減できます。
攻撃シナリオ
目的: 現実的な開発フローの中で、敵対的な依存関係の試みがどのように検出されるかを示します。
- Heisenbergワークフローを有効にしたデモリポジトリを用意します。
- 不審な活動、メンテナンス不良、またはごく最近の公開で知られる依存関係を追加または更新します。
- 通常の更新を行うかのようにプルリクエストを開きます。
- Heisenbergは変更された依存関係のみを評価し、関連する懸念点をすべて強調したヘルスレポートを投稿します。
- フラグが立ったシグナルを、サプライチェーンリスクの証拠および自動ガードレールが重要である理由として、関係者に示します。
この敵対的モデリングは、Weaponizing Dependabotのような自動化悪用に関するDarknetの解説を用いた社内レビューとも相性が良く、適切な制御がない場合に自動化ツールがどのように悪用され得るかをチームが理解する助けになります。
レッドチームにおける関連性
Heisenbergは防御側のために作られていますが、レッドチームは次の用途に利用できます:
- 対象環境における、弱い／未精査の依存関係更新プラクティスを特定する。
- 依存関係の注入やタイポスクワッティングに依存する現実的な侵害経路をモデル化する。
- 組織がHeisenbergまたは同様の制御を導入していれば、リスクがどれほど迅速に検知されるかを示す。
また、サプライチェーン偵察ツールやGitHubワークフロー分析手法とも自然に組み合わせられます。たとえば、Velesのようなシークレット露出検出ツールはキー検出に優れ、GitPhishのようなOAuth悪用研究は、CI/CDエコシステム内のより広範なリスクを浮き彫りにします。
検知と緩和
- 依存関係の変更をプルリクエストに限定し、Heisenbergが完全に可視化できるようにします。
- レポートを集約し、セキュリティチームがリポジトリ横断でパターンを把握できるようにします。
- GitHubワークフローを強化して回避経路を防ぎます。Clawsのようなツールは、安全なワークフロー運用の徹底に役立ちます。
- Dependabotの悪用やより広範なCI/CD悪用に関するDarknetの解説から得た教訓を用いて、依存関係自動化を脅威モデリングします。
- 検知ロジックの有効性を維持するため、意図的にリスクはあるが無害なパッケージを用いた定期的なカオステストを導入します。
比較
Heisenbergは、依存関係ツリー全体ではなく変更に焦点を当てることで、スケジュール実行型のコンポジションスキャナーとは異なります。開発者のワークフローを遅くすることなく、マージ時点のリアルタイムなインテリジェンスをチームに提供します。より広範なGitHubワークフロー強化ツールと比べると、パッケージレベルのサプライチェーンリスクに特化しており、完全なCI/CDセキュリティ態勢を構成する補完的要素となります。
結論
Heisenberg Dependency Health Checkは、コードレビュー中にリスクの高い依存関係を捕捉するための、高シグナルで摩擦の少ない制御を提供します。開発者が追加または更新しているパッケージに厳密に焦点を当てることで、ノイズでチームを圧倒することなくサプライチェーンリスクを可視化し続けます。オープンソースパッケージに大きく依存し、ビルドパイプラインに入り込む前にサプライチェーン侵害を防ぎたいあらゆるチームにとって、実用的なアップグレードです。
Heisenberg Dependency Health Checkの詳細確認またはダウンロードはこちら: https://github.com/AppOmni-Labs/heisenberg-ssc-gha
