WhyzperMe/forgeguard

# ForgeGuard ForgeGuard 是一个基于 Rust 的、CLI 优先的软件供应链漏洞和风险扫描器。它专为防御性安全工程、CI/CD 门禁、SBOM 生成和安全审查工作流而设计。 ForgeGuard 目前支持静态的 Rust/Cargo 和 JavaScript 包元数据扫描。它会递归发现支持的 lockfile，跨生态系统标准化依赖项，在在线模式下查询公告情报，在离线模式下重用本地公告缓存，应用确定性的风险模型，评估本地策略，并为人类和自动化渲染报告。 ## 状态 ForgeGuard 是一个早期但已具备生产级雏形的 v0.1 项目。首先实现了兼容 Cargo 和 npm 的 JavaScript lockfile 支持。PyPI、Go、Maven、RustSec 本地数据库集成、EPSS、CISA KEV、VEX 以及更丰富的 SBOM 支持仍是计划中的扩展点。 ## 安全姿态 ForgeGuard 在扫描不受信任的仓库时故意保持保守。 默认情况下，Cargo 扫描器： - 仅解析静态文件； - 不运行 `cargo build`； - 不执行 `build.rs`； - 不运行包管理器安装脚本； - 不评估项目源代码； - 当启用网络公告查询时，仅向 OSV.dev 发送包生态系统、包名称和解析后的版本。 使用 `--offline` 或 `--no-network` 可完全禁用外部公告查询。 ## 功能 - 有界递归仓库发现 - 静态 Cargo 项目发现 - `Cargo.lock` 解析 - 在可从静态清单推断的情况下，进行直接、构建、开发和传递性依赖分类 - 静态 `package-lock.json`、`pnpm-lock.yaml` 和 Yarn v1 `yarn.lock` 解析 - 明确报告对 Bun lockfile 的不支持 - 在 OSV 查询前过滤公共 crates.io 包 - 在 OSV 查询前过滤公共 npm registry - OSV.dev 批量公告查询 - 用于离线扫描的本地 OSV 公告缓存 - 公告别名处理和发现去重 - 带有可解释原因的确定性风险评分 - 通过 `forgeguard.yml` 进行策略执行 - 终端、JSON、Markdown 和 SARIF 报告 - 最小化的 CycloneDX JSON SBOM 导出 - 离线/无网络模式 - 对 CI 友好的退出码 ## 非目标 ForgeGuard 不是： - 漏洞利用框架； - EDR 规避工具； - 网络扫描器； - Web 漏洞扫描器； - 恶意软件沙箱； - 执行不受信任依赖的工具。 ## 安装 从仓库根目录： ``` cargo build -p forgeguard --release ``` 在开发期间运行 debug 构建： ``` cargo run -p forgeguard -- --help ``` ## 快速开始 扫描一个 Cargo 项目或直接的 `Cargo.lock` 路径： ``` forgeguard scan . forgeguard scan Cargo.lock ``` 生成 JSON 输出： ``` forgeguard scan . --format json --out forgeguard-report.json forgeguard scan . --format json --output forgeguard-report.json ``` 生成 Markdown 输出： ``` forgeguard scan . --format markdown --out forgeguard-report.md ``` 生成 SARIF 输出： ``` forgeguard scan . --format sarif --out forgeguard.sarif ``` 在没有网络公告查询的情况下运行： ``` forgeguard scan . --offline forgeguard scan . --no-network forgeguard scan . --offline --strict --cache .forgeguard/osv-cache.json forgeguard cache update . forgeguard cache status --format json forgeguard cache path forgeguard policy check forgeguard-report.json --policy forgeguard.yml --json ``` 生成最小化的 CycloneDX SBOM： ``` forgeguard sbom . --format cyclonedx-json --output bom.cdx.json ``` 通过 ID 解释漏洞： ``` forgeguard explain RUSTSEC-2020-0071 ``` ## 退出码 | 退出码 | 含义 | | ---: | --- | | `0` | 命令完成；扫描策略通过或警告 | | `1` | 扫描完成但策略失败 | | `2` | 使用或配置错误，包括无效的策略文件 | | `3` | 扫描/运行时错误，包括无法读取的目标或格式错误的 lockfile | | `4` | 网络或公告源/缓存错误 | | `5` | 内部错误 | ## 策略文件 ForgeGuard 会自动在扫描的项目或 lockfile 旁边查找 `forgeguard.yml`。您也可以显式传入一个： ``` forgeguard scan . --policy forgeguard.yml ``` 示例策略： ``` fail_on: severity: high known_exploited: true fix_available: false allowlist: - id: "RUSTSEC-0000-0000" reason: "Temporary exception while upstream patch is validated" expires: "2026-01-31" licenses: deny: - AGPL-3.0 - GPL-3.0 ``` 允许列表条目必须包含原因。已过期的条目不会抑制发现。 ## CI/CD 示例 ``` name: Supply Chain Security on: pull_request: push: branches: [main] permissions: contents: read jobs: forgeguard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: persist-credentials: false - run: cargo run -p forgeguard -- scan . --policy forgeguard.yml --format markdown --out forgeguard-report.md ``` ## 终端输出示例 ``` ForgeGuard Scan Report Target: examples/vulnerable-rust-app Ecosystem: Cargo Dependencies scanned: 2 Findings: 1 Policy: warning Risk summary: Critical: 0 High: 0 Medium: 0 Low: 1 Info: 0 ``` ## 支持的生态系统 | 生态系统 | 状态 | | --- | --- | | Cargo | 在 v0.1 中支持 | | npm package-lock | 在 v0.1 中支持 | | pnpm lockfile | 在 v0.1 中支持，保守的图重建 | | Yarn v1 lockfile | 在 v0.1 中支持，保守的图重建 | | Bun lockfile | 已检测；解析器尚未实现 | | PyPI | 计划中 | | Go modules | 计划中 | | Maven | 计划中 | | CycloneDX SBOM 导入 | 计划中 | | SPDX | 计划中 | ## 隐私模型 在线模式发送的公告查询仅包含： - 生态系统； - 包名； - 包版本。 ForgeGuard 不会将源代码、环境变量、密钥、完整清单或完整的 lockfile 上传到公告 API。离线/无网络模式仅执行本地静态分析，并且不调用公告服务。 ## 架构 ForgeGuard 是一个具有严格 crate 边界的 Cargo workspace： | Crate | 职责 | | --- | --- | | `forgeguard-core` | 领域模型、风险评分、扫描报告类型 | | `forgeguard-scanner` | 有界的多生态系统 lockfile 发现 | | `forgeguard-cargo` | 静态 Cargo 发现和 lockfile 解析 | | `forgeguard-npm` | 静态 npm/pnpm/Yarn lockfile 解析 | | `forgeguard-osv` | OSV.dev 客户端和公告映射 | | `forgeguard-policy` | 策略加载、验证和评估 | | `forgeguard-report` | 表格、JSON、Markdown 和 SARIF 渲染 | | `forgeguard-cli` | CLI 编排和进程退出行为 | 详情请参阅 [`docs/architecture.md`](docs/architecture.md)。 ## 威胁模型 请参阅 [`docs/threat-model.md`](docs/threat-model.md)。 ## 开发 质量门禁： ``` cargo fmt --all -- --check cargo clippy --workspace --all-targets --all-features --locked -- -D warnings cargo test --workspace --all-features --locked cargo build --workspace --all-features --locked cargo doc --workspace --no-deps --locked ``` 本地运行： ``` cargo run -p forgeguard -- scan examples/vulnerable-rust-app ``` ## 路线图 - RustSec 本地公告数据库 - GitHub Advisory Database 扩充 - EPSS 评分 - CISA KEV 扩充 - VEX 支持 - 完整的 CycloneDX 导入/导出 - SPDX 支持 - 针对 pull request 的依赖差异扫描 - 支持 npm、PyPI、Go 和 Maven - 签名的发布版本和来源元数据

标签：Rust, SBOM生成, 加密, 可视化界面, 文档安全, 文档结构分析, 漏洞扫描器, 网络流量审计, 通知系统