aatuh/evydence

# Evydence [](https://github.com/aatuh/evydence/actions/workflows/ci.yml) [](https://github.com/aatuh/evydence/actions/workflows/scorecard.yml) [](LICENSE)    Evydence 是一个自托管、API 优先的发布证据账本，专为产品安全、AppSec、平台、发布工程和合规准备团队设计。这些团队需要通过签名且对客户安全的发布证据包来回答客户关于 CVE、SBOM、来源和发布审查的问题。 官方网站： 核心客户的疑问是：“此 CVE 出现在你此版本的 SBOM 中。你们是否受影响？为什么受影响或不受影响？谁批准了该决定？我们能核实哪些证据？” Evydence 记录了支持该回答的 SBOM、漏洞扫描、VEX 或手动决定、构建来源、构件摘要、例外情况、发布包和客户交付包。 | 从这里开始 | 当你想做以下事情时使用此选项 | | --- | --- | | [客户 CVE 审查演示](examples/customer-cve-review-demo/README.md) | 检查无需外部服务的买家证明路径。 | | [买家评估概述](docs/buyer-overview.md) | 跟踪买家交付包、演示、发布证据和 API 审查路径。 | | [运营者概述](docs/operator-overview.md) | 跟踪自托管安装、操作手册和生产门禁路径。 | | [OpenAPI 参考](docs/reference/openapi.md) | 审查 `/v1` API 契约和生成的 schema。 | | [渲染的 OpenAPI 文档](docs/openapi/index.html) | 浏览生成的静态操作和 schema 参考。 | | [安装与操作](docs/how-to/install-and-operate.md) | 运行带有 PostgreSQL 和对象存储的自托管 API/worker 路径。 | | [发布证据索引](docs/reference/release-evidence-index.md) | 验证公开发布的构件、校验和、生产检查证据及限制。 | 在使用 Evydence 之前，团队通常需要将扫描器导出数据、CI 日志、Slack 审批、电子表格、对象存储文件夹和一次性的客户解答拼凑在一起。 在使用 Evydence 之后，同一个版本将拥有租户范围的 API 记录、仅追加的决定、防篡改的审计条目、签名的 bundle、可重现的报告，以及明确说明差距、假设、例外和限制的受限交付包。 它不作出法律合规结论、不授予认证、不证明 SBOM 的完整性、不将扫描器的发现视为权威，也不保证发布的安全性。 ## 当前状态 - 最适用于：评估、试点，以及在运营者审查后受控的内部自托管使用。 - 不适用于：广泛的 HA 生产环境、未经审查的受监管生产环境、托管 SaaS 或法律/合规结论。 - 当前的公开发布候选元数据记录在 [`release/current.json`](release/current.json) 中；GitHub Releases 仍然是已发布 tag 和资产的外部事实来源。 - 当前的发布证据链接了 Release Artifacts 工作流、公开的 CI `Production Check` 工作流运行、CodeQL 运行、`coverage.out` 以及来自 [发布证据索引](docs/reference/release-evidence-index.md) 的 `release-check-summary.txt`。 - 在超出本地评估范围运行之前，请参阅[生产就绪](docs/reference/production-readiness.md)、 [试点部署检查清单](docs/how-to/pilot-deployment-checklist.md) 和 [发布证据索引](docs/reference/release-evidence-index.md)。 ## Evydence 旨在回答什么问题？ Evydence 旨在让发布风险的解答可追溯到具体的对象，而不是缺乏依据的文字描述： | 客户或内部审查问题 | 承载答案的 Evydence 对象 | | --- | --- | | 我们是否受版本 `Y` 中的 `CVE-X` 影响？ | 漏洞发现以及链接到该版本的 VEX/手动决定、例外或修复记录。 | | 此解答使用的是哪个 SBOM？ | 链接到版本和构件的 SBOM 记录，包含原始 payload 哈希和对象引用。 | | 哪个扫描器结果提出了该发现？ | 漏洞扫描和带有扫描器元数据的标准化发现记录。 | | 谁批准或记录了该决定？ | 带有执行者上下文的仅追加的漏洞决定、例外、批准和审计链条目。 | | 有什么证据支持“不受影响”或“已修复”？ | VEX 影响/操作声明、链接的证据、构件摘要、构建来源和验证回执。 | | 哪些内容可以安全地与客户分享？ | 脱敏配置、客户交付包、证据 bundle 以及带有限制的包清单。 | | 客户如何验证该交付包？ | 签名的发布 bundle、包清单哈希、由 OpenAPI 支持的 API 记录、审计链验证和离线验证器路径。 | ## 当前限制 - 当前状态是一个受控的自托管生产候选版本，适用于评估、试点，以及在运营者审查后受控的内部生产环境。 - 生产 API 部署使用一个 API 写入副本；worker 可以通过 PostgreSQL outbox 锁定进行扩展。 - 容器发布使用维护者运行的 GHCR 工作流，必须通过不可变的摘要和 cosign 证据进行验证；Helm 安装不应使用浮动的镜像 tag。 - 原生 PKCS#11/HSM 模块执行、超越已记录的对象锁定验证元数据的广泛提供商端 WORM 强制执行证明、直接的特定提供商管理 API 客户端、外部组同步、受监管的生产环境以及托管 SaaS 生产环境，仍然不在当前支持的范围之内，除非部署审查填补了这些空白。 ## 当前实现 此仓库包含 `github.com/aatuh/evydence` 模块下的 Go 实现。当前的公开发布候选版本是 [`v0.1.0-rc.7`](https://github.com/aatuh/evydence/releases/tag/v0.1.0-rc.7)， 作为预发布版本发布，包含签名的归档文件、校验和、OpenAPI 和迁移校验和、覆盖率输出、生产检查摘要、SBOM/来源元数据、发布说明以及签名的发布清单。 使用 GitHub Releases 和已检查的发布证据构件作为发布候选系列的运营者安装来源。检出源代码仍然是开发路径。 发布候选系列的容器镜像在维护者镜像工作流针对该 tag 运行后，发布为 `ghcr.io/aatuh/evydence:`。将摘要和 cosign 证据作为运营者的信任输入，而不仅仅是可变的 tag。当前公开发布候选的元数据将发布归档证据与最后一次验证的项目拥有的镜像证据区分开来，因为镜像发布是一个独立的工作流。 ## 最快的证明路径 对于以审查者优先的路径，请遵循 [在 10 分钟内评估 Evydence](docs/tutorials/evaluate-in-10-minutes.md)。 对于首次本地 API 流程，请遵循[入门指南](docs/tutorials/getting-started.md)。 为了进行持久的本地评估，请在 [安装与操作](docs/how-to/install-and-operate.md) 中运行类似生产的 Compose 演练。 对于首先要检查的发布证据路径，请使用 [端到端发布证据示例](examples/end-to-end-release-evidence/README.md)。 对于无需外部服务的买家证明，请运行 [客户 CVE 审查演示](examples/customer-cve-review-demo/README.md)。 对于首个 CI 配线示例，请从 [GitHub Actions 快速入门发布证据工作流](docs/github-actions/quickstart-release-evidence.yml) 开始， 一旦你的 runner 固定了扫描器版本，便转向面向扫描器的工作流。 如需在不运行完整技术栈的情况下检查具体的 JSON 输出，请打开该示例中的示例就绪报告、 [客户交付包清单](examples/end-to-end-release-evidence/sample-customer-package-manifest.json)、 [可下载的客户交付包](examples/end-to-end-release-evidence/sample-customer-package.zip)， 以及审计链验证夹具，或者在[本地包查看器](docs/how-to/view-packages.md) 中加载打包好的交付包。 发布候选构件及其验证命令索引在 [发布证据索引](docs/reference/release-evidence-index.md) 中。如果你想 在运行 API 之前评估发布验证，请从公开的 `v0.1.0-rc.7` 版本开始。 要在 Linux amd64 上的干净临时目录中验证公开发布资产，请运行： ``` make public-release-verify TAG=v0.1.0-rc.7 ``` 首先要评估的 VEX 优先证据流程为： 1. 创建产品、版本和构件。 2. 为构件上传 SBOM 证据。 3. 为版本上传漏洞扫描证据。 4. 为故意设置的阻断性发现记录 VEX 决定或批准的例外情况。 5. 生成发布就绪报告。 6. 创建签名的发布 bundle 和对客户安全的交付包或证据 bundle。 7. 在本地查看交付包，并验证 bundle、交付包清单和审计链。 有关客户交付包审查界面的可视化预览，请参阅 [交付包查看器指南](docs/how-to/view-packages.md)。该预览使用 非敏感的打包示例数据，包含桌面和移动设备的屏幕截图，并且不会上传文件。 ## 为什么选择 Evydence 而不是现有工具？ - Dependency-Track 和漏洞管理工具在 SBOM 和 发现工作流方面表现出色；Evydence 则侧重于发布级别的证据、决定、bundle、审计链、控制、客户交付包和审查限制。 - GUAC 风格的供应链图工具在关系探索方面表现出色； Evydence 侧重于发布清单、验证回执和 面向审查者的交付包证据。 - 专注于 OpenVEX 的工具在编写或使用 VEX 声明方面表现出色； Evydence 将 VEX 作为证据存储，并将标准化的决定与版本、 扫描、SBOM 上下文、例外情况和对客户安全的包关联起来。 - Vanta、Drata 及类似的 SaaS GRC 工具是广泛的合规平台； Evydence 是一个自托管的技术证据账本，不主张 法律合规或认证。 - 利用对象存储、脚本、电子表格和临时的 Postgres 表在内部构建此功能是可能的； Evydence 从一开始就提供了带版本的 API、OpenAPI 契约、租户范围划分、幂等性、审计链、发布证据以及 经过审查的不承诺（non-claim）用语。 ### 核心产品路径 - `/v1` API、提交的 OpenAPI 契约、幂等的创建/操作请求，以及 租户范围的 Problem Details 响应。 - 产品、版本、构件、SBOM、漏洞扫描、VEX/手动 决定、例外、批准、发布 bundle、审计链验证 和对客户安全的交付包。 - 带有假设和 限制的发布就绪、漏洞决定、控制覆盖范围、CRA 就绪、安全摘要、交付包、保留和备份报告。 - PostgreSQL、对象存储、outbox worker、CLI 上传/验证助手、 GitHub Actions/GitLab 示例、SDK 封装、Compose、Helm 和气隙隔离 打包路径。 有关完整的高级功能清单（包括身份、控制、 源码/部署/事件证据、保留、备份、签名提供商 配置、提供商验证、透明度记录以及 已实现但不完善的部分），请参阅[功能地图](docs/reference/capability-map.md)。 ## 许可证、安全、支持和治理 Evydence 采用 `AGPL-3.0-only` 许可；请参阅 [LICENSE](LICENSE)。 商业许可证例外和付费支持详见 [COMMERCIAL.md](COMMERCIAL.md)。项目治理、贡献期望、 安全报告、支持路径、商标指南、发布证据 期望和发布说明记录在 [GOVERNANCE.md](GOVERNANCE.md)、 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md)、 [SUPPORT.md](SUPPORT.md)、[TRADEMARKS.md](TRADEMARKS.md)、 [RELEASE_EVIDENCE.md](RELEASE_EVIDENCE.md) 和 [CHANGELOG.md](CHANGELOG.md) 中。 这些文件保留了与仓库其余部分相同的产品边界： Evydence 支持合规准备和技术证据整理，但 不作出法律合规结论、不授予认证、不证明 SBOM 完整性、不将扫描器输出视为权威，也不保证发布 安全。 ## 本地 API ``` cp .api.env.example .api.env set -a; . ./.api.env; set +a EVYDENCE_PRINT_BOOTSTRAP_SECRET=true go run ./cmd/evydence-api ``` API 侦听在 `EVYDENCE_ADDR` 上，默认值为 `:8080`。本地引导输出包含一次性的管理员 API 密钥。对于进程内的本地演示，请将 `EVYDENCE_DATABASE_URL` 保持未设置状态；若要使用基于 PostgreSQL 的持久状态，请对其进行设置。 将该密钥用作： ``` Authorization: Bearer Idempotency-Key: ``` 如需可运行的初始证据流程，请使用[入门指南](docs/tutorials/getting-started.md)。 ## 验证 规范的发布验证参考位于 [docs/reference/release-validation.mddocs/reference/release-validation.md)。 自托管的生产就绪配置文件位于 [docs/reference/production-readiness.md](docs/reference/production-readiness.md)。 发布候选检查清单位于 [docs/reference/release-candidate.md](docs/reference/release-candidate.md)。 发布证据构件映射位于 [docs/reference/release-evidence-index.md](docs/reference/release-evidence-index.md)。 针对高风险路径的维护者审查策略位于 [docs/reference/maintainer-review-policy.md](docs/reference/maintainer-review-policy.md)。 公开的路线图和发布节奏位于 [docs/reference/roadmap.md](docs/reference/roadmap.md)。 常见的本地检查： ``` make test make openapi-check make fast-check ``` PostgreSQL 检查是可选的，以保持单元测试的快速运行： ``` make compose-up set -a; . ./.test.env; set +a make live-postgres-check make postgres-integration-test ``` `make finalize` 运行项目拥有的格式化、单元测试、OpenAPI、文档、部署和 SDK 门禁。`make release-check` 在此基础上扩展，当配置了 `EVYDENCE_TEST_DATABASE_URL` 时，将运行 lint、gosec、govulncheck、竞态测试和实时 PostgreSQL 门禁。`make coverage` 是无数据库的本地覆盖率视图；`make coverage-check` 是生产覆盖率门禁，需要 `EVYDENCE_TEST_DATABASE_URL` 以便包含基于 PostgreSQL 的覆盖率。 `make production-check` 更为严格：它需要 `EVYDENCE_TEST_DATABASE_URL`，强制执行配置的覆盖率阈值，并运行发布构件签名冒烟测试。通过该门禁是发布候选证据的必要条件，但它本身并不能填补剩余的服务分解、PKCS#11/原生 HSM 保管、直接的特定提供商管理 API/组同步、超越已配置的存储桶/样本对象检查的更广泛对象锁定强制执行、HA 和退出审查工作。生产 API 和 worker 进程默认使用仅限关系型的 PostgreSQL 负载，并跳过兼容性快照写入；兼容性快照仍然用于迁移、恢复和本地工作流。租户、凭据哈希、幂等性、审计链条目、发布 bundle、签名、验证结果、漏洞决定和 outbox 作业的关键运行时变更在可用时使用专用的 PostgreSQL 写入路径。产品、项目、版本、构件、证据项、证据生命周期事件、SBOM、漏洞扫描、OpenAPI 契约、VEX 文档、审计链条目和解析器 outbox 作业的发布账本和证据核心变更在可用时也使用专用的 PostgreSQL 写入路径。其余的聚合持久化调用在配置了该存储时，使用 PostgreSQL 关系同步，而不写入兼容性快照。当前的自托管生产指南仍然使用单个 API 写入副本；生产 API 启动会拒绝不支持的写入模式和声明的副本数超过一个的情况，然后通过 PostgreSQL 咨询写入租约来强制执行该策略。worker 副本可以通过 PostgreSQL outbox 行锁定进行扩展。

标签：API优先, EVTX分析, Go, GPT, Ruby工具, SBOM, 安全合规, 日志审计, 测试用例, 漏洞管理, 硬件无关, 网络代理, 请求拦截, 软件供应链安全, 远程方法调用