PackageInferno

极度简单、Docker优先的npm供应链扫描器。仅需一个Compose文件即可运行：

• Enumerator（枚举器）→ 构建包队列
• Fetcher（获取器）→ 下载tarball（可选上传至S3）
• Analyzer（分析器）→ 静态分析 + 可选YARA
• Postgres → 本地数据库存储发现结果
• Streamlit Dashboard（仪表板）→ 在 http://localhost:8501 可视化查看结果

这是纯容器版本。该项目可扩展至使用EC2、SQS和RDS。工具集中已为此做了大部分配置。

---

你将获得

• Docker中端到端流水线（宿主机只需安装Docker）
• 通过 scan.yml 可配置规则（白名单、阈值、YARA）
• 本地Postgres模式 + 扫描历史 (scan_runs) 即开即用
• 可选S3上传tarball和发现结果（通过 ~/.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 – 分析配置（规则、评分、白名单、YARA）
• scripts/run_pipeline.sh – 运行 enumerate → fetch → analyze
• scripts/init_db.sh – 引导DB模式
• scripts/test_setup.sh – 自动设置验证
• SCANNING_GUIDE.md – 详细扫描策略和示例

---

快速开始（本地）

前提条件：安装了Docker Desktop（或引擎）并支持Compose v2。

一键安装

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

此命令会将仓库克隆到 ~/package-inferno 并给出启动说明。

选项A：使用预构建镜像（最快）

从GitHub容器注册表拉取并运行预构建容器：

# 克隆仓库（获取配置文件和脚本）
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# 使用预构建镜像运行
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个包）
• ✓ 验证发现结果是否正确存储

手动设置

1. 启动Postgres并初始化模式：

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

2. 运行流水线：

./scripts/run_pipeline.sh

3. 启动仪表板：

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

发现结果保存在 ./out/findings/*.findings.json 中，启用DB时也会存储在 findings 表中。

---

扫描模式

PackageInferno支持多种扫描策略，适用于不同目标：

模式	用例	速度	覆盖范围	命令
特定种子	测试/调查已知包	最快	针对性	SEEDS="pkg1,pkg2"
小批量	验证设置、样本扫描	快	10-100个包	MAX_CHUNKS=2 CHUNK_LIMIT=10
全量注册表	全面供应链审计	数小时至数天	200万+包	MAX_CHUNKS=0 CHUNK_LIMIT=100
变更馈送	监控新版本（已自动包含）	实时	最近更新	内置

1. 扫描特定包（推荐用于测试）

定位你想要分析的具体包：

# 单条命令，使用种子
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# 或从文件读取
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注册表分页扫描包：

# 清理之前的运行结果
rm -rf downloads/* out/*

# 扫描2页，每页10个包（共20个包）
export MAX_CHUNKS=2        # 页面数
export CHUNK_LIMIT=10      # 每页包数
unset SEEDS                # 重要：禁用种子模式

# 为更好可视化而分别运行各步骤
docker compose run --rm enumerator  # 发现并排队
docker compose run --rm fetcher     # 下载tarball
docker compose run --rm analyzer    # 扫描威胁

示例输出：

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 = 无界
export CHUNK_LIMIT=100     # 更大的批次以提高效率
./scripts/run_pipeline.sh

警告： 这将运行数小时/数天，扫描数十万个包。请监控磁盘空间和数据库大小。

4. 恢复中断的扫描

枚举器将状态保存到 ./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  # 自动恢复

强制全新扫描：

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

示例扫描结果

来自22个包的2页扫描，以下是PackageInferno检测到的结果：

-- 按分数排序的高可疑包
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;

-- 结果：
   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 - Shell/eval模式
• 12 × advanced_obfuscation - 十六进制编码、XOR、字符串数组
• 6 × big_base64_blob - 大型编码负载
• 18 × url_in_code - 嵌入URL

评分系统（在 scan.yml 中配置）会聚合这些发现，产生风险分数和标签（clean、suspicious 或 malicious）。

---

探索结果

通过仪表板（推荐）

运行 docker compose up -d dashboard 后打开 http://localhost:8501

功能：

• 📊 概览标签页：汇总统计、分数分布图
• 🔍 搜索标签页：按名称查找包，按风险标签筛选
• ⚠️ 高风险标签页：前恶意包及其下钻详情
• 🎯 C2分析：含有已知外泄端点的包
• 📈 分析标签页：趋势、常见规则、时序分析

通过数据库查询

直接SQL访问，用于自定义分析：

# 连接到数据库
docker exec -it pi-postgres psql -U piuser -d packageinferno

有用查询：

-- 含有凭据窃取企图的包
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;

-- 发现的所有C2/Webhook目标
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';

-- 拼写错误攻击
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;

-- 包含原生二进制文件的包
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文件

发现结果也会以结构化JSON保存到 ./out/findings/：

# 查看特定包的发现结果
cat out/findings/[email protected] | jq .

# 按严重程度统计发现数
jq -r '.findings[].severity' out/findings/*.findings.json | sort | uniq -c

# 提取所有发现的C2 URL
jq -r '.findings[] | select(.rule=="c2_webhook") | .details.full_urls[]' out/findings/*.findings.json

---

可选：S3集成（tarball和发现结果）

如果你希望将制品放入S3：

• 创建桶（自行命名）：
  • package-inferno-tarballs（原始npm tarball）
  • package-inferno-findings（分析器输出）
• 确保你的 ~/.aws 包含有效凭据（基于配置文件或环境）。
• 在运行流水线之前导出环境变量：

export AWS_REGION=us-west-2
export S3_TARBALLS=package-inferno-tarballs
export S3_FINDINGS=package-inferno-findings
export AWS_PROFILE=default   # 可选；或依赖环境凭据

Compose将 ~/.aws 挂载到fetcher和analyzer中。如果 LOCAL_ONLY=false，fetcher会上传tarball到 S3_TARBALLS。如果设置了 S3_FINDINGS，analyzer会在本地写入后将发现JSON上传。

最小IAM策略示例（附加到你正在使用的用户/角色）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3Access",
      "Effect": "Allow",
      "Action": ["s3:PutObject","s3:GetObject","s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::package-inferno-tarballs",
        "arn:aws:s3:::package-inferno-tarballs/*",
        "arn:aws:s3:::package-inferno-findings",
        "arn:aws:s3:::package-inferno-findings/*"
      ]
    }
  ]
}

---