AlbertoMZCruz/supply-guard
GitHub: AlbertoMZCruz/supply-guard
一款离线可用的软件供应链安全扫描器，专注于检测传统漏洞扫描器无法覆盖的恶意软件包、仿冒包和行为威胁。
Stars: 1 | Forks: 0
# SupplyGuard
供应链安全扫描器，用于检测漏洞扫描器遗漏的威胁。
**零依赖。离线可用。单一二进制文件。**
SupplyGuard 通过专注于 Trivy、Grype 和 Snyk 等工具无法捕获的威胁来补充它们：恶意软件包、可疑的安装脚本、Typosquatting（误植域名/仿冒包）、IOC 匹配以及策略违规。
## 为什么选择 SupplyGuard
2026 年 3 月，npm 软件包 Axios（每周下载量超过 1 亿次）因账户被劫持而遭到入侵。恶意版本包含一个执行后自毁的 RAT payload。传统的 CVE 扫描器没有检测到它，因为它不是漏洞 —— 它是供应链攻击。
SupplyGuard 正是为了捕获此类威胁而构建的。
## 检测内容
| 检查项 | ID | 描述 |
|-------|-----|-------------|
| Lockfile 完整性 | SG001 | 缺失、损坏或不同步的 lockfile |
| Install scripts | SG002 | 具有可疑模式的生命周期脚本（postinstall, preinstall） |
| IOC 匹配 | SG003 | 已知的恶意软件包、C2 域和可疑的维护者邮箱 |
| 依赖年龄 | SG004 | 发布不到 N 天的软件包 |
| 幽灵依赖 | SG005 | 在 manifest 中存在但从未在源代码中导入的依赖 |
| Typosquatting | SG006 | 与流行软件包名称可疑相似的包名 |
| 来源验证 | SG007 | 缺失完整性哈希、校验和或 SLSA/Sigstore 证明 |
| 配置加固 | SG008 | 不安全的包管理器配置 |
| Actions pinning | SG009 | 使用标签而不是 SHA pin 的 GitHub Actions |
| 网络调用 | SG010 | 发起网络请求、使用 exec API 或联系 C2 域的脚本 |
| 版本范围 | SG011 | 依赖 manifest 中过于宽松或无限制的版本范围 |
| CI install audit | SG012 | CI workflow 中的不安全安装命令（例如使用 `npm install` 而不是 `npm ci`） |
## 支持的生态系统
- **npm** (package.json, package-lock.json, .npmrc)
- **pip/PyPI** (requirements.txt, poetry.lock, pyproject.toml, .pth files)
- **Cargo** (Cargo.toml, Cargo.lock, build.rs)
- **NuGet** (.csproj, packages.lock.json)
- **Maven** (pom.xml)
- **Gradle** (build.gradle, verification-metadata.xml)
## 快速开始
```
# 扫描当前目录
supply-guard scan
# 扫描特定项目
supply-guard scan /path/to/project
# 用于 CI 解析的 JSON 输出
supply-guard scan -o json -q
# 用于 GitHub Code Scanning / VS Code 的 SARIF 输出
supply-guard scan -o sarif
# 用于 PR comments 和 AI chat 的 Markdown 输出
supply-guard scan -o markdown -q
# Auto-fix patches (pipe to git apply)
supply-guard scan -o diff -q > fixes.patch && git apply fixes.patch
# Fail CI on critical or high findings
supply-guard scan --fail-on critical,high
# Only show new findings vs. a baseline
supply-guard scan -o json -q > baseline.json
# ... later ...
supply-guard scan --baseline baseline.json -o json -q
# Watch mode (re-scans on file changes)
supply-guard scan --watch
# 在您的项目中初始化 hardening config
supply-guard init
# Install AI agent integration files (Cursor rules, MCP configs, AGENTS.md, SKILL.md)
supply-guard agents install
# 仅安装 Cursor-specific 文件
supply-guard agents install --cursor
# 检查已安装的 agent 文件
supply-guard agents list
# 从保存的扫描生成 PR comment
supply-guard report scan-result.json -f pr-comment
```
## 安装
### 快速安装（推荐）
```
curl -sSf https://raw.githubusercontent.com/AlbertoMZCruz/supply-guard/main/install.sh | sh
```
此命令会自动检测您的操作系统和架构，下载最新版本并安装到 `/usr/local/bin`。
### GitHub Releases
从 [GitHub Releases](https://github.com/AlbertoMZCruz/supply-guard/releases) 下载适用于 Linux、macOS 和 Windows (amd64/arm64) 的预编译二进制文件。
### Docker
```
docker run --rm -v $(pwd):/project ghcr.io/albertomzcruz/supply-guard scan /project
```
### 从源代码构建
```
go install github.com/AlbertoMZCruz/supply-guard/cmd/supply-guard@latest
```
## 配置
在项目根目录创建 `supplyguard.yaml`（或运行 `supply-guard init`）：
```
output: table
fail_on:
- critical
- high
ecosystems:
npm:
enabled: true
pip:
enabled: true
checks:
dependency_age_days: 7
# Version range strictness: exact, conservative, permissive
version_range_strictness: conservative
# Disable specific checks by ID (SG001-SG012)
# disabled:
# - SG005
# 完全忽略 packages (all checks)
ignore:
- some-trusted-internal-package
# Granular ignore rules (all non-empty fields must match)
# ignore_rules:
# - check: SG002
# package: esbuild
# reason: "trusted build tool"
# - check: SG009
# file: ".github/workflows/sonarcloud.yml"
# reason: "pinning managed by Renovate"
```
## CI/CD 集成
### GitHub Actions
```
- name: Install supply-guard
run: curl -sSf https://raw.githubusercontent.com/AlbertoMZCruz/supply-guard/main/install.sh | sh
- name: Supply chain security scan
run: supply-guard scan --fail-on critical,high -o sarif > results.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
### Docker (任意 CI)
```
docker run --rm -v $(pwd):/project ghcr.io/albertomzcruz/supply-guard scan /project --fail-on critical,high
```
适用于 GitHub Actions、Azure DevOps、GitLab CI、Jenkins 和 Bitbucket Pipelines。SupplyGuard 会自动检测 CI 环境并相应地调整输出。
## 安全特性
- **安全文件读取**：所有文件读取都通过带有 O_NOFOLLOW（防止符号链接竞争）、50 MB 大小上限和 `LimitReader` 强制执行的 `safefile.ReadFile` 进行。
- **有界的目录遍历**：`safefile.WalkDir` 强制执行最大深度 (20) 和文件数量 (50,000) 限制，以防止恶意仓库导致的资源耗尽。
- **终端转义保护**：表格输出中的所有不可信数据都经过清理，以防止恶意软件包名称导致的 ANSI 转义注入。
- **配置注入警告**：检测被扫描的仓库是否植入了可能禁用检查的 `supplyguard.yaml`。使用 `--config` 指定受信任的路径，或设置 `SUPPLYGUARD_TRUST_PROJECT_CONFIG=true` 以抑制警告。
- **仅 HTTPS 更新**：`update` 命令强制使用 HTTPS 并阻止重定向降级。
- **可更新的威胁情报**：`supply-guard update` 将最新的 IOC 数据库下载到 `~/.config/supplyguard/iocs.json`，该文件会自动优先于嵌入数据被使用。
## AI/Agent 集成
SupplyGuard 旨在成为一流的 AI-agent 友好工具。它可以通过 CLI、MCP server 或 agent 指导文件被任何 AI 编码助手使用。
### 快速设置
使用单个命令将所有 agent 集成文件安装到您的项目中：
```
supply-guard agents install
```
这将创建：
| 文件 | 用途 |
|------|---------|
| `.cursor/rules/supply-guard.mdc` | 在依赖文件编辑时自动触发扫描 |
| `.cursor/mcp.json` | 在 Cursor 中将 SupplyGuard 注册为 MCP server |
| `.vscode/mcp.json` | 在 VS Code / Copilot 中将 SupplyGuard 注册为 MCP server |
| `AGENTS.md` | Codex 和 GitHub Copilot 的 Agent 指令 |
| `SKILL.md` | Cursor skill 定义 |
使用标志选择特定集成：
```
supply-guard agents install --cursor # Cursor rule + MCP config + SKILL.md
supply-guard agents install --vscode # VS Code MCP config
supply-guard agents install --docs # AGENTS.md + SKILL.md
```
MCP 配置以非破坏性方式合并：`.cursor/mcp.json` 或 `.vscode/mcp.json` 中的现有 server 将被保留。
使用 `supply-guard agents list` 检查安装状态。
### MCP Server
`supply-guard mcp` 命令通过 stdio 启动 [Model Context Protocol](https://modelcontextprotocol.io/) server，允许 AI agent 将 SupplyGuard 作为类型化工具调用，而无需解析 CLI 输出。
#### 在 Cursor 中设置
添加到您的 MCP 配置（`.cursor/mcp.json` 或 Settings > MCP Servers）：
```
{
"mcpServers": {
"supply-guard": {
"command": "supply-guard",
"args": ["mcp"]
}
}
}
```
#### 在 VS Code / GitHub Copilot 中设置
添加到项目中的 `.vscode/mcp.json`：
```
{
"servers": {
"supply-guard": {
"type": "stdio",
"command": "supply-guard",
"args": ["mcp"]
}
}
}
```
#### 在 Claude Desktop 中设置
添加到 `claude_desktop_config.json`：
```
{
"mcpServers": {
"supply-guard": {
"command": "supply-guard",
"args": ["mcp"]
}
}
}
```
#### MCP 工具
配置完成后，您的 AI agent 可以使用以下工具：
| 工具 | 描述 | 使用示例 |
|------|-------------|---------------|
| `scan` | 对目录运行完整或定向扫描 | `scan({ directory: ".", format: "markdown" })` |
| `explain_finding` | 深入分析检查的重要性，包含真实攻击示例 | `explain_finding({ check_id: "SG006", package: "lod4sh" })` |
| `suggest_fix` | 针对发现问题的分步修复说明 | `suggest_fix({ check_id: "SG009", file: ".github/workflows/ci.yml" })` |
| `list_checks` | 列出所有 12 项安全检查及其描述和生态系统 | `list_checks({})` |
| `get_policy` | 读取当前生效的 SupplyGuard 策略配置 | `get_policy({})` |
| `install_agent_files` | 将 agent 集成文件安装到项目中 | `install_agent_files({ directory: ".", files: ["cursor-rule"] })` |
#### MCP 资源
| Resource URI | 描述 |
|---|---|
| `supplyguard://checks` | 所有检查 ID 及其描述 (JSON) |
| `supplyguard://policy/{dir}` | 目录的活动策略配置 (JSON) |
### Report 命令
从保存的 JSON 扫描结果生成格式化报告：
```
# 保存扫描结果
supply-guard scan -o json -q > scan-result.json
# GitHub PR comment (collapsible sections by severity)
supply-guard report scan-result.json -f pr-comment
# 面向利益相关者的执行摘要
supply-guard report scan-result.json -f executive-summary
# 用于安全修复的 Git commit message
supply-guard report scan-result.json -f commit-message
# Developer action items
supply-guard report scan-result.json -f developer-brief
```
### 输出格式
| 格式 | 标志 | 最适用于 |
|--------|------|----------|
| `table` | `-o table` | 人工终端显示（默认） |
| `json` | `-o json` | 程序化解析、自动化 |
| `sarif` | `-o sarif` | GitHub Code Scanning、IDE 集成 |
| `markdown` | `-o markdown` | AI 聊天显示、PR 评论 |
| `diff` | `-o diff` | 通过 `git apply` 自动应用修复 |
| `stream-json` | `-o stream-json` | 实时 NDJSON 事件流 |
### CLI 标志参考
| 标志 | 简写 | 描述 |
|------|-------|-------------|
| `--output` | `-o` | 输出格式 (table, json, sarif, markdown, diff, stream-json) |
| `--quiet` | `-q` | 隐藏 banner、警告和装饰 |
| `--fail-on` | | 在达到指定严重级别时以退出码 1 失败（例如 `critical,high`） |
| `--baseline` | | 上次扫描 JSON 的路径，仅显示新发现 |
| `--watch` | | 监视文件更改并持续重新扫描 |
| `--config` | | 受信任的配置文件路径 |
### 退出码
| 代码 | 含义 |
|------|---------|
| 0 | 成功，无发现 |
| 1 | 发现超过 `--fail-on` 严重级别阈值 |
| 2 | 扫描器错误（配置错误、路径无效等） |
| 10 | 存在严重 发现 |
| 11 | 存在高级别 发现（无严重） |
| 12 | 存在中级别 发现（无严重/高级别） |
### 修复建议
每个发现都包含一个机器可操作的 `fix` 字段（如果可用），包含：
- `type` — `replace`、`delete`、`add`、`config_change` 或 `command`
- `file`、`line` — 目标位置
- `old_content`、`new_content` — 用于确定性文本替换
- `description` — 当修复需要判断时的人工可读说明
使用 `--output diff` 从所有可修复的发现中生成兼容 `git apply` 的补丁。
### 基线差异对比
使用稳定的指纹跨时间比较扫描结果：
```
# 初始扫描
supply-guard scan -o json -q > baseline.json
# 更改后，仅显示 NEW findings
supply-guard scan --baseline baseline.json -o json -q
```
每个发现都有一个 `fingerprint` 字段（check_id + file + package + version 的 SHA-256 前缀）用于去重。
### Agent 指导文件
SupplyGuard 附带 AI agent 自动发现的文件：
| 文件 | 自动发现者 | 用途 |
|------|-------------------|---------|
| `AGENTS.md` | OpenAI Codex, GitHub Copilot | CLI 参考、工作流、项目布局 |
| `SKILL.md` | Cursor Skills | 何时使用、如何调用、如何解释结果 |
| `.cursor/rules/supply-guard.mdc` | Cursor | 编辑依赖文件时自动触发 |
| `schema/scan-result.schema.json` | 任何具备 JSON 能力的 agent | 用于验证 JSON 输出的正式 schema |
## 设计原则
- **离线优先**：所有 IOC 数据嵌入二进制文件中。无需互联网即可工作。
- **零信任**：不依赖 npm audit、pip-audit 或任何外部工具。
- **互补性**：不扫描 CVE（那是 Trivy/Grype 的工作）。检测行为威胁。
- **默认失败开放**：在本地报告发现而不阻塞。在 CI 中使用 `--fail-on` 进行门控。
- **零配置**：`supply-guard scan .` 开箱即用，具有安全的默认设置。
## 更新威胁情报
嵌入的 IOC 数据库涵盖构建时的已知威胁。要获取最新信息：
```
supply-guard update
```
这将更新的数据库保存到 `~/.config/supplyguard/iocs.json`。SupplyGuard 在可用时自动使用磁盘版本，如果不可用则回退到嵌入数据。
## 许可证
MIT
标签：Cargo, CI/CD 安全, DevSecOps, EVTX分析, GitHub Actions, IOC 匹配, Maven, npm, NuGet, pip, provenance, PyPI, RAT 检测, Rust, SLSA, Typosquatting, typo 抢注检测, 上游代理, 云安全监控, 依赖混淆, 包管理器, 单一二进制, 完整性校验, 工件安全, 开发安全, 开源软件安全, 数据投毒防御, 文档安全, 日志审计, 漏洞验证, 离线扫描, 统一API, 网络流量审计, 自动笔记, 请求拦截, 软件开发工具包, 零依赖, 静态分析