ralabarta/agentproof

AgentProof 是一个**本地优先的 Go CLI**，它将 Codex 和 Claude Code 会话与 Git 更改关联起来，摄取测试结果工件，检测确定性风险，评估代码影响，并生成可重现的 **Markdown、HTML 和 JSON 证据**。 无需账户。无需服务。无需遥测。无需网络请求。 ## 快速开始 ``` go install github.com/ralabarta/agentproof/cmd/agentproof@latest agentproof init agentproof record --objective "Protect refresh tokens from replay" --agent codex -- codex agentproof verify --test-result test-results.jsonl ``` ``` AgentProof verification: WARNING ✓ Required evidence complete: 3/3 ✓ Canonical manifest integrity passed ✓ 28 test results passed ✓ No secret patterns detected in captured added lines ⚠ Authentication or authorization code modified Affected components: internal/auth, internal/api Bundle ID: 7f0c…d91a ``` ## 为什么选择 AgentProof 编码 Agent 的证据通常散落在终端会话、Git、CI 日志和代码审查工具中。AgentProof 将这些来源汇总成一个经过完整性校验的包裹，同时将原始会话内容保留在你的本地机器上。 | | 原则 | 实际意义 | |---|---|---| | 🔒 | **默认本地** | 无账户、无服务、无遥测、无网络请求 | | 🧭 | **诚实关联** | Git/会话匹配是一种*关联*，绝不是作者身份声明 | | 🚧 | **失败即关闭证据** | 缺失或状态不明确的必需来源绝不会变成通过 | | 🎯 | **确定性检查** | 稳定的发现 ID、有序的输出、有界的解析器、规范的清单 | | 🍴 | **感知 Fork 的 CI** | 验证过程只摄取工件；它绝不运行测试、hooks、构建或仓库命令 | ### 证据词汇表 每一个面向人类的声明都在三个独立的维度上进行分类。这是信任模型的核心，并且是强制执行的：这些词汇表在 `internal/evidence` 中枚举，如果本节内容与它们不一致，测试就会失败。 **证据状态** — 是否捕获到了来源？ | 状态 | 含义 | |---|---| | `observed` | 直接从 Git、进程结果或提供的工件中捕获 | | `missing` | 已声明且为必需，但在声明位置不存在 | | `unsupported` | 当前版本未处理 | | `unknown` | 已尝试但状态不明确，且说明了原因 | | `not_observed` | 从未声明或发现，因此不期望任何内容 | **声明置信度** — 结论距离捕获的字节有多远？ | 置信度 | 含义 | |---|---| | `observed` | 直接从捕获的证据中读取 | | `derived` | 从证据中按确定性逻辑计算得出 | | `inferred` | 因 AgentProof 观察到但无法控制的条件而减弱 | **关联度** — 更改与记录窗口的绑定程度有多紧密？绝不是对作者身份的声明。 | 关联度 | 含义 | |---|---| | `clean-baseline` | 基准是干净的，因此 Git 范围是精确的 | | `contaminated-baseline` | 未提交的工作早于记录时间，无法单独分离 | | `unknown-uncaptured-worktree` | 更改的内容无法捕获，因此范围不完整 | ## 安装 下载发布归档文件并根据 `checksums.txt` 进行验证，或者使用 Go 1.22+ 从源码构建： ``` go install github.com/ralabarta/agentproof/cmd/agentproof@latest ```

本地开发

``` git clone https://github.com/ralabarta/agentproof.git cd agentproof make test make build ``` 运行时仅依赖 Go 标准库——无需安装其他任何内容。

## 记录 Agent 会话 在现有的 Git 仓库中进行初始化，并在首次记录之前提交生成的配置： ``` agentproof init git add .agentproof/config.json .agentproof/.gitignore git commit -m "chore: configure AgentProof" ``` 从干净的工作树开始以获得最强的关联度： ``` agentproof record \ --objective "Add session rotation" \ --agent codex \ --model gpt-5 \ -- codex ``` Claude Code 使用相同的包装器： ``` agentproof record --objective "Add audit logging" --agent claude -- claude ``` 原生适配器是基于启发式规则的，并且也按此进行版本控制。不支持或格式错误的工件会变成可见的 `unknown` 证据——它们绝不会在未经提示的情况下被接受。

原始输出保留（可选开启，默认关闭）

``` agentproof record --retain-raw --objective "Reproduce issue" -- codex agentproof purge --raw # preview files older than seven days agentproof purge --raw --confirm # delete the previewed selection ```

