jt-systems/installguard
GitHub: jt-systems/installguard
面向 npm 和 PyPI 生态的供应链策略守卫，在依赖安装前通过多维信号评估与可配置策略规则拦截高风险包，变被动漏洞检测为主动风险预防。
Stars: 1 | Forks: 0
# InstallGuard
[](LICENSE)
[](ROADMAP.md)
[](whitepaper.md)
[](https://installguard.dev)
## 为什么需要 InstallGuard
针对 npm、PyPI 及类似生态系统的现代供应链攻击，越来越依赖于**发布**与**检测**之间的时间差：维护者账号被盗，带毒的补丁被发布，CI 在几分钟内将其安装，机密信息随之泄露，而该版本在传统扫描器察觉之前就被下架了。
CVE 数据库和恶意软件特征码是必不可少的，但它们是被动的。它们只能检测*已知*的入侵——无法减少*新兴*入侵带来的风险暴露。
InstallGuard 采取了不同的切入点：
- 在采用全新版本的包之前先**等待**。
- **批准**允许哪些包在安装期运行脚本。
- **阻止**依赖项来自异构来源（Git URL、tarball、GitHub 快捷方式）。
- 在 PR 阶段而非发生数据泄露之后**洞察**依赖项风险。
- 通过签名证明，**证明**构建过程受特定策略的约束。
请阅读 [whitepaper.md](whitepaper.md) 中的详细背景论文。
## 功能介绍
状态说明：☑ 已发布 · ◐ 部分完成 · ☐ 计划中
| 能力 | 状态 |
| ---------- | :----: |
| Lockfile 适配器：`package-lock.json`、`pnpm-lock.yaml`、`yarn.lock`、`uv.lock`、`poetry.lock`、经过哈希处理的 `requirements.txt` | ☑ |
| 最低发布时间强制执行（按环境区分，支持直接依赖覆盖） | ☑ |
| 生命周期脚本批准列表（`preinstall` / `install` / `postinstall`） | ☑ |
| 异构来源阻止（Git、tarball、GitHub 快捷方式） | ☑ |
| 多信号检测：发布者变更、包弃用、dist-tag 变动、文件集差异、账号注册时间、拼写错误/同形异义词、可疑脚本静态分析 | ☑ |
| 信任评分计算，包含各信号贡献度细分 | ☑ |
| 外部信号提供者：OSV/GHSA 公告、deps.dev 项目元数据、OpenSSF Scorecard | ☑ |
| 用于第三方提供者的公共 `SignalProvider` trait（参见 [`crates/core/examples/minimal_provider.rs`](crates/core/examples/minimal_provider.rs)） | ☑ |
| PR 注释（GitHub Action、GitLab MR 小组件）+ 按 PR 生成的风险摘要 | ☑ |
| 确定性的 `installguard.lock` + in-toto 证明 (`policy-evaluation/v1`) | ☑ |
| CycloneDX SBOM 导出，包含策略决定属性 + 各包 VEX | ☑ |
| `--frozen` 离线重新验证（基于已记录的快照） | ☑ |
| PyPI 安装期扫描（`setup.py` + 标准 `.tar.gz` sdist 内的 PEP 517 backend-path） | ◐ |
| 维护者双重身份验证 (2FA) 状态检查 | ◐ 推迟（Registry 未在免认证状态下公开此信息） |
| Sigstore 签名（cosign 无密钥 / KMS）用于证明 | ◐ 结构化来源匹配已发布；完整的 Fulcio/Rekor 验证已推迟 |
| 沙箱化的安装脚本执行 | ☐ 计划中 (M5) |
| Registry 代理强制执行 (Verdaccio / Artifactory / Nexus) | ☐ 计划中 (M6) |
| PyPI 之外的其他生态系统 (crates.io, Go, RubyGems, …) | ☐ 计划中 (M8+) |
有关里程碑的详细信息请参见 [路线图](ROADMAP.md)，技术范围请参见[设计文档](DESIGN.md)。
## 如何融入现有体系
InstallGuard 是对以下工具的**补充**，而非替代品：
- `npm audit`、Snyk、osv-scanner — 保留它们；它们负责捕获*已知*漏洞。
- Dependabot / Renovate — 保留它们；InstallGuard 让它们的 PR 合并起来更安全。
- pnpm 内置功能（`minimumReleaseAge`、`onlyBuiltDependencies`）— InstallGuard 在整个组织范围内将这些功能*操作化*：提供中央策略、审计、证明以及跨生态系统的证据。
目前的对比和定位详见 [installguard.dev/start/what](https://installguard.dev/start/what/)。
## 快速开始
```
# Homebrew (macOS, Linux)
brew install jt-systems/installguard/installguard
# 或从源码构建 (Rust 1.86+)：
cargo install --path crates/cli
# 扫描当前项目 (自动检测 npm / pnpm / yarn / uv / poetry / hashed requirements)
installguard scan
# 对发现结果进行分类，并输出可直接粘贴的 installguard.yaml 块
installguard doctor
# 在 CI 中：对策略违规进行严格失败处理
installguard ci --summary-file installguard-summary.json
# 生成评估的未签名 in-toto attestation
installguard attest --out installguard.intoto.json
# 离线 CI：根据记录的快照重新进行离线验证
installguard ci --frozen
```
外部信号提供者（OSV、deps.dev、OpenSSF Scorecard）默认开启，在离线运行时可单独禁用：
```
installguard scan --no-osv --no-deps-dev --no-scorecard
```
策略示例（`installguard.yaml`）：
```
policyVersion: 1
defaults:
minimumReleaseAge: 1440 # minutes (24h)
blockExoticSubdeps: true
detectPublisherChange: true
flagDeprecated: true
detectVersionSurfaceChange: true
minMaintainerAccountAgeDays: 30
requireProvenance: false # opt-in once your supply chain emits it
maxAdvisorySeverity: high # OSV / GHSA gate
requireLicense: true # deps.dev gate
licenseAllowlist: [MIT, Apache-2.0, BSD-3-Clause, ISC]
blockArchived: true
minScorecardScore: 5 # OpenSSF Scorecard 0-10
minTrustScore: 60
scripts:
policy: deny-by-default
allow: [esbuild, sharp, playwright]
direct:
minimumReleaseAge: 4320 # stricter for direct deps
detectPublisherChange: true
```
完整的 DSL 请参见 [DESIGN.md §4](DESIGN.md#4-policy-dsl)。更多示例存放在 `examples/policies/` 中。
## 安全安装工作流
InstallGuard 将依赖项获取与脚本执行分离开来：
```
# npm
npm ci --ignore-scripts && installguard scan && npm rebuild
# pnpm
pnpm install --ignore-scripts && installguard scan && pnpm rebuild
# yarn (Berry)
yarn install --mode=skip-build && installguard scan && yarn rebuild
```
如果有任何一项不符合策略，脚本将不会运行。
## 项目状态
InstallGuard 目前处于 **alpha** 阶段。里程碑 0–4 已经发布，此外还有首个“超越 npm”的重要部分：针对 `uv.lock`、`poetry.lock`、经过哈希处理的 `requirements.txt` 的 PyPI 支持，PyPI Registry 信号，Scorecard 对接，PEP 740 声明来源，以及对 `.tar.gz` sdist 中 `setup.py` 及其 PEP 517 `backend-path` 的扫描。接下来的重点领域是沙箱化脚本执行 (M5) 和 Registry 代理强制执行 (M6)——详情请参阅 [ROADMAP.md](ROADMAP.md)。
如果您有兴趣进行早期采用、威胁模型审查、提供真实 lockfile 用于适配器测试，或者贡献规则想法，请提交 Issue。
## 文档
- [白皮书](whitepaper.md) — 背景论文：概念模型、威胁模型、标准映射及其局限性。
- [DESIGN.md](DESIGN.md) — 技术设计（架构、策略 DSL、证明格式、性能目标）。
- [ROADMAP.md](ROADMAP.md) — 从基础设施到合规报告的优先里程碑。
## 原则
1. **预防优于被动响应。** 减少风险暴露；而非仅仅追踪已知的 IOC（入侵指标）。
2. **确定且可审计。** 每一个决定都会被记录、可哈希、可签名。
3. **支持离线。** 没有遥测或隐藏的自动回传路径。物理隔离的部署环境是首要支持对象。
4. **分发方式简单。** 单一静态二进制文件。不需要 `node_modules`。自身不包含安装脚本。
5. **操作化现有控制措施。** 不去重新发明 pnpm、Sigstore 或 OSV——而是将它们编排起来。
6. **对局限性保持坦诚。** 参见 [白皮书 §16](whitepaper.md#16-limitations--trade-offs)。
## 许可证
采用 [Apache License, Version 2.0](LICENSE) 许可。之所以专门选择 Apache-2.0 许可证，是因为其明确的专利授权——这对于旨在被企业级采纳的安全工具来说至关重要。
标签：CI/CD安全, DNS 解析, GNU通用公共许可证, IP 地址批量处理, Llama, Node.js, npm, pnpm, PyPI, Python, SBOM, Syscall 审计, yarn, 云安全监控, 依赖管理, 包拦截, 包管理器, 可视化界面, 同形异义词检测, 安全策略, 安全网关, 开发安全, 提示词设计, 搜索语句（dork）, 攻击防御, 无后门, 暗色界面, 构建证明, 漏洞防御, 硬件无关, 统一API, 跌倒检测, 软件物料清单, 通知系统, 钓鱼防御, 零日攻击防护, 静态分析