undont/supplyscan

## 快速开始 ``` brew install undont/tap/supplyscan supplyscan scan # scan current directory supplyscan check lodash 4.17.20 # check an npm package supplyscan check django 2.2.0 -e pypi # check a PyPI package ``` ## 功能 - **跨 npm 和 PyPI 的供应链检测**：聚合来自 DataDog（Shai-Hulud v2 和 TeamPCP / Mini Shai-Hulud）、GitHub Advisory Database 和 OSV.dev 的 IOC，按生态系统匹配，以防止同名包发生冲突 - **漏洞扫描**：通过 npm audit API 扫描 npm，通过 OSV.dev 扫描 PyPI - **多格式 lockfile 支持**：覆盖 npm、Yarn (classic & berry)、pnpm、Bun、Deno 和 Python (pip、Poetry、Pipenv、uv、PDM) - **启发式建议**：针对运行安装脚本的包，以及包名或 URL 中不可见或非 ASCII 字符的检测 - **CLI 和 MCP 模式**集成于单一二进制文件中，可通过 `--mcp` 切换 - **JSON 输出**：适用于脚本和 CI 使用 - **按来源缓存**：具有可配置的 TTL，使每个 IOC 源按各自的计划刷新 ### 支持的 Lockfile | 包管理器 | Lockfile | |-----------------|----------| | npm | `package-lock.json`, `npm-shrinkwrap.json` | | Yarn Classic | `yarn.lock` (v1) | | Yarn Berry | `yarn.lock` (v2+) | | pnpm | `pnpm-lock.yaml` | | Bun | `bun.lock` | | Deno | `deno.lock` | | pip | `requirements.txt` | | Poetry | `poetry.lock` | | Pipenv | `Pipfile.lock` | | uv | `uv.lock` | | PDM | `pdm.lock` | 使用 Go 编写并作为静态二进制文件发布，因此扫描器本身不会被它所扫描的包生态系统入侵。 ## 安装 ### Homebrew ``` brew install undont/tap/supplyscan ``` ### Go 安装 ``` go install github.com/undont/supplyscan/cmd/supplyscan@latest ``` 需要 Go 1.26+ 且 `$GOPATH/bin` 在你的 PATH 中。

下载二进制文件

