assay

Assay

面向特权 MCP 工具操作的开放、可重新计算的证据规范。
Assay 会记录特权工具调用作出了什么决定、观察到了什么，以及哪些内容仍未得到证明，让审核者可以离线重放相关声明，而不必相信 Agent 对自身行为的描述。在强制执行模式下，针对经由代理转发的 MCP tools/call 请求，代理门控机制具有确定性并在失败时默认拒绝；执行强制策略的代理是参考生成器，而非契约本身。在受支持的 Linux 主机上，可选的 eBPF/LSM 插桩会补充内核级观察数据。原生支持 CI、无需后端，且设计上有界。

快速开始 · 工作原理 · 查看效果 · MCP 示例 · OWASP MCP Top 10 · 讨论

---

Agent 通过 MCP 获得了真正的工具访问能力，同时也带来了工具投毒、恶意替换和混淆代理 OAuth 问题。Assay 位于工具调用边界，依次完成三件事。

一条黄金路径：发布版本锁定的 Agent 操作流程记录了九个由 CLI/MCP 驱动的步骤及其退出码/stdout 契约。其受保护操作的测试夹具位于 examples/privileged-action-gate/。

强制执行、提供证明、保持诚实

• **强制执行。**在强制执行模式下，门控机制会在转发前决定经由它路由的 tools/call 请求，并给出每项允许或拒绝的确切原因。在受支持的 Linux 主机上，独立控制措施还包括 cgroup eBPF IPv4/TCP 连接过滤（其钩子错误路径会允许连接）以及 Landlock TCP 连接端口允许列表。assay sandbox --enforce 会拒绝不可用的后端或冲突的文件系统策略，除非明确指定 --allow-audit-fallback。--enforce-net 需要同时启用 --enforce；即使启用了审计回退，主动的 Landlock 网络强制执行也会拒绝无法表示为 TCP 端口允许列表的策略。
• **提供证明。**已配置的生成器可以记录决策和有界观察数据，并将其导出为可离线验证、防篡改的证据包。特权操作流程会携带判定结果、调用前的建立过程以及声明与观察结果的一致性信息，供 CI 审核，无需托管后端。基本的 assay mcp wrap 不会自动创建证据包；请启用所需的记录和导出步骤。
• **保持诚实。**Trust Basis 会将受支持的声明分类为 verified、self_reported、inferred 或 absent；其门控机制会检查声明中界定的边界。工具返回“success”只是提供方的断言，绝非证明。Assay 不提供单一的安全评分；依赖任何产物前，请先了解其来源、覆盖范围和非声明内容。

快速入门

# Fast path: release installer for Linux and macOS.
curl -fsSL https://getassay.dev/install.sh | sh

# Confirm the command resolves; if setup fails, run `assay doctor`.
assay --version

# Source-build alternative (requires Rust):
cargo install assay-cli --version 6.17.0 --locked

python3 examples/mcp-quickstart/run.py

对于 v6.17.0，请在源码检出目录或解压后的已发布 CLI 压缩包中运行最后一条命令。 安装程序仅包含二进制文件，不包含受限的快速入门资源。线上 getassay.dev 安装程序会在解压前，使用已发布的 SHA-256 校验和旁文件验证所选压缩包。 设置 ASSAY_REQUIRE_PROVENANCE=1 可进一步要求 GitHub 工件来源证明； 默认情况下会报告 provenance_not_requested，严格验证成功时会报告 provenance_verified。 校验和只能证明文件字节与已发布的旁文件一致，不能证明产出者身份。来源证明 标识源码和构建信息，不代表运行时安全或语义正确。

捕获的运行器输出（捆绑的本地模拟工具不会执行任何外部操作）：

assay quickstart: PASS
mcp_requests=initialize,tools/list,tools/call
decision=allow tool=read_file
decision_artifact=.assay/quickstart/decisions.ndjson
non_claim=forwarded_to_local_mock_only

已发布版本包含的内容：

• Claude Code 和 Cursor 已提供静态项目清单；Codex 使用 编辑器 MCP 配置指南中说明的等效 TOML 条目。清单存在并不能证明宿主能够发现它。assay mcp config-path 仅支持 Claude Desktop 和 Cursor。
• 已发布的 v6.17.0 CLI 压缩包支持 Linux x86_64/arm64、macOS x86_64/arm64 和 Windows x86_64。Python wheel 支持 macOS x86_64/arm64 和 Linux x86_64 上的 CPython 3.12、3.13 和 3.14；不承诺支持其他解释器和平台。
• 已发布的 assay-mcp-server 压缩包支持 Linux x86_64/arm64。也会发布 MCPB 和 server.json 包描述文件；这些文件存在并不能证明宿主能够发现它们。
• CI：GitHub Action。核心工作流无需托管后端或 API 密钥。如果你刚接触威胁模型，请参阅 OWASP MCP Top 10 映射，其中针对每项风险说明了 Assay 的覆盖范围及其明确不覆盖的部分。

