detecting-malicious-npm-packages

悪意のある npm パッケージの検出

法的通知： パッケージの分析は、隔離された使い捨て環境で行ってください。悪意のあるパッケージの中には、インストール時（npm install はライフサイクルスクリプトを自動実行します）やインポート時に実行されるものがあります。認証情報、SSH キー、クラウドトークン、本番環境へのネットワークアクセスがあるワークステーションで、不審なパッケージを分析しないでください。このスキルは、防御的な分析と許可を得たインシデント対応のみを目的としています。

概要

npm レジストリは世界最大のソフトウェアパッケージエコシステムであり、サプライチェーン攻撃者に最も狙われています。悪意のあるパッケージは、タイポスクワッティング（expresss、crossenv）、依存関係の混同、アカウントやメンテナーの乗っ取り（2025 年の Shai-Hulud ワームと event-stream の侵害が代表的な例です）、starjacking を通じて被害者に届きます。npm に特有の危険は、アプリケーションコードが実行される前に、npm install が開発者の完全な権限で preinstall、install、postinstall のライフサイクルスクリプトを自動実行することです。そのため、パッケージをインストールするだけで侵害される可能性があります。npm パッケージのおよそ 2% がインストールスクリプトを使用しており、これらは一般的であると同時に、マルウェアの強力な配布手段にもなっています。

典型的な悪意ある動作には、環境変数、~/.npmrc トークン、SSH キー、クラウド認証情報を攻撃者が管理する URL に流出させること、リバースシェルを開くこと、クリプトマイナーを仕込むこと、process.env を読み取って送信すること、base64 や eval でペイロードを難読化すること、メンテナーの npm トークンを盗んで、そのメンテナーが所有する他のパッケージにトロイの木馬化したバージョンを再公開し、自ら拡散すること（ワーム化）などがあります。

このスキルでは、GuardDog（Semgrep とメタデータルールを基盤とする、Datadog のオープンソースヒューリスティックスキャナー）を中心とした、再現可能なトリアージワークフローを提供します。これを手動での tarball の検査、ロックファイルと既知の悪意あるバージョンリストとの照合、ネットワークとファイルシステムを監視した動的実行で補完します。目的は、特定のパッケージやプロジェクトの依存関係ツリーに悪意のあるコードが含まれているかどうかを、迅速かつ安全に判断することです。

使用する場面

• 特定の npm パッケージを依存関係に追加する前にトリアージする場合。
• コードレビューやサードパーティライブラリの導入時に、package.json／package-lock.json 全体を審査する場合。
• サプライチェーンに関する勧告（ワームキャンペーンなど）への対応として、ロックファイルに既知の悪意あるバージョンが含まれているか確認する必要がある場合。
• トロイの木馬化されたパッケージをインストールした疑いがあるエンドポイントや CI ランナーを調査する場合。
• 悪意のある兆候を示すパッケージをブロックする、CI/CD のインストール前ゲートを構築する場合。

前提条件

• 本番環境の認証情報がない隔離された VM または使い捨てコンテナー。スナップショット／ロールバック機能が必要です。
• GuardDog：

  pip install guarddog
  # or run via Docker without local install:
  docker pull ghcr.io/datadog/guarddog
  alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
  

• Node.js と npm（分析用にダウンロードする際は --ignore-scripts を使用してください）。
• jq、tar。既知の脆弱性や悪意あるパッケージとの照合には、必要に応じて OSV-Scanner も使用します。

  go install github.com/google/osv-scanner/cmd/osv-scanner@v1
  

• 動的分析を行う場合：送信トラフィックのログを取得できるサンドボックス（tcpdump、DNS シンク、ネットワーク名前空間など）。

目標

• npm パッケージ（または依存関係ツリー全体）を実行せずに静的スキャンし、悪意のある挙動を示すヒューリスティックを検出する。
• インストールスクリプトの悪用、環境変数や認証情報の流出、難読化、目立たないプロセス実行を特定する。
• ロックファイルで固定されたバージョンを、既知の悪意あるバージョンリストや OSV と照合する。
• 不審なパッケージを安全に実行し、ネットワークやファイルシステムの挙動を観察する。
• ブロックや脅威インテリジェンスに活用するため、侵害の痕跡（URL、IP、ハッシュ）を抽出する。
• 根拠を添えて、妥当性を説明できる判定（無害／不審／悪意あり）を提示する。

MITRE ATT&CK マッピング

テクニック ID	テクニック名	関連性
T1195.002	サプライチェーンの侵害：ソフトウェアサプライチェーンの侵害	中核的なテクニックです。レジストリを通じてトロイの木馬化された npm パッケージが配布されます。
T1059.007	コマンドおよびスクリプトインタープリター：JavaScript	悪意のあるインストールスクリプト／モジュールコードによって、攻撃者の JavaScript が実行されます。
T1552.001	安全でない認証情報：ファイル内の認証情報	パッケージは ~/.npmrc、.env、SSH キー、クラウド認証情報ファイルを窃取します。
T1041	C2 チャネル経由の情報流出	盗み出したシークレットが攻撃者の HTTP(S) エンドポイントに送信されます。
T1027	難読化されたファイルまたは情報	base64／eval／hex による難読化で、レビュー時にペイロードが見つかりにくくなります。

ワークフロー

1. パッケージを実行せずにダウンロードする

取得中に何も実行されないよう、スクリプトを無効にして tarball を取得します。