预构建的二进制文件可从 [GitHub Releases](https://github.com/undont/supplyscan/releases) 获取： ``` # macOS (Apple Silicon) curl -L https://github.com/undont/supplyscan/releases/latest/download/supplyscan-darwin-arm64 \ -o /usr/local/bin/supplyscan && chmod +x /usr/local/bin/supplyscan # macOS (Intel) curl -L https://github.com/undont/supplyscan/releases/latest/download/supplyscan-darwin-amd64 \ -o /usr/local/bin/supplyscan && chmod +x /usr/local/bin/supplyscan # Linux (x64) curl -L https://github.com/undont/supplyscan/releases/latest/download/supplyscan-linux-amd64 \ -o /usr/local/bin/supplyscan && chmod +x /usr/local/bin/supplyscan ```

从源码构建

``` git clone https://github.com/undont/supplyscan.git cd supplyscan go build -o supplyscan ./cmd/supplyscan mv supplyscan /usr/local/bin/ ```

## CLI 用法 CLI 是默认模式；无需任何 flag。 ``` # 扫描当前目录（默认递归扫描树中的每一个文件） supplyscan scan supplyscan . # shorthand # 扫描 monorepo 根目录；查找并审计所有子包的 lockfile supplyscan scan /path/to/monorepo # 仅扫描顶层目录，不进入子目录 supplyscan scan /path/to/project --no-recursive # --shallow is an alias # 仅扫描生产依赖（排除 devDependencies） supplyscan scan --no-dev # 当某些内容无法被审计时失败（exit 3） —— 例如未固定版本的 requirements 或 # 没有 lockfile 的 manifest —— 即使未发现漏洞泄露。适用于 CI。 supplyscan scan --strict # 检查特定包（默认为 npm） supplyscan check lodash 4.17.20 # 检查 PyPI 包 supplyscan check django 2.2.0 --ecosystem pypi supplyscan check django 2.2.0 -e pypi # short form # 刷新 IOC 数据库 supplyscan refresh supplyscan refresh --force # force update even if cache is fresh # 显示状态 supplyscan status # 输出原始 JSON（用于脚本/CI） supplyscan scan --json supplyscan check lodash 4.17.20 --json # 显示帮助 supplyscan help ``` ### 退出码 | 代码 | 含义 | |------|---------| | `0` | 干净 —— 未发现任何问题 | | `1` | 错误（路径错误等） | | `2` | 发现问题 —— 存在供应链入侵或已知漏洞 | | `3` | `--strict` 模式下的覆盖缺口（某些内容无法审计；未发现问题） | 默认情况下，覆盖缺口仅为信息性提示，**不会**改变退出码；只有 `--strict` 会将其变为独立的退出码 `3`，而真正的发现（退出码 `2`）始终优先。 ## MCP Server 集成 对于 AI agent 集成（Claude Code、Cursor 等），supplyscan 可以通过 `--mcp` flag 作为 MCP server 运行。 ### Claude Code ``` brew install undont/tap/supplyscan && \ claude mcp add mcp-supplyscan --transport stdio -s user -- supplyscan --mcp ``` ### Claude Desktop / Cursor / 其他客户端 添加到你的 MCP 配置文件中： ``` { "mcpServers": { "mcp-supplyscan": { "command": "supplyscan", "args": ["--mcp"] } } } ``` ### MCP 工具 | 工具 | 描述 | |------|-------------| | `supplyscan_status` | 扫描器版本、IOC 数据库信息、支持的 lockfile | | `supplyscan_scan` | 扫描项目目录以检测入侵和漏洞 | | `supplyscan_check` | 检查单个 package@version | | `supplyscan_refresh` | 从上游来源更新 IOC 数据库 |

工具参数

#### `supplyscan_scan` | 参数 | 类型 | 描述 | |-----------|------|-------------| | `path` | string | 项目目录的路径 | | `include_dev` | boolean | 包含开发依赖（默认：`true`） | #### `supplyscan_check` | 参数 | 类型 | 描述 | |-----------|------|-------------| | `package` | string | 包名 | | `version` | string | 包版本 | | `ecosystem` | string | `npm`（默认）或 `pypi` | #### `supplyscan_refresh` | 参数 | 类型 | 描述 | |-----------|------|-------------| | `force` | boolean | 即使缓存是最新的也强制刷新 |

## 更新 ``` # Homebrew brew upgrade supplyscan # Go go install github.com/undont/supplyscan/cmd/supplyscan@latest ``` 使用 `supplyscan status` (CLI) 或 `supplyscan_status` (MCP) 检查你当前的版本。 ## 数据源 ### IOC 源（已聚合） - **[DataDog Indicators of Compromise — Shai-Hulud v2](https://github.com/DataDog/indicators-of-compromise/tree/main/shai-hulud-2.0)** 包含原始的 Shai-Hulud 蠕虫包 (npm) - **[DataDog Indicators of Compromise — TeamPCP](https://github.com/DataDog/indicators-of-compromise/tree/main/teampcp)** 包含 Mini Shai-Hulud / TeamPCP 活动（npm 和 PyPI 记录） - **[GitHub Advisory Database](https://github.com/advisories)** 包含 npm 和 PyPI (`pip`) 恶意软件通告 (GHSA) - **[OSV.dev](https://osv.dev)** 包含 npm 和 PyPI 恶意软件条目（`MAL-` 通告） ### 漏洞数据 - **[npm audit API](https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities)** 包含 npm 包中的已知 CVE - **[OSV.dev querybatch](https://google.github.io/osv.dev/post-v1-querybatch/)** 包含 PyPI 包中的已知漏洞 ### 版本范围匹配 以版本范围表示的 IOC 条目（例如 `< 1.2.3`、`>= 1.0.0, < 2.0.0`）在 **npm** 中使用 semver 进行评估，因此范围建议会匹配任何受影响的已安装版本。**PyPI** IOC 范围不进行范围评估 —— PyPI 仅匹配精确的固定版本、枚举的版本列表和全版本通配符。这是因为 PyPI 使用 PEP 440 而不是 semver，并且为了一小部分案例而添加 PEP 440 解析器违背了该工具最小攻击面的设计原则（绝大多数 PyPI 恶意软件 IOC 是枚举的特定版本或全版本域名抢注）。如果将来开始出现范围形式的 PyPI IOC，PEP 440 范围支持将被列为明确的后续跟进计划。 ## 许可证 [MIT](LICENCE)

标签：EVTX分析, Go, LNA, Ruby工具, WebSocket, 依赖分析, 动态分析, 文档安全, 日志审计