发布内容

输出	内容
策略关卡	assay mcp wrap — 在工具运行前以确定性方式允许或拒绝，并说明原因。
证据包	可离线验证、防篡改的审计与回放归档。
信任依据 / 信任卡片	规范的 trust-basis.json（受限的声明分类），以及便于审阅的 trustcard.{json,md,html}。
外部回执	将评估结果、运行时决策和模型清单作为受限回执提供，并附带 JSON Schema 契约。
工具决策日志	对于已处理的已知工具调用，assay-mcp-server stdio 服务会在日志筛选器启用时发出 info 级别的 tool_decision 事件；decision 包含一个 JSON 编码的观测决策条目，其中包含投影后的目标字段。
SARIF / CI	GitHub Action、Security 选项卡集成、PR 上的策略关卡。
证明文件	将证据包签名为 DSSE 封装的 in-toto v1 Statement，并使用 evidence-bundle/v1 谓词。

  Agent ──► Assay ──► MCP Server
              ├─ ✅ ALLOW / ❌ DENY  (policy, with reason)
              ├─► 📋 Evidence bundle (offline-verifiable)
              └─► 📊 Trust Basis → Trust Card → SARIF / CI

当前版本：v6.17.0。已发布行为以 CHANGELOG.md 和发行说明为准；标签发布后合并的更改属于 Unreleased，而 crates.io 发布状态与合并状态相互独立。 发布定义和支持承诺：docs/LAUNCH.md。

这适合我吗？

适合：如果你已有评估输出、运行时决策、清单工件或 MCP 工具调用测试，并且希望获得一个小巧、便于审阅的 CI 工件，而不是仪表板——提供的是有边界的可审计性，而非单一信任徽章。

暂不适合：如果你需要 Assay 替你判断模型是否正确、希望将托管仪表板作为产品，或需要合规声明而非有边界的证据范围。Assay 不是信任评分引擎、通用评估仪表板或托管式可观测性产品——请参阅它是什么，以及它不是什么。

查看实际效果

Agent 通过强制执行代理尝试执行一项特权操作 — github.add_deploy_key，代理会在转发前针对每次调用做出决定；此演示离线运行于本地模拟环境（不使用真实凭据）：

cd examples/privileged-action-gate && ./run.sh

拒绝是故障时默认拒绝的谨慎措施，而非对意图的判定；允许则表示决定转发，绝不证明该操作已发生。声明与观察到的行为之间的一致性会记录在判定旁边，绝不作为门禁条件。完整演示：特权操作门禁。

选择你的路径

你拥有	可获得内容	从这里开始
CI 评估中的 Promptfoo JSONL	评估结果回执 + 已验证的包 + Trust Basis 差异	Promptfoo JSONL
OpenFeature EvaluationDetails	决策回执 + 已验证的包	OpenFeature
CycloneDX ML-BOM 模型组件	清单回执 + 已验证的包	CycloneDX ML-BOM
MCP 工具调用	允许/拒绝审计跟踪 + 观察行为证据	MCP 快速入门
GitHub PR 门禁	Trust Basis 差异、门禁状态、可用于 SARIF/JUnit 的输出	CI 指南
Runner 归档 / 覆盖率注释	覆盖率描述符 + 声明类别单元 + 声明与观察结果核验	覆盖率诚实性演练

工作流保持精简：导入或记录有界结果，将其打包并验证，编译 trust-basis.json，再对 Trust Basis 差异执行门禁。Assay 不会将上游工具变成事实来源；它会让证据边界清晰可查。对于特权工具操作，MCP 代理会将每次 tools/call 记录为结构化的工具决策面，如实呈现断言与验证之间的界限。

策略很简单

version: "2.0"
name: "my-policy"
tools:
  allow: ["read_file", "list_dir"]
  deny: ["exec", "shell", "write_file"]
schemas:
  read_file:
    type: object
    properties:
      path: { type: string, pattern: "^/app/.*" }
    required: ["path"]

assay init --from-trace trace.jsonl 会生成跟踪生成流程使用的运行时观察策略（files、network 和 processes）；它不是 MCP 授权策略。使用 assay policy migrate 迁移旧版 MCP constraints: 策略。参见策略文件。

为什么选择 Assay