mkdir triage && cd triage
# Resolve the tarball URL and download it (no install, no scripts)
npm pack [email protected]            # produces express-4.18.2.tgz
# or for an arbitrary version:
npm view [email protected] dist.tarball
curl -sL "$(npm view [email protected] dist.tarball)" -o some-pkg.tgz
tar -xzf some-pkg.tgz              # extracts into ./package

2. GuardDog で単一のパッケージをスキャンする

GuardDog はメタデータとソースコードのヒューリスティックを適用し、一致したルールを出力します。

# Scan the latest published version from the registry
guarddog npm scan express

# Scan a specific version
guarddog npm scan some-pkg --version 1.2.3

# Scan the local tarball / extracted directory you downloaded above
guarddog npm scan ./some-pkg.tgz
guarddog npm scan ./package/

3. 依存関係ツリー全体を検証する

verify はマニフェストで宣言されたすべての依存関係をスキャンします。コードレビューに最適です。

guarddog npm verify /path/to/repo/package.json

4. シグナルの強いヒューリスティックに絞り込む

マルウェアの兆候として特に有力な npm ルールに絞り込み、トリアージ時のノイズを減らします。

guarddog npm scan some-pkg \
  --rules npm-install-script \
  --rules npm-serialize-environment \
  --rules npm-exec-base64 \
  --rules npm-silent-process-execution \
  --rules npm-obfuscation \
  --rules shady-links \
  --rules typosquatting

5. パイプライン向けに機械可読形式で出力する

ツールには JSON、GitHub コードスキャンには SARIF を使用します。

guarddog npm scan some-pkg --output-format=json   > guarddog.json
guarddog npm verify package.json --output-format=sarif > guarddog.sarif

6. ライフサイクルスクリプトとソースコードを手動で確認する

まずライフサイクルスクリプトを読みます。難読化や外部向け URL は危険な兆候です。

# Show all lifecycle hooks
jq '.scripts' package/package.json

# Hunt for exfiltration / execution primitives in the source
grep -rEn "child_process|exec\(|spawn|eval\(|Buffer\.from\(.*base64|process\.env|https?://" package/ \
  --include='*.js' --include='*.ts' | head -50

7. ロックファイルを既知の悪意あるバージョンと照合する

キャンペーン発生中は、固定されたバージョンをアドバイザリの悪意あるバージョン一覧と照合し、OSV も実行します。

# Extract resolved name@version pairs from a v3 lockfile
jq -r '.packages | to_entries[] | select(.key|startswith("node_modules/")) | "\(.key|ltrimstr("node_modules/"))@\(.value.version)"' package-lock.json

# OSV-Scanner flags known-vulnerable AND known-malicious (MAL-) advisories
osv-scanner --lockfile=package-lock.json

8. 監視下で安全に実行して挙動を確認する（静的解析で判断できない場合のみ）

使い捨てのネットワーク監視付きサンドボックス内でインストールを実行します。

# In a throwaway container / VM with egress capture running (tcpdump -w capture.pcap):
npm install ./some-pkg.tgz            # scripts WILL run — sandbox only
# Baseline-diff the filesystem afterwards for writes outside node_modules,
# and inspect capture.pcap for unexpected DNS / HTTP beacons.

9. IOC を抽出して運用に活用する

ブロックやインテリジェンス共有に向けて、URL、IP、ハッシュを抽出します。

grep -rhoE "https?://[a-zA-Z0-9./?=_%:-]+" package/ | sort -u > urls.txt
sha256sum some-pkg.tgz package/*.js > hashes.txt

10. 同梱のトリアージヘルパーを実行する

agent.py は GuardDog、ライフサイクルスクリプトの検査、IOC の抽出をまとめて実行し、1 つのレポートに出力します。

python scripts/agent.py --package some-pkg --version 1.2.3 --output verdict.json
# or against a local tarball:
python scripts/agent.py --tarball ./some-pkg.tgz --output verdict.json

ツールとリソース

ツール	用途	ソース
GuardDog	npm／PyPI／Go 向けのヒューリスティックベースのマルウェアスキャナー	https://github.com/DataDog/guarddog
OSV-Scanner	既知の脆弱なパッケージおよび既知の悪意あるパッケージ（MAL-）のアドバイザリ照合	https://github.com/google/osv-scanner
OSV malicious DB	オープンソースの悪意あるパッケージに関するアドバイザリ	https://github.com/ossf/malicious-packages
npm ライフサイクルのドキュメント	preinstall/install/postinstall の動作	https://docs.npmjs.com/cli/v10/using-npm/scripts
Datadog Security Labs	npm キャンペーンの分析記事とルール	https://securitylabs.datadoghq.com/
Semgrep	GuardDog がソースコードのヒューリスティックに使用するルールエンジン	https://semgrep.dev/

検証基準

• 隔離された環境でスクリプトを無効にしてパッケージを取得した。
• 対象バージョンに対して GuardDog の scan を実行し、結果を記録した。
• 該当する場合、依存関係ツリー全体に対して GuardDog の verify を実行した。
• ライフサイクルスクリプト（preinstall／install／postinstall）を読み、評価した。
• ロックファイルのバージョンを OSV／既知の悪意あるバージョン一覧と照合した。
• 静的解析で判断できなかった場合、サンドボックスで動的解析を実施した。
• IOC（URL、IP、ハッシュ）を抽出して記録した。
• 根拠を添えて判定（無害／疑わしい／悪意あり）を文書化した。
• 悪意のある検出結果をレジストリに報告し、脅威インテリジェンスとして共有した。