alexh-scrt/contagious-scan
GitHub: alexh-scrt/contagious-scan
针对 DPRK「Contagious Interview」供应链攻击的专项安全扫描 CLI 工具，用于检测 npm/Python 包中 BeaverTail 和 InvisibleFerret 等已知恶意模式。
Stars: 0 | Forks: 0
# contagious_scan
[](https://www.python.org/downloads/)
[](LICENSE)
## 它的功能
`contagious_scan` 是一个安全 CLI 工具，用于检测 *Contagious Interview* 攻击活动的指标——这是一次由 DPRK 策划的供应链攻击，通过带有木马的 npm 包和 Python 库瞄准软件开发人员。它会扫描包清单、安装后脚本、CI/CD 配置和源文件，以查找已知的恶意模式，包括 **BeaverTail** 信息窃取器 payload 和 **InvisibleFerret** 后门 stager。您可以将其作为一次性审计在任何本地或远程 Git 仓库上运行，或者将其接入 pre-push 钩子，以便在受损代码到达远程仓库之前将其阻止。
## 快速开始
```
# 安装
pip install contagious_scan
# 扫描当前仓库
contagious-scan scan .
# 扫描远程仓库
contagious-scan scan https://github.com/org/suspicious-repo --remote
# 安装为 Git pre-push hook (在发现 Critical 结果时阻止推送)
contagious-scan install-hook .
```
就是这样。任何严重或高危险级别的发现都会打印到终端，并且命令会以非零代码退出——使其开箱即用，完美适配 CI 环境。
## 功能特性
- **RAT payload 检测** — 针对 BeaverTail JS 加载器和 InvisibleFerret Python stager 的正则表达式和基于哈希的签名，以及跨 JS、Python 和 shell 文件被混淆的 base64/hex `eval`/`exec` 链。
- **包清单审计** — 标记 `package.json`、`setup.py`、`setup.cfg` 和 `pyproject.toml` 中恶意的 `postinstall`、`prepare` 和 `preinstall` 生命周期钩子。
- **感知 Git 的扫描** — 在钩子模式下仅检查暂存的文件，在审计模式下检查整个工作树，或按需克隆远程 URL。
- **Pre-push 钩子安装** — 当检测到严重级别的发现时，一条命令即可阻止推送，并为自动化流水线提供 `--ci-override` 标志。
- **结构化报告** — 丰富且带有颜色的终端表格、机器可读的 JSON 以及纯文本输出，包含危险级别（`critical` / `high` / `medium` / `info`）、文件位置、匹配模式的描述和修复指南。
## 使用示例
### 审计本地仓库
```
# 默认 Rich 终端输出
contagious-scan scan /path/to/repo
# 输出为 JSON (适用于管道传输至其他工具)
contagious-scan scan /path/to/repo --format json
# 仅显示 High 和 Critical 结果
contagious-scan scan /path/to/repo --min-severity high
```
### 审计远程仓库
```
contagious-scan scan https://github.com/org/repo --remote
```
### 仅扫描暂存文件（手动模拟钩子）
```
contagious-scan scan . --staged-only
```
### 安装 pre-push 钩子
```
# 标准安装 — 在发现 Critical 结果时阻止推送
contagious-scan install-hook /path/to/repo
# CI 友好：运行 Hook 但从不阻止推送
contagious-scan install-hook . --ci-override
# 检查 Hook 是否已安装
contagious-scan install-hook . --status
# 移除 Hook
contagious-scan install-hook . --uninstall
```
### 重新渲染已保存的 JSON 报告
```
# 将结果保存到磁盘
contagious-scan scan . --format json > findings.json
# 稍后重新渲染为 Rich 表格
contagious-scan report findings.json --format rich
```
### 终端输出示例
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Severity ┃ Description ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ packages/utils/package.json │ CRITICAL │ Malicious postinstall lifecycle hook │
│ src/loader.js │ HIGH │ BeaverTail base64 eval chain │
│ scripts/setup.py │ HIGH │ InvisibleFerret stager pattern │
│ .github/workflows/ci.yml │ MEDIUM │ Suspicious outbound curl in CI step │
└─────────────────────────────────┴───────────┴─────────────────────────────────────┘
4 findings (1 critical, 2 high, 1 medium)
```
### 退出代码
| 代码 | 含义 |
|------|---------|
| `0` | 没有达到或超过最低危险级别的发现 |
| `1` | 检测到一个或多个发现 |
| `2` | 扫描错误（路径无效、git 错误等） |
## 项目结构
```
contagious_scan/
├── __init__.py # Package init — version and top-level API
├── cli.py # Click CLI entry point (scan, install-hook, report)
├── scanner.py # Scan pipeline orchestration and file discovery
├── detectors.py # Detector functions: RAT patterns, loaders, hooks, CIDDs
├── signatures.py # Static IOC database: regexes, hashes, package names
├── git_utils.py # Staged file enumeration, repo walk, remote cloning
├── reporter.py # Rich/JSON/plain output rendering and exit codes
└── hook_installer.py # Git pre-push hook writer and manager
tests/
├── fixtures/
│ ├── malicious_package.json # npm package.json with injected postinstall payload
│ └── malicious_setup.py # setup.py with obfuscated InvisibleFerret loader
├── test_detectors.py # Unit tests for each detector function
├── test_scanner.py # Integration tests against temporary git repo fixtures
├── test_reporter.py # Reporter formatting and exit code tests
├── test_cli.py # CLI command and flag tests
├── test_git_utils.py # Git utility function tests
├── test_hook_installer.py
├── test_signatures.py
└── test_init.py
pyproject.toml
README.md
```
## 配置
`contagious-scan scan` 接受以下选项：
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--format` | `rich` | 输出格式：`rich`、`json` 或 `plain` |
| `--min-severity` | `info` | 报告的最低危险级别：`info`、`medium`、`high`、`critical` |
| `--staged-only` | `false` | 仅扫描 Git 暂存文件（钩子模式） |
| `--remote` | `false` | 将目标视为远程 URL 并在扫描前进行克隆 |
| `--output` | stdout | 将输出写入文件路径，而不是 stdout |
`contagious-scan install-hook` 接受：
| 标志 | 描述 |
|------|-------------|
| `--ci-override` | 以非阻塞模式为 CI 环境安装钩子 |
| `--uninstall` | 移除现有的钩子安装 |
| `--status` | 打印当前是否已安装钩子 |
## 运行测试
```
pip install -e ".[dev]"
pytest tests/
```
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
*由 [Jitter](https://github.com/jitter-ai) 构建 - 一个每天交付代码的 AI 智能体。*
标签：BeaverTail, CI/CD安全, Contagious Interview, DNS 反向解析, DPRK攻击检测, Git钩子, InvisibleFerret, Llama, LNA, npm, pip, Python, RAT检测, 威胁情报, 安全防御工具, 开发者工具, 无后门, 混淆代码检测, 渗透测试防御, 源码扫描, 网络安全, 网络安全研究, 逆向工具, 错误基检测, 隐私保护, 静态代码分析