规范证据	Assay 的证据模型是稳定契约；OpenTelemetry 和协议适配器（ACP / A2A 投影配置文件 / UCP）会映射到该模型。
确定性	策略门禁使用明确规则；其决定取决于请求、策略和适用的会话状态。这并不意味着实时评估器或外部影响具有确定性。
有界声明	明确区分已验证、可见和缺失 — 不采用评分优先的用户体验。
离线优先	核心强制执行和包验证不需要后端。
可核查的来源信息	源类别与覆盖率模型中的哪些部分何时交付，可通过 git log 查看为提交，而非需要你相信的声明 — 来源信息，并优先注明前人工作。

了解更多

• MCP 快速入门 · 编辑器 MCP 配方 — 在 Cursor / Claude Code / Codex 中强制执行策略的 MCP
• MCP 2025/2026 协议时代的对等性 — 固定的 resultType 和临时结果兼容性语料库
• 编码 Agent 治理 · OpenTelemetry 与 Langfuse — 已观测的运行 → 证据
• 证据回执实践 — Promptfoo / OpenFeature / CycloneDX 回执系列
• CI 指南 · 证据存储（S3 / B2 / MinIO）
• OWASP MCP Top 10 映射 · 安全实验
• 定位：ADR-033 · RFC-005

证据认识论、延迟与内部 Runner

信任声明采用明确的认识论，而非单一安全评分：verified（直接证据或离线验证）、self_reported（已发出但未经独立佐证）、inferred（有界且有文档记录的规则）、absent（没有可信证据）。Assay 不提供聚合信任评分，也不将 safe/unsafe 徽章作为主要输出 — 参见 ADR-033。

历史上的碎片化 IPI 实验结果标注日期为 2026-03-02，并注明提交 289a43ecc144，报告确定性集合的 p50 为 0.771ms / p95 为 1.913ms。该测试工具测量完整的本地模拟 tools/call 往返过程，包括 JSON-RPC 传输和工具响应。这些报告的计时并未单独测量策略决策开销，也不能证明当前版本或端到端模型的性能。

Assay-Runner 是一个内部／实验性的测量运行子系统，位于委托式 Linux/eBPF 验收路径之后。其 crate 包含在工作区发布流程中，以便依赖包能够解析它们；发布并不意味着 Runner 是独立产品，也不代表其 API 有单独的稳定性承诺。

## 生态

用于证据生成、验证和可审查性的相关项目；每个项目都有自己的接口和范围：

• assay-action — GitHub Action：验证证据包、PR 摘要和 SARIF（Marketplace）。
• Assay-Harness — 构建在规范证据制品之上的配方、门禁和报告层。
• observed-effect-v0 — 有界观测效果证据记录及其中立载体（in-toto、SCITT、MCP evidenceRef）的实践示例。
• gateway-evidence-replay — 用于网关路径证据包的确定性离线重放验证器。
• RGE-Bench — 用于评审证据可审查性的符合性工具包，单独维护，并受其自身的机器检查中立性防护机制约束。此处的复现仅针对摘要，且不会沿用：v1 的 71 向量摘要 sha256:e769822bc6c9e31085da7b1a17b163b9747fe0d04314fbb8685d4e612087c7cb 和历史 v2 摘要 sha256:ba0e3795d75c788fa48313ab462493f22d78759851d1b3275d8117051bb22fd0（95 个向量）各有一项由另一位作者在不同技术栈上报告的独立实现。JM-Lab 于 2026-08-24 报告了 v2 的 95/95 复现，其依据是契约文本和作者提供的输入，且未读取 expected。这两项复现均不能转用于当前包含 104 个向量的 v3 候选摘要 sha256:93f8ae9654eb5a16dee28d882087669cae5183e02e116ba1e8071a30594cfb6a，该摘要在记录中列为尚未复现。请参阅其 REPRODUCTIONS.md。

开放配置：privileged-mcp-action/v0

privileged-mcp-action/v0 是一份针对现有证据记录的组合与验证契约：特权 MCP 工具调用作出了什么决定、观测到了什么效果，以及哪些内容仍未得到证明。它不添加新信封，也不提供综合判定。

它附带一个 14 向量符合性语料库 （5 个接受、9 个拒绝），其摘要为候选摘要：在非作者实现者仅根据规范文本推导出预期结果之前，不会称其为已复现。

**该复现仍在开放进行，诚邀参与： #1840。**任何语言、任何技术栈均可。邀请中列明了当前摘要所对应的确切提交。[ 清洁室协议提供不透明且经过证明的输入包、一条命令即可执行的评分操作，以及实现报告模板，但不提供验证器逻辑或预期结果。[ 语料库 README说明了作者身份边界和声明上限。

贡献

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

请参阅 CONTRIBUTING.md 和 GitHub Discussions。

许可证

MIT