guillaumevele/agent-proof-kit

# Agent Proof Kit [](https://github.com/guillaumevele/agent-proof-kit/actions/workflows/verify.yml) [](https://www.npmjs.com/package/agent-proof-kit) [](LICENSE) 面向 AI agent 的确定性发布门控与原始字节写入收据。该套件 验证公共 agent 运行合约，评估安全性与来源 不变量，扫描仓库表面，导出 SARIF，生成证明包， 并通过 ByteFence 调解严格声明的文件编辑。 其评估路径设计得极其狭窄：无需提供商账户、API key 或 模型调用，且安装后无网络访问。安装过程本身可能会 获取 lockfile 锁定的依赖项。ByteFence 读取本地项目字节，但 其公共收据省略了源片段与 prompt。 成熟度：ByteFence 发布于 v0.5.0 并由确定性的本地和 CI 测试支持。工作流徽章是矩阵状态的实时来源。本项目已针对 合成测试夹具进行了测试，并未声称为已在生产环境中得到验证。 ## 安装说明 ``` npm install -g agent-proof-kit # provides `agent-proof` and `agent-proof-mcp` # 或不安装直接运行： npx --yes --package agent-proof-kit agent-proof verify --input examples/synthetic-agent-run.json --policy policies/default-policy.json ``` ByteFence 需要 Node.js 22 或更高版本。发布矩阵覆盖 Node.js 22 和 24 发布线。 ## 30 秒概览 ``` npm run verify node bin/agent-proof.js verify --input examples/synthetic-agent-run.json --policy policies/default-policy.json node bin/agent-proof.js diff --base examples/synthetic-agent-run.json --candidate examples/synthetic-agent-run-regression.json --policy policies/default-policy.json node bin/agent-proof.js verify --input examples/synthetic-agent-run-regression.json --policy policies/default-policy.json --format sarif node bin/agent-proof.js export --from langgraph-stream --input examples/adapters/langgraph-stream.json --redact-terms internal-codename --out agent-run.synthetic.json npm run test:bytefence npm run corpus:verify ``` 预期输出： ``` PASS score=100 findings=0 run=demo-agent-run-001 FAIL scoreDelta=-40 newFindings=2 ``` ## 30 秒了解 ByteFence ByteFence 是针对单次唯一 `exactReplace` 的事务边界。它从 原始原像派生出唯一授权的候选对象，拒绝未声明的字节 更改，在协同锁下重新检查原像，通过 同目录下的独占临时文件进行提交，并发出关联的 preflight/postApply 收据。 ``` npm run test:bytefence npm run bytefence:reproduce-vibe ``` 检入的证据包含七个对抗性案例，一个原始字节匹配器 拒绝了 100,000 个 seeded 的超出范围的突变且零错误放行，1,000 个 seeded 的合法编辑通过了完整的评估器且零错误拦截， 双进程过期基线序列化，以及在 重命名前后的崩溃故障点。在 100,000 个案例的测试中，完整的评估器还会每 512 次迭代进行一次抽样。可选的复现过程通过已安装的 Mistral Vibe 代码执行混合 EOL 行为，而无需调用模型。 从可执行的 [check/apply/verify 快速入门](docs/integrations/bytefence.md) 开始， 然后查看 [Mistral Vibe 2.19.1 适配器](adapters/vibe/README.md) 和 [批准的威胁模型](docs/rfc-bytefence.md)。 ## 它证明了什么 - CLI 可以重放版本化的合成 agent 运行。 - agent 运行和策略文件符合文档化的 JSON 合约。 - 除非存在明确批准，否则高风险操作将被阻止。 - 公共声明必须链接到证据。 - 未知的操作类型会失败关闭，直到策略对它们进行分类。 - 超大且未扫描的文件会导致公共表面扫描失败，而不是被静默跳过。 - 生成的 Markdown、SARIF 和 JSON 证明包是可重现的，并已在 CI 中检入。 - LangGraph、CrewAI 和 AutoGen 跟踪形状可以在发布前转换为合成测试夹具。 - 证明包可以通过规范的摘要和可选的 RSA 签名进行证明。 - 每个公共门控都映射到实现文件、验证路径和生成的证明。 - ByteFence preflight 收据可以从保留的 原始输入、意图和策略中独立重新计算 (`CORE_PROVEN`)。 - 成功的 ByteFence apply 会报告一个协同的 broker 重新检查并 提交了确切的候选对象，然后发出一个事务收据，其 声明级别为 `MEDIATED_PROVEN`。 - Apply 和裸收据验证默认保持有效的 `CORE_PROVEN`， 且 `mediationEnvironmentTrusted: false`。接受调解级别需要对 生产者和部署边界分别建立信任。 - 收据验证将 `publicProfileConformant` 与核心 完整性分开报告，因此未经审查的 in-toto 扩展不会被误认为是安全的 公共产物。 ## 它不主张什么 - 它不证明模型、供应商、用户工作流或生产系统。 - 它不能替代威胁建模、红队工作或人工审查。 - 它不对模型质量进行基准测试。 - 它不需要或检查私有仓库。 - ByteFence 不排除非协作的写入器，例如 Bash、IDE、 另一个 MCP server 或恶意的同用户进程。 - ByteFence 不是通用的文件系统比较并交换（compare-and-swap），且不主张 网络文件系统或断电保证。 ## 命令 | 命令 | 用途 | | --- | --- | | `npm run test:unit` | 针对 strategy 评估和公共表面扫描的单元测试。 | | `npm run test:schema` | 针对 agent 运行和策略的合约验证测试。 | | `npm run test:bytefence` | 原始字节合约、收据、属性、语料库、路径、事务、并发和崩溃测试。 | | `npm run test:vibe-adapter` | 针对版本锁定的 Mistral Vibe 项目工具配置文件的 Python 测试。 | | `npm run test:adapter` | JSONL 跟踪规范化测试。 | | `npm run test:diff` | 基线与候选对象的回归测试。 | | `npm run test:sarif` | SARIF 2.1.0 导出测试。 | | `npm run test:cli` | 在安全和不安全测试夹具上的端到端 CLI 行为测试。 | | `npm run test:mcp` | MCP stdio 工作流测试。 | | `npm run test:signature` | 证明包摘要和 RSA 签名测试。 | | `npm run test:dashboard` | 本地 HTML dashboard 渲染测试。 | | `npm run test:pack` | 针对完整已发布包表面的 `npm pack` 冒烟测试。 | | `npm run scan:leaks` | 针对密钥形状的值和已配置私有术语的仓库扫描。 | | `npm run report:generate` | 重新生成 `docs/generated/sample-agent-proof-report.md`。 | | `npm run report:verify` | 当生成的报告过期时失败。 | | `npm run artifacts:generate` | 重新生成 JSON、SARIF 和证明包产物。 | | `npm run artifacts:verify` | 验证生成的机器产物、新鲜度和本地路径规范，而不对其进行重写。 | | `npm run coverage:generate` | 重新生成门控覆盖矩阵。 | | `npm run coverage:verify` | 当门控覆盖矩阵过期或引用缺失文件时失败。 | | `npm run corpus:verify` | 在内存中重建 ByteFence 语料库，并检查每个记录的字节长度和摘要。 | | `npm run bytefence:benchmark` | 运行信息性的本地原始字节评估器基准测试，并打印计时摘要。 | | `npm run bytefence:reproduce-vibe` | 可选地在临时副本上通过已安装的 Vibe 代码复现混合 EOL 候选对象。 | | `npm run refresh` | 重新生成所有检入的生成产物。 | | `npm run verify` | 运行完整的 Node 发布门控；锁定的 Vibe 合约在 CI 中单独运行。 | ## 示例 ``` node bin/agent-proof.js verify \ --input examples/synthetic-agent-run.json \ --policy policies/default-policy.json \ --format markdown ``` 生成的证明：[docs/generated/sample-agent-proof-report.md](docs/generated/sample-agent-proof-report.md) 机器可读的产物： - [证明包 JSON](docs/generated/proof-bundle.json) - [SARIF 导出](docs/generated/sample-agent-proof.sarif) - [规范化的 JSONL 跟踪](docs/generated/normalized-agent-run.json) - [回归差异](docs/generated/sample-agent-run-diff.json) - [门控覆盖矩阵](docs/generated/gate-coverage.md) - [证明包证明](docs/generated/proof-bundle.attestation.json) - [本地证明 dashboard](docs/generated/proof-dashboard.html) ## GitHub Action ``` - uses: guillaumevele/agent-proof-kit@v0.5.0 with: input: examples/synthetic-agent-run.json policy: policies/default-policy.json report: agent-proof-report.md sarif: agent-proof-results.sarif ``` 复合 action 会在 action 检出内部安装其锁定的生产依赖项，并禁用生命周期脚本。使用者需要 Node.js 22 或 更高版本，但不需要首先为 Agent Proof Kit 运行 `npm install`。 请参阅 [docs/integrations/github-action.md](docs/integrations/github-action.md)。 ## MCP Server Agent Proof Kit 还附带了一个本地 stdio MCP server，以便助手无需记忆 CLI flag 即可运行发布门控： ``` { "mcpServers": { "agent-proof-kit": { "command": "npx", "args": ["--yes", "--package", "agent-proof-kit", "agent-proof-mcp"], "env": { "AGENT_PROOF_ROOT": "/path/to/repository" } } } } ``` 可用的 MCP 工具涵盖 ByteFence 只读检查和调解 apply、 状态、策略编译、跟踪导出、运行验证、公共表面扫描、 运行 diff、证明包创建、证明、dashboard 渲染和 生成产物读取。具有变更能力的 `bytefence_apply` 工具是 破坏性的、非幂等的，并且绝不会在不确定的状态下重试。请参阅 [docs/integrations/mcp.md](docs/integrations/mcp.md)。 上面的 `npx` 配置会解析最新发布的包。当需要不可变的 MCP 依赖 版本时，请将 `agent-proof-kit` 替换为 `agent-proof-kit@0.5.0`。 ## 策略表面 默认策略检查： - 合成测试夹具标记 - schema 验证 - 决策跟踪存在性 - 最终输出的声明声明 - 声明的证据覆盖 - 高风险操作遏制 - 未知操作类型的失败关闭 - 密钥形状的值 - 未扫描文件检测 - 可选的私有术语列表 策略是 JSON 文件，因此团队无需更改 CLI 即可调整风险类别、评分阈值和私有术语。 捆绑的策略包： - [default-policy.json](policies/default-policy.json) - [open-source-policy.json](policies/open-source-policy.json) - [strict-corporate-policy.json](policies/strict-corporate-policy.json) - [high-stakes-policy.json](policies/high-stakes-policy.json) 请参阅 [docs/policy-packs.md](docs/policy-packs.md)。 也支持 YAML 策略 DSL： ``` node bin/agent-proof.js compile-policy --input examples/policies/strict-corporate-policy.yaml node bin/agent-proof.js verify --input examples/synthetic-agent-run.json --policy examples/policies/strict-corporate-policy.yaml ``` ## 公共边界 所有检入的示例和生成的产物都是合成的，并使用保留域，例如 `example.com`。对于下游仓库，请将项目特定的名称添加到 `privateTerms`；默认扫描器会捕获密钥形状的值、env/private-key 路径和已配置的私有术语；它不会自动检测未知的内部代号。 请参阅 [docs/public-boundary.md](docs/public-boundary.md) 和 [docs/threat-model.md](docs/threat-model.md)。 ## 证明 证明包可以进行哈希处理，并可选择使用 RSA key 进行签名： ``` node bin/agent-proof.js sign-bundle --bundle docs/generated/proof-bundle.json --out proof-bundle.attestation.json node bin/agent-proof.js verify-bundle-signature --bundle docs/generated/proof-bundle.json --signature proof-bundle.attestation.json ``` 请参阅 [docs/signatures.md](docs/signatures.md)。 ## 本地 Dashboard ``` node bin/agent-proof.js dashboard \ --bundle docs/generated/proof-bundle.json \ --coverage docs/generated/gate-coverage.md \ --attestation docs/generated/proof-bundle.attestation.json \ --out proof-dashboard.html ``` 请参阅 [docs/dashboard.md](docs/dashboard.md)。 ## 项目映射 ``` action.yml reusable composite GitHub Action CHANGELOG.md tagged history and 0.5.0 release notes bin/agent-proof.js CLI entry point bin/agent-proof-mcp.js local stdio MCP server schemas/ public JSON contracts src/core/evaluate-agent-run.js deterministic policy engine src/core/diff-agent-runs.js baseline/candidate regression diff src/core/normalize-jsonl.js synthetic JSONL trace adapter src/core/trace-export.js LangGraph, CrewAI, AutoGen and JSONL fixture export src/core/policy-loader.js JSON/YAML policy loader and DSL compiler src/core/proof-signature.js canonical proof-bundle digest and signature helpers src/core/public-safety-scan.js repository surface scanner src/core/bytefence-evaluate.js raw-byte preflight evaluator src/core/bytefence-apply.js mediated lock/recheck/rename transaction src/core/bytefence-receipt.js preflight and postApply receipt verification src/report/ Markdown, SARIF, proof-bundle and dashboard renderers examples/bytefence/ deterministic adversarial raw-byte corpus adapters/vibe/ version-pinned Mistral Vibe 2.19.1 profile examples/adapters/ synthetic framework trace shapes policies/ JSON policy gates tests/ unit, CLI, MCP, schema, adapter, diff, SARIF, signature, dashboard and pack tests docs/generated/ reproducible proof artifacts docs/threat-model.md public threat model and release rule docs/signatures.md proof bundle digest and signature workflow docs/dashboard.md local HTML dashboard workflow docs/integrations/bytefence.md ByteFence quickstart, guarantees and evidence ``` ## ByteFence 0.5.0 - ByteFence 只读检查、调解 apply 和独立的收据验证。 - 版本化的意图、策略和 in-toto 形状的 Statement 合约。 - 公共对抗性语料库和可选的 Mistral Vibe 混合 EOL 复现。 - 显式的 Mistral Vibe 2.19.1 和供应商中立的 MCP 集成。 - Node.js 22/24 合约和已配置的 Ubuntu/macOS/Windows ByteFence 矩阵。 请参阅 [changelog](CHANGELOG.md) 获取完整的 0.5.0 清单和 历史标签。上述工作流徽章仍然是当前远程矩阵的 事实来源。 ## 路线图 - OpenTelemetry 形状的跟踪适配器。 - GitHub pull-request 评论、状态徽章和必选检查示例。 - 策略比较器和共享测试夹具注册表。 - 在提议上游 ByteFence 谓词之前，提供第二个独立复现的突变工具链和外部采用者 反馈。 - 渐进式 TypeScript 迁移和大型跟踪基准测试。 ## 许可证 MIT

标签：DNS 反向解析, GNU通用公共许可证, MCP, MITM代理, Node.js, 代码安全, 多模态安全, 安全防护, 完整性校验, 文档安全, 文档结构分析, 漏洞枚举, 自定义脚本