PackageInferno

PackageInferno Logo

驚くほどシンプルなDockerファーストのnpmサプライチェーンスキャナー。1つのcomposeファイルで以下が実行されます:

Enumerator → パッケージのキューを構築
Fetcher → tarballをダウンロード(オプションでS3へアップロード)
Analyzer → 静的解析 + オプションのYARA
Postgres → 検出結果を保存するローカルDB
Streamlit Dashboard → http://localhost:8501 で検出結果を可視化

これはコンテナ専用エディションです。このプロジェクトはEC2、SQS、RDSを使用してスケールするように構築できます。ツールセットにはそのための設定のほとんどが含まれています。

得られるもの

Docker内でのエンドツーエンドパイプライン(Docker以外のホストインストールは不要)
scan.yml による設定可能なルール(許可リスト、しきい値、YARA)
ローカルPostgresスキーマ + スキャン履歴(scan_runs)がすぐに使える
tarballと検出結果のオプションのS3アップロード(認証情報は ~/.aws を使用)
Streamlitダッシュボード: 検索、ドリルダウン、分析

docker-compose.yml – サービス: db、enumerator、fetcher、analyzer、dashboard、init-db
enumerator/ – NDJSONキューを構築するNodeワーカー
fetcher/ – tarballをダウンロードするNodeワーカー(有効な場合はS3へアップロード)
analyzer/ – Python静的アナライザー(オプションのインラインYARA付き)
dashboard/ – Streamlitアプリ(ポート8501)
infra/migrations.sql – コアDBスキーマ(packages、versions、findings、scores、indexes)
infra/20251106_scan_runs.sql – スキャン履歴テーブル
scan.yml – 解析設定(rules、scoring、allowlists、YARA)
scripts/run_pipeline.sh – enumerate → fetch → analyze を実行
scripts/init_db.sh – DBスキーマを初期化
scripts/test_setup.sh – セットアップの自動検証
SCANNING_GUIDE.md – 詳細なスキャン戦略と例

クイックスタート(ローカル)

前提条件: Compose v2 を備えた Docker Desktop(またはエンジン)。

ワンラインインストール

curl -fsSL https://raw.githubusercontent.com/MHaggis/Package-Inferno/main/install.sh | bash

リポジトリを ~/package-inferno にクローンし、開始するための手順を表示します。

オプションA: ビルド済みイメージを使用(最速)

GitHub Container Registryからビルド済みコンテナをプルして実行します:

# Clone the repo (for config files and scripts)
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# Run with pre-built images
docker compose -f docker-compose.ghcr.yml up -d db
./scripts/init_db.sh
SEEDS="lodash,express" docker compose -f docker-compose.ghcr.yml run --rm enumerator
docker compose -f docker-compose.ghcr.yml run --rm fetcher
docker compose -f docker-compose.ghcr.yml run --rm analyzer

利用可能なイメージ:

ghcr.io/mhaggis/package-inferno/enumerator:main
ghcr.io/mhaggis/package-inferno/fetcher:main
ghcr.io/mhaggis/package-inferno/analyzer:main

オプションB: ソースからビルド

セットアップの自動検証

インストールを検証するためにテストスクリプトを実行します:

./scripts/test_setup.sh

これにより:

✓ Docker と Docker Compose をチェック
✓ データベースを起動して初期化
✓ テストスキャンを実行(2パッケージ)
✓ 検出結果が正しく保存されていることを確認

手動セットアップ

Postgresを起動し、スキーマを初期化:

docker compose up -d db
./scripts/init_db.sh

パイプラインを実行:

./scripts/run_pipeline.sh

ダッシュボードを起動:

docker compose up -d dashboard
# open http://localhost:8501

