detecting-malicious-npm-packages

检测恶意 npm 包

法律声明： 请在隔离的一次性环境中分析软件包。某些恶意软件包会在安装时执行（npm install 会自动运行生命周期脚本）或在导入时执行。切勿在存有凭据、SSH 密钥、云令牌或可访问生产网络的工作站上分析可疑软件包。本技能仅用于防御性分析和经过授权的应急响应。

概述

npm registry 是世界上最大的软件包生态系统，也是供应链攻击者针对最多的目标。恶意软件包通过错拼抢注（expresss、crossenv）、依赖混淆、账号/维护者接管（2025 年的 Shai-Hulud 蠕虫和 event-stream 被入侵事件就是典型例子）以及 starjacking 等方式触达受害者。npm 的决定性危险在于，npm install 会在调用任何应用代码之前，以开发者的完整权限自动运行 preinstall、install 和 postinstall 生命周期脚本——因此仅仅安装一个软件包就足以被入侵。大约 2% 的 npm 软件包使用安装脚本，这使它们既常见又成为强大的恶意软件投递载体。

典型的恶意行为包括：将环境变量、~/.npmrc 令牌、SSH 密钥和云凭据外传到攻击者控制的 URL；打开反向 shell；投放挖矿程序；读取并上传 process.env；使用 base64/eval 混淆载荷；以及通过窃取维护者的 npm 令牌并重新发布其拥有的其他软件包的特洛伊化版本进行自我传播（蠕虫化）。

本技能提供了一套可重复的分类处置工作流，核心是 GuardDog（Datadog 基于 Semgrep + 元数据规则构建的开源启发式扫描器），并辅以手动 tarball 检查、基于锁文件对照已知恶意版本列表的入侵检查，以及带网络和文件系统监控的动态引爆。目标是快速、安全地判定给定软件包或项目依赖树中是否包含恶意代码。

使用场景

• 在将某个特定 npm 软件包添加为依赖之前对其进行分类处置。
• 在代码审查或引入第三方库时，审查完整的 package.json / package-lock.json。
• 响应供应链公告（例如蠕虫活动），需要检查你的锁文件是否拉取了已知恶意版本。
• 调查疑似安装了特洛伊化软件包的终端或 CI runner。
• 在 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 sink 或网络命名空间）。

目标

• 在不执行的情况下，对 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 用于工具链，SARIF 用于 GitHub 代码扫描。

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 提取编排为一份报告。

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 恶意数据库	开源恶意包公告	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、哈希）。
• 记录有证据支撑的判定结论（良性 / 可疑 / 恶意）。
• 将恶意发现报告给注册表并作为威胁情报共享。