Wezylnia/repo-trust-doctor

# Repository Trust Doctor [](https://github.com/Wezylnia/repo-trust-doctor/actions/workflows/ci.yml) [](https://github.com/Wezylnia/repo-trust-doctor/actions/workflows/codeql.yml) [](https://github.com/Wezylnia/repo-trust-doctor/releases) [](https://github.com/Wezylnia/repo-trust-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) [](https://github.com/Wezylnia/repo-trust-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22) [](LICENSE) Repository Trust Doctor 是一个模块化的仓库分析平台，用于判定一个开源仓库是否健康、可维护，以及是否值得使用、贡献或依赖。 本项目特意采用基于证据的方法：分析器生成的发现结果包含规则 ID、严重程度、置信度、证据和建议。评分和策略评估在解读这些发现时，不会因平均分而掩盖严重的风险。 ## 当前检查范围 当前的 `v0.8.3` 开发版本侧重于跨 12 个包生态系统的本地、静态仓库信任信号、CI/CD pipeline 安全、基础设施即代码检查以及深度代码智能： - 仓库健康文件，如 README、LICENSE、SECURITY.md、贡献文档、CODEOWNERS、模板和变更日志， - GitHub Actions 工作流风险，如宽泛的权限、`pull_request_target`、未锁定的 actions、shell 管道执行、checkout 凭证持久化以及高级加固规则， - GitLab CI 安全检查，涉及远程包含、CI 变量注入、未锁定的镜像、Docker-in-Docker 以及宽泛的缓存路径， - Azure Pipelines 安全检查，涉及 PR 变量展开、持久化凭证、未锁定的镜像以及自托管池， - CircleCI 安全检查，涉及未锁定的 orbs、Docker 执行器镜像、工作区持久化以及内联 secrets， - 可能提交的 secrets 或敏感文件，提供经过脱敏的证据并降低了误报率， - Dockerfile 规范信号，如 `latest` 标签、缺失的 `.dockerignore`、root 用户风险、缺失的健康检查、类似于 secret 的 `ENV` 以及缺失的多阶段构建， - Docker Compose 安全检查，涉及特权模式、host 网络、Docker socket 挂载以及 .env 文件加载， - Kubernetes 清单检查，涉及特权容器、共享 host namespace、hostPath 卷、宽泛的 capabilities 以及权限提升， - Terraform 基础设施检查，涉及公共 ingress、通配符 IAM、公共 S3 ACL、缺失的加密以及 provider 版本约束， - 包仓库配置检查，涉及 HTTP 仓库、内联凭证和不安全的协议， - 针对 npm、NuGet、Python、Maven、Gradle（包括版本目录）、Go、Cargo、Composer、Ruby、Dart/Pub、Elixir/Hex、SwiftPM 和 C/C++ 的依赖 lockfile 覆盖率和静态包来源信号， - Spring Boot Actuator 暴露和配置分析， - 具有稳定发现指纹的确定性 JSON、Markdown 和 SARIF 报告， - 发布产物校验和、SBOM/来源验证、变更日志、包版本、发布工作流证据以及 SBOM 关联， - 深度扫描覆盖率导入、关键代码启发式分析、多语言公共 API 提取、导入图分析以及框架路由检测， - JSON 扫描报告之间的信任差异，包含新增/已解决/恶化/改善的发现变更， - 用于 GitHub 仓库扫描的本地优先 React 工作台， - 通过分数和严重性阈值实现的 CI 门控行为。 ## 当前状态 本仓库处于 `v0.8.3` 开发里程碑阶段。它是一个稳定的静态仓库信任平台，适用于本地仓库信任审查、仓库加固、CI 门控、分析器开发、依赖清单审查、基于策略的评分、发布信任审查、深度代码智能、信任变更审查、API/worker 托管的扫描流程以及本地 React 支持的扫描审查。 在 `v0.8.3` 版本中已实现： - 整洁的 .NET 解决方案结构， - 纯领域模型， - 分析器抽象， - 共享的应用程序扫描生命周期，包含队列、状态、取消和进度模型， - 可重用的仓库扫描运行器，供 CLI、API 和 worker 主机使用， - 仅静态扫描编排， - console、JSON、Markdown 和 SARIF 报告输出， - CLI 优先的工作流， - 用于健康检查、启动、状态、进度、模块、发现、报告导出和取消的轻量级 API 扫描端点， - 基于 worker 的排队扫描执行， - 本地 React 信任工作台，可启动 GitHub 仓库扫描并直接打开已完成的报告， - 仓库健康、GitHub Actions、GitLab CI、Azure Pipelines、CircleCI、secrets 快速扫描、Docker、Docker Compose、Kubernetes 和 Terraform 分析器， - 扩展的仓库文档质量检查， - 扩展的 GitHub Actions 发布、产物和高级加固检查， - GitLab CI 安全检查， - 扩展的 Docker 缓存和包分层检查， - Docker Compose 和 Kubernetes 清单检查， - Azure Pipelines、CircleCI 和 Terraform 基础设施分析器， - 包仓库配置检查， - 针对 npm、NuGet、Python、Maven、Gradle（包括版本目录）、Go、Cargo、Composer、Ruby、Dart/Pub、Elixir/Hex、SwiftPM 和 C/C++ 的结构化依赖清单产物， - 支持的包生态系统中的 lockfile 覆盖率检查， - 直接的 NuGet `PackageReference` 解析，包括基本的 Central Package Management 版本解析， - 解析 `package.json` 中生产环境、开发环境、可选和 peer dependencies 部分， - 针对性地解析 `requirements.txt`、`pyproject.toml` 和 `Pipfile` 中的 Python 依赖， - 解析 Maven `pom.xml`、Gradle `build.gradle`、`build.gradle.kts` 和 `libs.versions.toml` 中的 Java 依赖， - 基于静态应用程序配置的 Spring Boot Actuator 暴露检查， - Go、Rust/Cargo、PHP/Composer、Ruby/Bundler、Dart/Flutter、Elixir/Hex、SwiftPM 和 C/C++ 包管理器解析， - 针对未锁定/范围版本和预发布版本的静态依赖规范发现， - 供手动审查的 npm 安装时脚本发现， - SBOM 和来源证据验证、关联以及完整性检查， - 针对 TypeScript、Python、Java、Go 和 Rust 的多语言公共 API 提取器， - 导入图分析、框架路由检测以及反序列化/命令执行启发式分析， - 重构的分析器文件，拆分为专注的辅助方法以提升可维护性， - 在无网络访问的情况下记录来自 `NuGet.config` 的 NuGet 包源， - 针对直接远程 npm 依赖、本地 npm 依赖、不安全的 NuGet 源和本地 NuGet 源的静态包来源发现， - Markdown 依赖清单摘要， - 记录在报告中的类型化信任配置， - 用于报告输出的稳定发现指纹， - 基于分数和严重性阈值的 CI 门控选项， - 基于 SQLite 的包元数据缓存和本地 OSV 公告索引（带有保守的在线回退机制）， - 依赖新鲜度、漏洞、许可证、包来源和依赖混淆审查发现， - 用于 API/worker/前端轮询的扫描进度 DTO， - 内置信任策略和基于配置的评分， - 针对校验和、SBOM/来源、变更日志/包版本对齐以及发布工作流的发布证据检查， - SBOM 和来源证据作为信息性发布证据导入， - 深度扫描中导入 Cobertura XML 和 lcov 的覆盖率， - 针对身份验证、授权、支付、数据访问、文件操作、网络调用、加密、secrets、大文件和宽泛异常处理的关键代码启发式分析， - 关键代码的低覆盖率或缺失覆盖率关联， - .NET 公共 API 表面提取和基线差异审查， - 扫描快照、信任差异、仓库比较、计划扫描和回归预警模型， - 用于比较两份 JSON 扫描报告的 CLI `diff` 命令， - 基于 fixture 的分析器测试， - 公开的规则、架构、API/worker、安全、Web UI 和贡献者文档。 默认情况下，扫描器不会执行仓库代码。扫描历史记录持久化、托管监控和通知提供程序是未来计划的工作；依赖情报会以本地方式持久化存储在 SQLite 中。 ## 环境要求 - .NET 10 SDK 或更高版本。 - Git。 ## 从源码安装 ``` git clone https://github.com/Wezylnia/repo-trust-doctor.git cd repo-trust-doctor dotnet restore dotnet build ``` ## 快速开始 运行本地静态扫描： ``` dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format console ``` 导出 Markdown 报告： ``` dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format markdown --output reports/scan.md ``` ## Web 信任工作台 React 工作台通过本地 API 后端启动 GitHub 仓库扫描，并直接打开已完成的报告。用户以 `owner/repo` 的形式输入仓库；UI 将 `https://github.com/owner/repo` 发送给后端。 ``` dotnet run --project src/Apps/RepoTrustDoctor.Api --urls http://localhost:5000 cd src/Apps/RepoTrustDoctor.Web npm install npm run dev ``` ## API 和 Worker 运行本地 API 主机： ``` dotnet run --project src/Apps/RepoTrustDoctor.Api ``` 启动并轮询扫描： ``` curl -X POST http://localhost:5000/api/scans \ -H "Content-Type: application/json" \ -d "{\"target\":\"https://github.com/owner/repo\",\"depth\":\"standard\",\"trustProfile\":\"production\"}" curl http://localhost:5000/api/scans/{scanId} curl http://localhost:5000/api/scans/{scanId}/progress curl http://localhost:5000/api/scans/{scanId}/report?format=json ``` API 接受绝对的 `https://github.com/owner/repo` 目标，并拒绝本地路径、带有凭证的 URL、查询字符串和片段。CLI 仍支持针对受信任的本地开发的本地路径扫描。worker 主机使用与 API 相同的应用程序扫描生命周期和仓库扫描运行器： ``` dotnet run --project src/Apps/RepoTrustDoctor.Worker ``` 当前的 API 和 worker 使用内存中的扫描状态和队列实现。它们旨在用于本地开发、集成测试以及未来的持久化集成。 ## CLI CLI 支持本地路径扫描以及对公共 HTTP(S) Git 仓库 URL 的浅克隆： ``` dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan https://github.com/owner/repo dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format json dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format markdown dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format sarif --output reports/scan.sarif dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format markdown --output reports/scan.md dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --format markdown --output reports/scan.md --force dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --depth deep --format markdown dotnet run --project src/Apps/RepoTrustDoctor.Cli -- diff reports/before.json reports/after.json --format markdown dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --profile enterprise dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --fail-under 75 dotnet run --project src/Apps/RepoTrustDoctor.Cli -- scan . --fail-on-severity High dotnet run --project src/Apps/RepoTrustDoctor.Cli -- --version ``` 受支持的信任配置包括 `Personal`、`ProductionDependency` 和 `SecuritySensitiveDependency`。CLI 仍然接受诸如 `enterprise`、`ci-cd` 和 `container` 等兼容性别名，并在策略评估之前对其进行规范化。 ### CLI 退出代码 | 代码 | 含义 | | ---- | ------- | | `0` | 扫描完成且没有阻断性的规避决策 | | `1` | CLI 使用错误 | | `2` | 输入/输出错误（例如拒绝覆盖现有报告） | | `3` | 扫描完成，但决策为 `AvoidAsProductionDependency` | | `4` | 配置的 CI 门控失败 | 未来打包的 CLI 命令： ``` repo-trust-doctor scan . repo-trust-doctor scan https://github.com/owner/repo repo-trust-doctor scan . --format json repo-trust-doctor scan . --format markdown repo-trust-doctor scan . --format sarif repo-trust-doctor scan . --format json --output report.json repo-trust-doctor diff before.json after.json --format markdown --output diff.md ``` ## 架构 该架构将检测与解读分离开来： - `src/Apps` 包含可执行入口点，如 CLI、API 和 worker。 - `src/Apps/RepoTrustDoctor.Web` 包含本地 React 报告查看器。 - `src/Core` 包含领域、应用程序、契约和共享原语。 - `src/Engine` 包含分析器抽象、执行、编排、评分、策略和报告。 - `src/Analyzers` 包含独立的分析器模块。 - `src/Infrastructure` 包含 Git、包仓库、安全订阅源、扫描运行器以及未来的持久化/缓存集成。 - `src/Infrastructure/RepoTrustDoctor.Infrastructure.Git` 目前负责准备本地工作区并浅克隆公共 HTTP(S) Git URL。 - `src/Infrastructure/RepoTrustDoctor.Infrastructure.Scanning` 组合了供 CLI、API 和 worker 主机使用的默认分析器 pipeline。 - `tests` 包含单元测试、分析器测试、集成测试和基于 fixture 的测试。 请阅读 [docs/architecture.md](docs/architecture.md) 中的公开架构概述。 ## 路线图 该路线图旨在逐步发展该平台： | 版本 | 侧重点 | | ------- | ----- | | `v0.1.x` | 基础 Alpha 版，静态本地扫描，基础分析器，报告输出，CI 门控 | | `v0.2.x` | 针对仓库文档、工作流、secrets、Docker 和报告扩展静态分析器 | | `v0.3.x` | 针对 NuGet、npm 和 Python 的结构化依赖清单 | | `v0.4.x` | 针对依赖元数据、漏洞、许可证和来源信号的风险情报 | | `v0.5.x` | SARIF 输出和渐进式扫描契约 | | `v0.6.x` | 内置策略、阻断性风险和基于配置的评分 | | `v0.7.x` | 发布规范、产物完整性、SBOM/来源和供应链证据 | | `v0.8.x` | 覆盖率导入、代码关键性、公共 API 分析和深度扫描信号 | | `v0.9.x` | 信任历史、比较、信任差异和模型 | | `v0.7.0` | 具有文档化契约、CLI/API/worker 主机、React 扫描工作台和可靠报告的稳定公开平台 | | `v0.7.2` | Java 和 Spring Boot 依赖支持，以及持续优化的 React/后端扫描体验 | | `v0.7.3` | Go、Cargo、Composer、Ruby、Dart/Pub、Elixir/Hex、SwiftPM 和 C/C++ 依赖清单 | | `v0.7.4` | 工作区检测和更清晰的 console/报告下钻 | | `v0.7.5` | GitLab CI、Docker Compose 和 Kubernetes 静态安全检查 | | `v0.8.0` | SBOM/来源证据导入和审查加固 | | `v0.8.1` | Azure Pipelines、CircleCI 和 Terraform 静态安全检查；包仓库配置规则；SBOM 关联；GitHub Actions 高级加固；Gradle 版本目录支持 | | `v1.7.x` | 多语言公共 API 提取、导入图分析、框架路由检测、反序列化/命令执行启发式分析、更深入的代码智能和误报减少 | 有关详细的里程碑范围、范围外边界和成功标准，请参阅 [docs/roadmap.md](docs/roadmap.md)。 ## 安全原则 - 默认情况下不执行不受信任的仓库代码。 - 优先使用静态解析和元数据查找。 - 在证据中脱敏可能的 secrets。 - 隔离分析器故障，以便部分报告仍然有用。 - 对启发式发现使用谨慎的措辞。 - 没有明确的接收策略，不接受任意上传的文件。 - 除非提供 `--force`，否则拒绝覆盖报告。 ## 文档 - [架构](docs/architecture.md) - [分析器覆盖率](docs/analyzers.md) - [路线图](docs/roadmap.md) - [开发指南](docs/development.md) - [本地依赖情报](docs/local-intelligence.md) - [CI 用法](docs/ci-usage.md) - [分析器编写指南](docs/analyzer-authoring.md) - [报告格式](docs/report-format.md) - [API 和 Worker](docs/api-worker.md) - [信任历史和差异](docs/trust-history.md) - [Web UI](docs/web-ui.md) - [发布检查清单](docs/release-checklist.md) - [信任配置](docs/policies/trust-profiles.md) - [规则目录](docs/rules/README.md) - [变更日志](CHANGELOG.md) ## 仓库治理 公开仓库使用受保护的 `main` 分支，要求非管理员贡献者进行 pull request 审查，要求进行 CI 状态检查，并使用了 CodeQL、OSSF Scorecard、Dependabot 和 Copilot 审查指令。仓库管理员可以绕过分支保护以进行紧急维护。 ## 许可证 本项目基于 Apache License 2.0 授权。有关详细信息，请参阅 [LICENSE](./LICENSE) 文件。 ## 免责声明 repo-trust-doctor 提供基于启发式证据的仓库分析。它不保证仓库、依赖项、工作流、包或发布是安全、合规或无漏洞的。 报告可能包含误报或漏报。该工具旨在支持决策制定，不能替代手动审查、法律审查、安全测试或专业审计。

标签：CI/CD安全, Llama, 开源治理, 暗色界面, 静态扫描