## 提供测试证据 AgentProof 在验证过程中有意不运行仓库代码。在你现有的测试作业中生成结果，然后提供一个或多个工件： ``` mkdir -p .agentproof/inputs go test -json ./... > .agentproof/inputs/test-results.jsonl agentproof verify --test-result .agentproof/inputs/test-results.jsonl --require-tests ``` 目前支持的格式： - Go `go test -json` / `test2json` JSON Lines - 来自现有测试运行器的 JUnit XML 声明的文件都是受限的、经过路径检查的，如果是符号链接则会被拒绝，同时会被哈希处理并作为数据进行解析。**嵌入在工件中的命令永远不会被执行。** ## 验证 Git 范围 在没有记录本地会话的情况下，验证 pull-request 范围，而不声称其源自 Agent： ``` agentproof verify --base origin/main --test-result junit.xml ``` 输出内容会写入 `.agentproof/` 目录下： | 文件 | 用途 | |---|---| | `manifest.json` | 规范的来源普查和计算出的包裹身份 | | `evidence.json` | 完整的标准化验证结果 | | `attestation.json` | 生成的清单哈希值以及包裹 ID | | `report.md` | 适用于 Pull-request 和终端的报告 | | `report.html` | 包含严格 CSP 的离线自包含报告 | AgentProof 使用下方的 Action 验证自身的 pull request。**[`docs/example-report.md`](docs/example-report.md) 是来自此仓库的真实生成输出，而非模拟。** 退出代码： | 代码 | 含义 | |---:|---| | `0` | 通过或仅有警告的结果 | | `1` | 必需的证据、测试或配置的确定性策略失败 | | `2` | 无效的命令使用或配置 | | `3` | 适配器、分析器、仓库或内部处理失败 | ## GitHub Action 将 AgentProof 固定到完整的发布提交 SHA。对于验证基础设施，不建议使用浮动的 tag。 ``` permissions: contents: read steps: - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3 with: fetch-depth: 0 - uses: ralabarta/agentproof@ with: base: origin/${{ github.base_ref }} test-results: | .agentproof/inputs/go-test.jsonl .agentproof/inputs/junit.xml require-tests: "true" fail-on: critical ``` 该 Action 请求**只读**的仓库权限，输出机器可读的结果，并上传报告包裹。默认情况下它不会对 pull request 进行评论——评论的发布应该是一个独立的、明确受信任的工作流，且该工作流仅消费生成的报告。

Action 的输入与输出

| 输入 | 默认值 | 用途 | |---|---|---| | `base` | *必需* | 要进行比对的 Git 基准 | | `test-results` | – | 以换行符分隔的工件路径 | | `require-tests` | `"false"` | 当没有测试证据时失败 | | `fail-on` | `critical` | 导致作业失败的严重性阈值 | | 输出 | 用途 | |---|---| | `conclusion` | `passed`、`warning` 或 `failed` | | `bundle-id` | SHA-256 包裹身份标识 | | `completeness` | 必需证据的完整度百分比 | | `integrity` | 规范清单完整性结果 | | `critical-violations` | 关键发现计数 | | `warnings` | 警告计数 | | `report` | 生成的 Markdown 报告路径 |

## 当前分析 | 语言 | 导入分析 | |---|---| | Go | 标准 `go/parser` | | TypeScript / JavaScript | 基于磁盘文件索引解析的词法提取 | | Python | 基于磁盘文件索引解析的词法提取 | | Rust、Java、C#、Ruby、PHP、Kotlin、Swift、Scala | 被报告为 `unsupported`——绝不会显示为零影响 | 只有第一方文件会进入图。支持处理 TypeScript `baseUrl` 和 `paths` 别名、目录 `index` 文件，以及解析为 `.ts` 源码的 ESM `.js` 说明符。`node_modules`、`vendor` 和构建输出永远不会被遍历。 遍历是确定性且有界的： | 边界 | 限制 | |---|---:| | 文件 | 20,000 | | 解析字节 | 512 MiB | | 图边数 | 1,000,000 | | 图深度 | 5 | | 工件大小 | 每个文件 32 MiB | 内置规则涵盖了类似密钥的添加以及高风险路径，包括身份验证、迁移、依赖清单、环境配置、API 和 CI 工作流。 **路线图：** 针对其余语言的适配器、SARIF 输出、Ed25519/Sigstore 签名、测试到更改的映射，以及版本化的成本表。 ## 隐私与信任模型 - 原生会话工件会被摘要和哈希处理；原始 prompt 永远不会被复制到报告中。 - 类似密钥的值会在 patch 持久化之前被移除。 - 路径、JSON/XML 记录、文件大小、图扩展和嵌套深度都是受限的。 - 报告会对不受信任的 Markdown 和 HTML 进行转义；HTML 报告不包含脚本和外部资产。 - SHA-256 检测捕获后的突变。它**不会**确立来源真实性、作者身份、完整性、正确性或安全性。 发布历史请查阅[更新日志](CHANGELOG.md)。[基础归档审查](docs/archive-review.md)记录了从提供的项目归档中重用、强化、推迟和排除了哪些内容。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。运行时有意仅依赖 Go 标准库——引入新依赖需要经过许可和供应链审查。 ## 许可证 MIT © AgentProof 贡献者。请参阅 [LICENSE](LICENSE) 和[第三方声明](THIRD_PARTY_NOTICES.md)。

标签：AI辅助编程, EVTX分析, SOC Prime, 代码审查, 完整性校验, 开发工具, 文档结构分析, 日志审计, 网络安全研究