dhawaldesai/agentic-ioc-scanner
GitHub: dhawaldesai/agentic-ioc-scanner
一个专门用于检测AI编程工具入侵迹象的IOC扫描器。
Stars: 0 | Forks: 0
# agentic-ioc-scanner
一套用于检测 AI 编程助手（Claude Code、Gemini CLI、Cursor）及其拉入代码库的依赖项是否被入侵的检测工具包。包含十一项检查，涵盖钩子注入、RCE 配置、恶意依赖、git-hook 后门和 CI 工作流篡改。IOC 列表已外部化——添加新指标无需更改代码。
配套博客文章：[当工具反击时](https://cisomandate.com/when-the-tool-fights-back-three-ways-ai-coding-assistants-have-become-an-attack-surface/)。
## 包含内容
### 1. IOC 扫描器 (`scanner/ais.sh`)
十一项检查，每项在章节标题下均有内联的 `What:`（目的）和 `Fix:`（修复）说明，使报告清晰易懂。IOC 列表位于 `scanner/iocs.txt`（已版本化；可通过 `IOC_FILE=/path/to/iocs.txt` 覆盖）。
| § | 检查内容 | 覆盖的威胁 |
|---:|-------|----------------|
| 1 | Claude Code `SessionStart` 钩子注入（任意 `settings.json`）（基于 jq，低误报率） | Mini Shai-Hulud 持久化 |
| 2 | `setup.mjs` 中的 Bun 运行时投放器签名 | Mini Shai-Hulud 安装阶段 |
| 3 | 混淆的 `execution.js` 载荷——大小 **加上** 混淆信号（单行、base64、`eval(atob(`、`child_process`） | Mini Shai-Hulud 凭证窃取器 |
| 4 | `$TMPDIR` 中的恶意软件锁文件（名称来源于 IOC 列表） | Mini Shai-Hulud 哨兵 |
| 5 | `package.json` `preinstall` 脚本引用投放器文件名 | 通用供应链蠕虫入口点 |
| 6 | AI 提交的涉及 `.github/workflows/` 的提交（电子邮件白名单过滤器） | 受入侵 AI 代理身份篡改 CI |
| 7 | 含有 shell 元字符模式的 `.gemini/` 配置文件 | Gemini CLI CVSS 10.0 RCE（`v0.39.1` 之前） |
| 8 | Cursor `AGENTS.md` 和 `.cursor/` 配置引用 git 钩子 / 裸仓库 | Cursor CVE-2026-26268 |
| 9 | Git `post-checkout` / `post-merge` / `post-rewrite` / `pre-commit` 钩子包含获取并执行原语，加上 `core.hooksPath` 重定向到安全白名单之外 | CVE-2026-26268 执行原语 + 通用钩子劫持 |
| 10 | 全局安装和本地 `node_modules` 包与 IOC 列表交叉引用 | Mini Shai-Hulud SAP CAP 集合，DPRK PromptMink，未来恶意包 |
| 11 | Git 远程仓库匹配已知蠕虫窃取仓库名称（`Shai-Hulud`，`A Mini Shai-Hulud has Appeared`） | 确认入侵信号 |
**用法：**
```
bash scanner/ais.sh
# 当提示时输入您的项目文件夹
# 自定义 IOC 列表：
IOC_FILE=./my-iocs.txt bash scanner/ais.sh
# 自定义报告路径（默认：./agentic-ioc-scan-YYYYMMDD-HHMMSS.log）：
REPORT_FILE=/var/log/agentic-scan.log bash scanner/ais.sh
```
**输出**
- 发现结果以流式方式输出到终端（彩色）**并**保存到纯文本报告文件（默认 `agentic-ioc-scan-YYYYMMDD-HHMMSS.log`，通过 `tee` → `sed` 去除 ANSI 转义码）。
- 严重性标签：`[CRITICAL]`（立即处理）、`[WARNING]`（可能恶意——请验证）、`[REVIEW]`（可能合法使用——请确认）、`[OK]`（清洁）。
- 文件内容发现包括找到指标的**行号**（格式 `path:line`）。显示行号的章节：§1 钩子、§2 Bun 签名、§3 混淆信号、§5 preinstall 键、§7 Gemini 元字符、§8 AGENTS.md git 钩子引用、§9 可疑钩子内容。
- §11 蠕虫远程仓库发现还会报告有问题的 **`.git/config` 行**以及匹配的远程 URL，以便您直接定位需要移除的条目。
- `core.hooksPath` 重定向（§9）会报告仓库 `.git/config` 的绝对路径，以便审计重新分配。
- 感知工作树：当 `.git` 是一个文件（包含 `gitdir: …`）时，会先解析实际的 git 目录再进行检查。
**示例发现**
```
[CRITICAL] Repo points to known worm exfil name
Repo: /home/dev/projects/myrepo
Config: /home/dev/projects/myrepo/.git/config:9
URL: https://github.com/dhawaldesai/A-Mini-Shai-Hulud-has-Appeared
[CRITICAL] Malicious hook: /home/dev/projects/myrepo/.claude/settings.json:3
[CRITICAL] Suspicious git post-checkout hook: /home/dev/projects/myrepo/.git/hooks/post-checkout:2
```
**更新 IOC**
编辑 `scanner/iocs.txt` 并更新 `# version:` 标题。格式为 `TYPE|VALUE|NOTES`。支持的类型：
| 类型 | 使用于 | 示例 |
|------|---------|---------|
| `FILENAME` | §5 preinstall 模式 | `setup.mjs` |
| `LOCKFILE` | §4 锁文件扫描 | `tmp.987654321.lock` |
| `NPM` | §10 全局 + 本地包扫描 | `@validate-sdk/v2` |
| `PYPI` | §10（当添加 PyPI 扫描器时交叉检查） | `lightning` |
| `HOOKSTRING` | §1 钩子内容匹配（当前内联编码） | `SessionStart` |
| `REPONAME` | §11 git 远程仓库匹配 | `A Mini Shai-Hulud has Appeared` |
| `EMAILSUBSTRING` | 保留用于未来的提交者 IOC 匹配 | — |
| `CONFIGPATH` | AI 代理工具配置路径参考列表 | `.claude/settings.json` |
当出现新 IOC 时无需更改代码——扫描器在启动时读取它们，并在横幅中打印加载的版本。
**依赖项**
必需：`bash`、`find`、`grep`、`awk`、`sed`、`git`。可选：`jq`（§1 优选；若缺失则回退到 grep 启发式）、`npm`（§10 全局包检查必需；若不可用则静默跳过该章节）。
### 2. 受影响包版本扫描器 (`scanner/pkg_version_check.sh`)
IOC 扫描器的配套工具。读取受影响的 `package,version` 对的 CSV（例如 `~/Downloads/Mini Shai-Hulud - Sheet1.csv` 中的 Mini Shai-Hulud IOC 数据源——633 个 npm 包/版本对）并检查它们是否出现在：
1. 用户提供的本地项目目录中——扫描 `package.json`、`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml` 和已安装的 `node_modules//package.json`。当 CSV 包含非作用域名称时，也会检查 PyPI 清单（`requirements.txt`、`poetry.lock`、`Pipfile.lock`）。
2. 用户的 GitHub 仓库中——通过 `gh` CLI：对锁文件类型进行代码搜索，然后通过依赖图 SBOM API（`/repos/{owner}/{repo}/dependency-graph/sbom`）进行精确版本验证。
**严重性模型：** 锁文件、`node_modules/` 或 SBOM 中的精确 `pkg@version` 匹配 → `[CRITICAL]`。范围说明符（`^1.2.3`、`~1.2.3`、`>=…`）可能包含受影响版本 → `[REVIEW]`。包名匹配但未确认版本 → `[REVIEW]`。输出以流式方式显示到终端并保存到 `./shai-hulud-pkg-scan-YYYYMMDD-HHMMSS.log`（去除 ANSI 转义码），并在末尾附上严重性分类汇总。
**用法：**
```
# 交互式 — 提示项目目录
bash scanner/pkg_version_check.sh
# 完全脚本化（env-var 覆盖）
PROJECT_DIR=/path/to/project \
IOC_CSV="$HOME/Downloads/Mini Shai-Hulud - Sheet1.csv" \
REPORT_FILE=/var/log/pkg-scan.log \
bash scanner/pkg_version_check.sh --skip-node-modules
```
**CSV 格式：** 第 1 列 = 包名（支持作用域名称如 `@scope/pkg`），第 2 列 = 受影响的确切版本。自动检测并跳过标题行。可通过 `IOC_CSV=…` 覆盖路径。
**依赖项：** `bash`、`find`、`grep`、`awk`、`sed`。可选：`jq`（提高 `node_modules//package.json` 解析准确性）、`gh`（GitHub 阶段必需——若缺失或未认证则跳过该阶段并显示明确信息）。
**已知限制：**
- GitHub 代码搜索会遗漏大于 384KB 的锁文件，并且只索引默认分支——SBOM 路径是权威检查。
- GitHub 阶段受速率限制约束（认证后 10 次请求/分钟）；以每 7 秒约 5 个包的速度节流，因此完整的 633 行 CSV 对 GitHub 需要约 22 分钟。请先运行本地扫描，GitHub 阶段单独运行。
- 锁文件解析基于 `grep`，并非完全解析——深度嵌套或格式异常的文件可能产生漏报。最有价值的后续工作是使用基于 jq 的锁文件解析。
- SBOM API 要求仓库的依赖图已启用并建立索引；未启用的仓库回退到 `[REVIEW]`。
### 3. Claude Code 安全策略 (`claude-code-policy/`)
Claude Code 的预防层，补充上述检测层。
- 阻止项目级钩子运行（`allowManagedHooksOnly`）
- 阻止写入 `.claude/settings.json`
- 阻止执行已知的投放器模式
- 阻止代理工具使用 `curl`、`wget` 和 `bun` 命令
**安装：**
```
# 复制托管设置（不能被项目覆盖）
cp claude-code-policy/managed-settings.json ~/.claude/managed-settings.json
# 复制 PreToolUse hook
mkdir -p ~/.claude/hooks
cp claude-code-policy/hooks/block_shai_hulud.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/block_shai_hulud.py
```
## 路线图 / 已知缺口
- 等同于 §10 的 PyPI 全局扫描（目前仅集成了 `npm ls -g`）。
- 服务器端 `pre-receive` 钩子，用于拒绝添加来自非白名单作者的 `.claude/settings.json`、`.vscode/tasks.json` 或 `.gemini/` 文件的推送。
- 可选与 GitHub 推送保护 / 高级安全集成。
## 参考资料
- [当工具反击时](https://cisomandate.com/when-the-tool-fights-back-three-ways-ai-coding-assistants-have-become-an-attack-surface/) — 配套分析
- [Sophos: SAP npm 包上的 Mini Shai-Hulud 供应链攻击](https://www.sophos.com/en-us/blog/-mini-shai-hulud-supply-chain-attack-targets-sap-npm-packages)
- [Mend.io: Shai-Hulud 袭击 SAP — 供应链蠕虫将 Claude Code 武器化](https://www.mend.io/blog/shai-hulud-sap-cap-supply-chain-attack-claude-code/)
- [Wiz: SAP npm 上的 Mini Shai-Hulud 供应链](https://www.wiz.io/blog/mini-shai-hulud-supply-chain-sap-npm)
- [Novee Security: Google Gemini CLI RCE — CVSS 10.0 公告](https://novee.security/blog/google-gemini-cli-rce-vulnerability-cvss-10-critical-security-advisory/)
- [The Hacker News: Google 修复 CVSS 10 Gemini CLI CI/CD RCE（也涵盖 Cursor CVE-2026-26268）](https://thehackernews.com/2026/04/google-fixes-cvss-10-gemini-cli-ci-rce.html)
- [ReversingLabs: PromptMink — 通过 Claude 插入代码库的朝鲜恶意软件](https://www.reversinglabs.com/blog/claude-promptmink-malware-crypto)
- [Endor Labs: Mini Shai-Hulud 卷土重来 — 42 个带有伪造 Sigstore 徽章的恶意 npm 包针对 @antv 生态系统](https://www.endorlabs.com/learn/mini-shai-hulud-returns-42-malicious-npm-packages-fake-sigstore-badges-in-antv-ecosystem-attack)
## 贡献
欢迎提交 Issue 和 PR — 尤其是新的 IOC 提交（添加到 `scanner/iocs.txt` 并更新版本标题）、额外的平台特定扫描根目录，以及针对相邻 AI 代理工具（Continue、Cody、Codex CLI、Aider）的检测模式。
## 许可证
MIT
标签：应用安全, 暗色界面, 网络安全研究, 逆向工具