DBが有効な場合、検出結果は ./out/findings/*.findings.json と findings テーブルに保存されます。

スキャンモード

PackageInfernoは、目的に応じて複数のスキャン戦略をサポートしています:

モード	ユースケース	速度	カバレッジ	コマンド
特定シード	既知パッケージのテスト/調査	最速	対象を絞る	`SEEDS="pkg1,pkg2"`
小規模バッチ	セットアップの検証、サンプルスキャン	高速	10〜100パッケージ	`MAX_CHUNKS=2 CHUNK_LIMIT=10`
全レジストリ	包括的なサプライチェーン監査	数時間〜数日	200万+パッケージ	`MAX_CHUNKS=0 CHUNK_LIMIT=100`
変更フィード	新規リリースの監視(自動的に含まれる)	リアルタイム	最近の更新	組み込み

1. 特定パッケージのスキャン(テスト推奨)

解析したい特定パッケージを対象にします:

# Single command with seeds
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# Or from a file
echo -e "react\nvue\nangular" > packages.txt
export SEEDS_FILE=packages.txt
./scripts/run_pipeline.sh

最初にテストした方法: クイック検証には SEEDS="is-odd,is-even" を使用しました。

2. npmレジストリからのスキャン(_all_docs)

npmレジストリからページング処理でパッケージをスキャンします:

# Clean previous runs
rm -rf downloads/* out/*

# Scan 2 pages of 10 packages each (20 packages)
export MAX_CHUNKS=2        # Number of pages
export CHUNK_LIMIT=10      # Packages per page
unset SEEDS                # Important: disable seeds mode

# Run individual steps for better visibility
docker compose run --rm enumerator  # Discovers and queues
docker compose run --rm fetcher     # Downloads tarballs
docker compose run --rm analyzer    # Scans for threats

出力例:

config: chunkLimit=10, maxChunks=2
checking recent changes feed...
changes feed: enqueued 2 new versions
enumerating via _all_docs (fresh scan)
page 1/2 count: 10
page 2/2 count: 10
done, enqueued 22 (22 new versions)

3. 継続的監視(無制限スキャン)

npmレジストリ全体をスキャンします:

export MAX_CHUNKS=0        # 0 = unbounded
export CHUNK_LIMIT=100     # Larger batches for efficiency
./scripts/run_pipeline.sh

警告: これは数時間から数日間実行され、数十万のパッケージをスキャンします。ディスク容量とデータベースサイズを監視してください。

4. 中断されたスキャンの再開

Enumerator はカーソル位置を ./out/enumerator_state.json に保存します:

{
  "last_seq": "0",
  "last_startkey": "package-name",
  "last_run": "2025-11-23T19:24:49.123Z",
  "last_processed": 22,
  "last_new": 22
}

パイプラインを再実行するだけで、最後のカーソルから再開されます:

./scripts/run_pipeline.sh  # Automatically resumes

新しいスキャンを強制するには:

rm -f out/enumerator_state.json
./scripts/run_pipeline.sh

スキャン結果の例

22パッケージの2ページスキャンで、PackageInfernoが検出したものは次のとおりです:

-- Top suspicious packages by score
SELECT p.name, s.score, s.label, COUNT(f.id) as findings 
FROM packages p 
JOIN versions v ON p.id = v.package_id 
JOIN scores s ON v.id = s.version_id 
LEFT JOIN findings f ON v.id = f.version_id 
GROUP BY p.name, s.score, s.label 
ORDER BY s.score DESC;

-- Results:
   name                | score | label      | findings
-----------------------+-------+------------+----------
 rendition             | 606   | malicious  | 153
 vs-deploy             | 454   | malicious  | 119
 --123hoodmane-pyodide | 213   | malicious  | 46

rendition がこれほど疑わしい理由:

57 × url_outside_allowlist - 許可リスト外のドメイン
46 × suspicious_pattern - シェル/evalパターン
12 × advanced_obfuscation - 16進エンコード、XOR、文字列配列
6 × big_base64_blob - 大きなエンコードペイロード
18 × url_in_code - 埋め込みURL

スコアリングシステム(scan.yml で設定)はこれらの検出結果を集計して、リスクスコアとラベル(clean、suspicious、または malicious)を生成します。

結果の確認

ダッシュボード経由(推奨)

docker compose up -d dashboard 実行後、 http://localhost:8501 を開きます

機能:

📊 概要タブ: サマリー統計、スコア分布チャート
🔍 検索タブ: パッケージ名で検索、リスクラベルでフィルタ
⚠️ 高リスクタブ: ドリルダウン可能な上位の悪意のあるパッケージ
🎯 C2分析: 既知の外部送信(exfiltration)エンドポイントを持つパッケージ
📈 分析タブ: トレンド、一般的なルール、時間的分析

データベースクエリ経由

カスタム分析のための直接SQLアクセス:

# Connect to database
docker exec -it pi-postgres psql -U piuser -d packageinferno

便利なクエリ:

-- Packages with credential theft attempts
SELECT DISTINCT p.name, v.version, s.score
FROM packages p
JOIN versions v ON p.id = v.package_id
JOIN findings f ON v.id = f.version_id
JOIN scores s ON v.id = s.version_id
WHERE f.rule = 'env_snoop'
ORDER BY s.score DESC;

-- All C2/webhook destinations found
SELECT p.name, f.details->>'endpoints' as c2_endpoints
FROM packages p
JOIN versions v ON p.id = v.package_id
JOIN findings f ON v.id = f.version_id
WHERE f.rule = 'c2_webhook';

-- Typosquatting attempts
SELECT 
  p.name,
  f.details->>'target_package' as impersonating,
  f.details->>'similarity' as similarity_pct,
  f.details->>'typosquat_type' as attack_type
FROM packages p
JOIN versions v ON p.id = v.package_id
JOIN findings f ON v.id = f.version_id
WHERE f.rule = 'typosquat_detected'
ORDER BY (f.details->>'similarity')::float DESC;

-- Packages with native binaries
SELECT p.name, f.details->>'path' as binary_path
FROM packages p
JOIN versions v ON p.id = v.package_id
JOIN findings f ON v.id = f.version_id
WHERE f.rule = 'native_binary_present';

JSONファイル経由

検出結果は ./out/findings/ 配下に構造化JSONとしても保存されます:

# View findings for a specific package
cat out/findings/[email protected] | jq .

# Count findings by severity
jq -r '.findings[].severity' out/findings/*.findings.json | sort | uniq -c

Package-Inferno

人気