Dmitrze/repo-trust

## 为什么会有这个项目 2024年，研究人员在 18,617 个 GitHub 仓库中发现了 [**约 600 万个疑似虚假 Star**](https://arxiv.org/pdf/2412.13459) —— 在拥有 50 个以上 Star 的仓库中，大约有 **16%** 表现出虚假 Star 活动的迹象。Fork 无法反映真实情况。“最后一次提交在 2 天前”这句话，根本无法告诉你这是单人“公交车因子”（Bus factor，即项目关键维护者流失风险）还是滞后的 Scorecard 评分。 GitHub Star 只是受欢迎程度的信号，而不是信任的信号 —— 然而开发者、技术侦察人员和采购团队每天都在把它当作衡量可信度的捷径。 现有工具只能解决部分问题： - **OpenSSF Scorecard** 非常出色 —— 但它评估的是 *安全性*，而不是信任度。 - **deps.dev** 聚合了丰富的数据 —— 但它仅提供 API，没有任何观点和建议。 - **Snyk Advisor** 和 **Socket.dev** 是受 SaaS 限制的闭源服务。 - **StarScout** 是一个研究产物，并不是你可以安装使用的工具。 **Repo Trust** 填补了这一尽职调查层的空白：它是一个免费、开源、可在本地运行的 CLI 工具，将五个信任维度的评估结合成一份可解释的报告。 ## 功能特性 对于任何公开的 GitHub 仓库，`repo-trust scan` 都会生成一个介于 0 到 100 之间的 **信任评分**，该评分由以下五个模块组成： | 模块 | 衡量内容 | | --- | --- | | ⭐ **Star 真实性** | 人气信号是真实的吗？使用 StarScout 的 9 项低活跃度特征组合 + 步调时间 z 分数 + 结合生态感知的 Fork/Watcher 比率来检测虚假 Star 模式。 | | 📈 **活跃度健康** | 仓库还“活着”吗？包含 30/90/365 天时间窗口的提交节奏、发布周期、Issue 和 PR 响应延迟、贡献者活跃情况。 | | 👥 **维护者健康** | 管理是否具有可持续性？包括“公交车因子”代理指标、提交量按作者的基尼系数、贡献者留存率、治理文档。 | | 🌍 **采用信号** | 它在实际中被使用了吗？聚合 [deps.dev](https://deps.dev) 的包存在情况 + 每周下载量。文档成熟度。 | | 🔒 **安全与就绪度** | 它准备好投入生产了吗？聚合 [OpenSSF Scorecard](https://scorecard.dev)（引入新鲜度权重）+ OSV 漏洞 + 文档完整性 + CI 工作流 + semver 规范。 | 每一项评分都附带 **证据**、一个 **置信度区间**（低 / 中 / 高），以及在数据不完整时的 **注意事项**。我们从不说 *"这个仓库是个骗局"*。我们会说 *"在抽样的加星者中，有 X% 符合低活跃度特征"*，然后由你自己得出结论。 **聚合，而非复制。** 我们通过支持 ETag 的轻量级客户端和本地 SQLite 缓存来 *调用* OpenSSF Scorecard、deps.dev、OSV 和 GitHub API。我们绝不重复造轮子。 ## 安装 ### 从源码构建 (当前版本) ``` cargo install --git https://github.com/Dmitrze/repo-trust --tag v0.1.0 ``` 需要 Rust 1.75+。如果尚未安装，请通过 [rustup.rs](https://rustup.rs/) 安装 Rust。 ### 将在 v0.1.x 中推出 - 📦 通过 `cargo install repo-trust` 从 crates.io 安装 - 🍺 Homebrew formula - 🐳 Docker image (`ghcr.io/dmitrze/repo-trust`) - 📥 适用于 Linux x86_64/arm64、macOS arm64、Windows x86_64 的独立二进制文件 发布的二进制文件均附带 SLSA 来源证明和 Sigstore 无密钥签名 —— 请参阅 [docs/RELEASE_VERIFICATION.md](docs/RELEASE_VERIFICATION.md) 了解验证步骤。 ### 推荐设置 ``` # 设置 GitHub token 以获取更高的速率限制（5000次/小时，而非60次/小时） # 在此处创建：https://github.com/settings/tokens（scope: public_repo） export GITHUB_TOKEN=ghp_... ``` ## 快速开始 ### 扫描单个仓库 ``` # 默认 standard 模式 — 5 个模块，约30秒，约200次 API 调用 repo-trust scan rust-lang/cargo # Quick 模式 — 仅 headline signals，小于5秒，约30次 API 调用 repo-trust scan rust-lang/cargo --mode quick # Deep 模式 — 完整 stargazer sampling，小于5分钟，约2000次 API 调用 repo-trust scan rust-lang/cargo --mode deep ``` ### 输出格式 ``` repo-trust scan rust-lang/cargo --format json | jq # for scripting repo-trust scan rust-lang/cargo --format md > report.md # for PRs / docs repo-trust scan rust-lang/cargo --format csv >> batch.csv # for spreadsheets repo-trust scan rust-lang/cargo --format json,md,csv # multiple at once ``` ### 选择性模块 ``` repo-trust scan rust-lang/cargo --modules security,maintainers repo-trust scan rust-lang/cargo --skip-modules stars ``` ### 本地 Web 查看器 ``` repo-trust serve # → 打开 http://localhost:8765 ``` ### 缓存管理 ``` repo-trust cache info # cache location, size, row counts repo-trust cache prune # remove expired entries repo-trust cache clear --all # full reset ``` ## 使用场景 ### 🔍 在备选方案中做出选择 你正在三个 HTTP 客户端库之间犹豫。对每一个运行 `repo-trust scan` —— 并排比较维护者集中度、采用信号和安全态势。基于数据做出决定，而不是基于 GitHub Star 带来的感觉。 ### 🛡 安全 / 采购审查 你正在审查一个公司项目的依赖关系图。对每一个顶层依赖使用 `repo-trust scan`。确定性的 JSON 输出是可审计且可复现的 —— 可以直接粘贴到供应商审查清单中。 ### 📈 作为维护者 为你自己的仓库评分。按模块划分的细目会准确地告诉你哪些方面较弱 —— 单一维护者？缺少 CODEOWNERS？Scorecard 停滞？ —— 以及哪些方面较强。改进建议既具体又具有可操作性。 ## 功能差异 ### 对比 OpenSSF Scorecard OpenSSF Scorecard 回答的是：*"这个项目是否遵循了安全最佳实践？"* Repo Trust 回答的是：*"我是否应该在所有维度上信任这个仓库？"* | 问题 | Scorecard | Repo Trust | | --- | --- | --- | | 仓库是否得到积极维护？ | ✅ | ✅ | | 是否有 CI 工作流和签名发布？ | ✅ | ✅ (聚合自 Scorecard) | | 是否存在未修复的漏洞？ | ✅ | ✅ (聚合自 OSV) | | **Star 是真实的吗？** | ❌ | ✅ Star 真实性 | | **是否由一名维护者完成了 90% 的工作？** | ❌ | ✅ 维护者健康 | | **项目在现实中是否被真正采用？** | ❌ | ✅ 采用信号 | | **整体的信任信号如何？** | ❌ (仅限安全性) | ✅ 加权综合评估 | 我们选择 **聚合** Scorecard 而不是复制它。当数据较新时，Scorecard 的评分约占我们“安全与就绪度”模块权重的 50%。如果你只需要了解安全性，请使用 Scorecard。如果你需要评估信任度，请使用我们。 ### 对比 Snyk Advisor / Socket.dev - **开源。** Apache-2.0 许可证。没有付费层级。 - **CLI 优先。** 不需要 SaaS 账户。 - **本地优先。** 不收集遥测数据。 - **可解释。** 每一项评分都附带证据和置信度区间。 - **可复现。** 相同的输入 + 评分版本 → 字节级别完全相同的 JSON。 - **版本化的方法论。** 评分机制的变化受 SemVer 规范追踪。 ## 方法论亮点 在 [`docs/methodology.md`](docs/methodology.md) 中阅读完整的方法论 (CC-BY-4.0 —— 可引用，可改编)。核心原则： - **在 v1 版本中不使用黑盒机器学习 (ML)。** 评分是一个透明的加权证据模型，并具有明确的阈值说明。 - **置信度独立于评分。** 在展示时，“高评分-低置信度”的仓库会与“高评分-高置信度”的仓库区别对待。 - **聚合，而非复制。** 我们将 OpenSSF Scorecard、deps.dev 和 OSV 的输出作为输入引入，绝不重复它们的工作。 - **设计上的保守性。** 当数据不完整时，我们会报告较低的置信度。在虚假 Star 标记上，误报被认为比漏报更糟糕 —— 真正的维护者不应该被软件中伤。 - **确定性的输出。** 相同的输入字节 ⇒ 相同的输出字节（除 `snapshot_at` 和 `runtime_seconds` 之外）。由快照测试 + 属性测试保障。参见 [ADR-0007](docs/adr/0007-deterministic-output.md)。 ## 文档 | 文档 | 涵盖内容 | | --- | --- | | [`docs/PRD.md`](docs/PRD.md) | 产品需求 —— 范围、目标、模块、路线图 | | [`docs/architecture.md`](docs/architecture.md) | 架构 —— 模块、数据流、技术选型 | | [`docs/methodology.md`](docs/methodology.md) | 公开方法论 —— 我们衡量什么以及如何衡量 (CC-BY-4.0) | | [`docs/scoring-model.md`](docs/scoring-model.md) | 版本化的评分权重、阈值、变更日志 | | [`docs/module-specs.md`](docs/module-specs.md) | 各模块的输入/输出契约 | | [`docs/benchmark-plan.md`](docs/benchmark-plan.md) | 我们如何对评分进行基准测试和验证 | | [`docs/api-notes.md`](docs/api-notes.md) | GitHub API 怪癖、速率限制说明 | | [`docs/governance.md`](docs/governance.md) | 项目治理 | | [`docs/adr/`](docs/adr/) | 12 份架构决策记录 (ADR) | ## 项目状态 **v0.1.0** —— alpha 发布。五个模块均已端到端交付。包含 274 个测试（单元测试 + 集成测试 + 快照测试 + 属性测试）。严格的 CI 准入门槛：clippy::pedantic、cargo-deny、cargo-audit、tarpaulin 覆盖率 ≥75%、rustdoc -D warnings。在 `v1.0.0` 发布之前，API 和输出格式可能还会发生变化 —— 在集成时请固定使用特定版本。 请在 [路线图](docs/PRD.md#12-roadmap) 中查看后续计划：Python/Java/Ruby 生态支持、深度模式改进、Gitlab 适配器、用于 CI 策略门禁的 `--exit-code-on-category`。 ## 致谢 Repo Trust 站在巨人的肩膀上： - **OpenSSF Scorecard** 团队，为开源安全健康指标树立了标准。 - **Google Open Source Insights / deps.dev**，提供了公开的包和仓库元数据图谱。 - **OSV.dev**，提供了开源漏洞数据库。 - **StarScout** 的作者 (He et al., ICSE 2026)，其严谨的虚假 Star 检测方法论为我们的 Star 真实性模块奠定了基础。 - **Dagster** 团队，进行了 [2023 年最初的虚假 Star 调查](https://dagster.io/blog/fake-stars)，并开源了 [`fake-star-detector`](https://github.com/dagster-io/fake-star-detector)。 如果你发表了关于仓库信任、信号或供应链完整性的研究，并且我们引用或借鉴了你的工作，请告诉我们 —— 我们会添加适当的归属说明。 ## 免责声明 `repo-trust` 生成的是概率性信号，旨在辅助人类判断。它 **不** 是安全审计、法律建议，也不能替代尽职调查。像 `HighRisk` 这样的分类反映的是针对已记录的启发式规则的评分阈值，而不是对不当行为的指控。有可能会出现误报 —— 请通过 [GitHub Issues](https://github.com/Dmitrze/repo-trust/issues) 报告这些情况。 ## 许可证 - **代码：** [Apache License 2.0](LICENSE) © 2026 Repo Trust 贡献者 - **方法论** (`docs/methodology.md`)：额外采用 [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) —— 可引用且可改编 ## 维护者 由 **Dmitry Melnik** ([@Dmitrze](https://github.com/Dmitrze)) 构建并维护。 [**dmitrymelnik.ai**](https://dmitrymelnik.ai) —— 包含指向所有渠道的链接 (X、LinkedIn、联系方式)。

标签：CISA项目, deps.dev, DevSecOps, OpenSSF, OSV, Rust, Scorecard, Vercel, WebSocket, 上游代理, 云安全监控, 依赖分析, 信任评估, 可视化界面, 多维度评分, 安全合规, 数据管道, 源码管理, 网络代理, 网络流量审计, 软件工程, 通知系统, 防伪Star, 静态分析