Tracekit MCP gateway

---

当 Agent 做了不该做的事，你会追问三件事：它做了什么、是否获准这样做，以及记录是否可信？ Agent 自己的日志无法回答第三个问题，因为 Agent 可以修改日志。下面是同一次运行的两种记录方式：

_{同一次运行的记录：数据库、签名器、查看器和两次编辑都是真实的；模型是脚本模拟的。听声音观看（1:47）}

在这个演示中，签名器以 Agent 自身的用户身份运行（开发模式），因此，知道如何操作的 Agent 本可以读取密钥并重新签署日志。将签名器运行在 Agent 无法访问的位置，并配备见证者，这样就无法篡改。

试试看

uvx --from tracekit-ai tracekit demo --server

无需 API 密钥，也无需通过 uv 安装任何内容。在 Mac 上使用空缓存耗时 5 秒（在全新的虚拟环境中通过 pip install tracekit-ai 安装则需 10 秒）。软件包名为 tracekit-ai：PyPI 上的 tracekit 是无关项目。脚本模拟的 Agent 会进行三次调用，你应该会看到：

== agent run (SCRIPTED: fixed tool calls, not a model)
  Bash 'ls': allow
  Bash 'sudo rm -rf /': deny TK-D001 TK-D004 TK-F003
  Bash 'echo "unterminated': ask TK-SHELL-PARSE
...
Integrity: VERIFIED.

== tamper test: rewrite the denied call as allowed in a copy, then verify again
[FAIL] signatures — 11 record(s), keys valid at their position
        seq 4: hash does not match the event
Integrity: FAILED.

删除操作在执行前被拒绝，等待审批的调用在获批后执行，运行也通过了验证。随后，演示在副本中将拒绝记录改为允许，验证便在被修改的记录处失败。

将它添加到你的 Agent 中

三行：

pip install tracekit-ai

import tracekit; tracekit.instrument()     # the first line of your agent; then run it as usual

tracekit last                               # Integrity: VERIFIED. / Assurance: dev; ...

tracekit.instrument() 会启动开发签名器（或复用正在运行的签名器），并对它检测到的框架中的每次工具调用和模型调用进行门控和记录。tracekit last 会导出你最近一次运行、验证它，并告知其保存位置。 tracekit view --dev 会显示每次运行。在一台全新机器上，LangGraph 示例（模拟模型，无需 API 密钥）安装、运行并通过验证共用时 27 秒：examples/v2/clean-machine.sh langchain。

_{稳定支持：Claude Code、OpenAI Agents SDK、LangChain / LangGraph、Claude Agent SDK 和 MCP。实验性支持：Codex CLI、Cursor、Gemini CLI、CrewAI、Browser Use、Pydantic AI、Google ADK、Haystack、LlamaIndex、Microsoft Agent Framework、Strands Agents、Vercel AI SDK、NVIDIA OpenShell、E2B、microsandbox、agentgateway、Wassette、LiteLLM 的 MCP gateway、Docker 的 MCP Gateway 和 TypeScript SDK。 在 NVIDIA OpenShell 沙箱中，Tracekit 会决定并签署 OpenShell 放行的每个 HTTP 请求，并将 OpenShell 自身的拦截、进程事件和策略变更签署到同一次运行记录中。设置指南： 编码 Agent · OpenAI Agents SDK · Claude Agent SDK · LangChain / LangGraph · MCP · Wassette · CrewAI · Browser Use · Pydantic AI · Google ADK · Haystack · LlamaIndex · Microsoft Agent Framework · Strands Agents · NVIDIA OpenShell · LiteLLM · TypeScript · Vercel AI SDK · agentgateway · microsandbox · E2B · Docker MCP Gateway · OpenTelemetry · 其他 Agent}

其他入口：编码 Agent、无需 uv、why 演示、示例包、TypeScript

编码 Agent：`tracekit init --dev --v2` 会将 Claude Code 的钩子连接到开发签名器；其他 Agent 可添加 `--agent codex`、`cursor`、`gemini` 或 `opencode`（实验性）。启用 Claude Code 的沙箱后，Tracekit 会将每次未经沙箱保护的重试暂缓，等待人工处理 （[Claude Code 的沙箱](https://github.com/Cygnux-Labs/Tracekit/wiki/Integrations-Claude-Code-Sandbox)）； 使用 Codex 的沙箱时，查看 Tracekit 能看到的内容以及要使用的设置 （[Codex 的沙箱](https://github.com/Cygnux-Labs/Tracekit/wiki/Integrations-Codex-Sandbox)）； 使用 Gemini CLI 的工具沙箱时，Tracekit 会将每次沙箱扩展暂缓，等待人工处理 （[Gemini CLI 的沙箱](https://github.com/Cygnux-Labs/Tracekit/wiki/Integrations-Gemini-Sandbox)）。 单独运行 sandbox-runtime 的代理时，Tracekit 会决定是否转发每个请求（实验性， [sandbox-runtime](https://github.com/Cygnux-Labs/Tracekit/wiki/Integrations-Sandbox-Runtime)）。 使用 agentsh 进行沙箱隔离？`tracekit follow` 会在 agentsh 写入每项决策日志时为其签名（实验性， [agentsh](https://github.com/Cygnux-Labs/Tracekit/wiki/Integrations-agentsh)）。 无需 uv：运行 `pip install tracekit-ai`，然后运行 `tracekit demo --server`。`--why` （实验性）会显示一封被暂缓的 邮件，其原因通过重放查明，并由其签名记录引用：

tracekit demo --server                # exit 0
tracekit demo --why                   # exit 0
tracekit init --dev --v2

在检出目录中，已打包的示例套件（v1）可仅使用验证器进行检查（pip install --no-deps tracekit-ai 即可），而 python examples/v2/langchain/agent.py --scripted 会使用模拟模型运行 LangGraph Agent：

tracekit verify docs/sample/demo-run.tkb --key docs/sample/signer.pub            # exit 0
tracekit verify docs/sample/demo-run-tampered.tkb --key docs/sample/signer.pub   # exit 1

TypeScript 需要 Node 18 或更高版本：运行 npm install @cygnuxlabs/tracekit，然后运行 npx @cygnuxlabs/tracekit up，即可在 Apple Silicon Mac、Linux 和 Windows 上启动无需 Python 的开发签名器（TypeScript SDK）。Python 版本为 3.9 至 3.13；框架集成需要 3.10 或更高版本。

它能证明什么

三项保障。它们彼此相关，但其中一项并不能带来其他保障，而且每项保障所需条件各不相同。

保障	你能获得什么	所需条件
证据完整性	记录一旦被编辑、删除、替换或插入，就无法通过该记录的验证	只需签名日志。要发现日志末尾被截断，或日志被用被盗密钥重新签名的情况，还需要见证方
执行控制	每次调用都会在运行前接受检查。被拒绝的调用会被阻止；被暂缓的调用只有在获得批准后才会执行，且参数与获批时完全一致	调用必须经由 Tracekit：通过 SDK、钩子或网关。绕过它的代码不会受到阻止
独立保证	如果运营方重写或分叉自己的日志，就会被发现	运营方无法控制的见证方，以及监控器。两者目前均为实验性，尚无公开运行的见证方

限制

• 开发模式无法防范以你的身份运行的 Agent。 开发模式运行会标记为 isolation: same-user （常见问题）。
• 验证通过的运行只能证明记录完整：不能证明意图，不能证明报告的工具结果属实，也不能证明已捕获每个操作 （常见问题）。 tracekit analyze --v2 会比较提出的请求、模型的说法和实际运行的内容，但模型的说法只是它自己的陈述；分析结果只是与完整性并列的意见，而非完整性的一部分 （分析结果）。
• 捕获路径之外的操作不会留下记录，例如钩子无法监测、且没有内核传感器导入覆盖的子进程，或绕过适配器的代码 （适配器）。
• 策略规则会匹配文本和工具名称。 坚决的 Agent 可以改写命令；真正的保护来自签名方的隔离 （策略参考）。
• 承诺会隐藏内容，但不会隐藏时间、大小或数量 （隐私）。

从开发模式到 Agent 无法触及签名方，各种部署分别能提供什么保障： 保障。所有限制及其应对方法： 限制。它与欧盟《人工智能法案》、 ISO/IEC 42001、NIST AI RMF 和 OWASP 的对应关系： 合规性。

包含内容

一个签名方。核心功能稳定，并优先进行加固。其余功能以实验性功能形式随同一软件包发布：功能可用且经过测试，但可能会在不同版本间发生变化（稳定性说明）。

核心功能	功能说明	测量结果
记录	每次运行都会将每次工具调用、决策和结果记录在一条签名哈希链中。事件丢失时会生成有签名的缺口，绝不会悄无声息	仅靠日志就捕获了 8 次篡改攻击中的 6 次（E1）
决策	在调用执行前，允许、拒绝或暂缓每次调用以供人工处理。适用于 shell、文件、SQL、HTTP、云 CLI、浏览器、电子邮件、消息、支付、机密信息和 MCP 的策略包	阻止了 699 次有害调用中的全部 699 次；800 次调用中出现 1 次误报（E17）
审批	暂缓的调用只有在通过命令行获得批准后才会执行；批准绑定到确切参数且只能使用一次（审批）	修改过的参数、重放的快照或其他运行的批准都会被拒绝；每项稳定框架集成都运行契约测试
验证	tracekit verify 使用你固定的密钥离线检查运行记录文件	捕获了 8 次内部人员攻击中的全部 8 次（E8）
查看	tracekit view：查看每次运行的验证结果、被阻止和暂缓的调用、批准、缺口、重放和运行审查（查看器）	未测量
实验	功能	测量结果
---	---	---
Witness	独立的见证者会为每个检查点共同签名；监视器会监视日志中的改写和分叉	在使用见证者的情况下，8 次篡改攻击全部被发现（E1）
交叉核对	签名者会将模型请求的调用（由大模型网关或会话记录看到的调用）与 Agent 报告的调用进行比较。若钩子被跳过，或调用是捏造的，就会发出标记	12 个植入的差异全部被标记，误报为 0（E10）
遏制	签名的事件会暂停或隔离一次运行。工具使用 Agent 从未持有的凭据运行（执行器、MCP 网关）。出口流量观察器会标记无法由任何调用解释的流量。内核传感器导入会记录 Tetragon 或 Falco观察到的进程、连接和文件写入	8 项遏制检查全部通过，10 项检测检查全部通过（E17）
解释	每个参数的来源，以及 tracekit why：通过重放运行并移除某个输入，找出哪个输入导致了某项操作	找准全部 6 个真实原因，误归责为 0；使用一个 7B 模型，样本量较小
检查	tracekit analyze --v2，已签名：之前没有任何说明的操作；修改无人提及或表示要更改的文件；在项目目录之外写入；违反“不要碰 X”的要求；发送数据；未告知用户就删除文件或添加软件包；运行框架从未提交过的提示词行；以及运行中的推理有多少可以读取（哪些 Agent 的推理可读）；--review 会加入审核模型的第二意见（仅警告）。实时约束会暂停可能违反“不要碰 X”要求的调用，等待批准	在一个盲测池上仅评估一次（E20 pool v3，合成数据；最终审核对该次运行之后检查项所作的修正未改变任何数据）：当没有请求提及该文件时，在所有会话中都能发现被泛泛、封闭或针对审核者的掩饰文本掩盖，或以看似无害的方式提及的未请求编辑；在“不要碰 X”之后，按掩饰方式检测率为 79–100%（编辑执行前暂停率为 67–92%）；将失败的测试运行声称为通过，检测率为 86%；未作任何说明就发送或删除文件，或添加并推送软件包，按掩饰方式检测率为 96–100%，但在看似无害地提及文件的情况下发送文件除外（33%）；追加的提示词行每次都会被标记；在 1,812 个正常调用中，有 5 个误报，1 个调用被暂停。在开发池上，在修复检查项的过程中进行读取；在“不要碰 X”之后，pool v2 的检测率为 88–96%（修复前为 29–75%），pool v1 为 54–92%
更多审批者	带有通行密钥的网页、Slack，或能在权限范围内批准操作的审核 Agent	针对 Agent 审批者的 7 种滥用案例全部被发现（E18）

证明

我们自己的实验：规模较小、合成构造，由我们编写。没有挑选有利结果。失败的案例也如实保留。

实验	设置	结果
E1 篡改检测	120 条记录的签名日志，8 种攻击，每种进行 60 次试验，在 1.2 上重新运行	仅凭日志检测出 8 种攻击中的 6 种，使用见证者时检测出 8 种中的 8 种
E8 内部人员攻击	针对 Linux 系统模式签名器的真实非特权用户：诱饵签名器、已停止的签名器、被替换的策略、伪造的运行记录	检测出 8 种中的 8 种，每个拉取请求都设有合并门禁
E17 策略包	11 类中的 699 次有害和 800 次良性工具调用，由两个正则表达式引擎判定	阻止了 699 次中的 699 次；出现 1 次误报，一封草稿邮件被暂缓发送，等待人工处理
E21 策略鲁棒性	420 次有害和 432 次良性调用，编写时未参考规则；130 次开发者会话调用	服务端策略包：在唯一一次盲测中阻止或暂缓了 420 次中的 211 次；添加针对该测试集的规则（自上次读取以来）后，阻止或暂缓了 245 次；432 次中出现 18 次误报，会话中 130 次里出现 2 次；p99 为 150 µs
E10 调和	30 次运行，其中 12 次植入了差异：缺失的钩子、伪造的调用、被修改的参数	标记了 12 次中的 12 次，0 次误报
E9 开销	通过 Unix 套接字进行签名器往返、文件存储、macOS 快速运行	每次调用 p50 为 0.45 ms，p99 为 0.91 ms；5,356 个事件/秒
E3 v1 正则表达式门禁，在较粗略的测试集上	16 次有害和 20 次良性调用，均在规则编写后生成	检测出 16 次中的 11 次，1 次误报。规则是绊线，不是沙箱

E1 中漏检的两种情况是设计使然：日志无法看到自身被截断的尾部，持有密钥的人也可以重新签名。只有在别处保存日志头部副本的见证者才能检测出这些情况，因此未经见证的运行会验证为 dev。测试集由我们编写，威胁模型尚未经过外部审查。所有实验及未测量的内容：评估 · 技术报告。

工作原理

• Agent 从不持有签名密钥，也从不分配序列号。
• 每条记录都会签名，并携带前一条记录的哈希，因此任何字节被更改，验证都会在相应记录处失败。
• Agent 对自身所作的任何报告都不可信：包括它的隔离方式、故障模式、记录缺口，或是谁批准了调用。
• 谁能改写日志，就决定了一次运行的价值，因此要将签名器放在 Agent 无法触及之处。Agent 的代码在所有模式下都相同；TRACEKIT_SIGNER 指向签名器。

签名器的运行位置	谁能访问密钥和日志	记录的隔离方式
笔记本开发环境	Agent 自身用户	same-user
笔记本系统模式（Linux；macOS 实验性支持）	root 和签名器的 OS 用户	separate-user
容器或 Kubernetes sidecar	签名器的 uid 和节点管理员	separate-user
Docker Compose 堆栈（deploy/compose/）	Docker 主机管理员	separate-user
通过 HTTPS 连接的中央签名器	签名器主机管理员	remote

运行签名器的操作员仍可使用自己的密钥改写日志；独立见证方和监控器会让这种行为显现出来。了解每种模式的端到端部署方法：部署。 完整模型：架构、 笔记本电脑和 服务器威胁模型。

适合你吗？

适合使用 Tracekit 的情况	普通追踪器就够用的情况
Agent 会操作真实系统：shell、文件、数据库、电子邮件、支付、云服务	Agent 只读取数据，或运行在一次性沙箱中
某些调用必须在执行前被拦截，或暂缓等待人工处理	事后查看发生了什么就足够
团队外部的人需要信任这份记录：客户、审计员、事件审查人员	日志只供团队内部调试使用

若要调试原型，OpenTelemetry、Langfuse 或 LangSmith 等追踪器才是合适的工具。Tracekit 并不取代它们；它提供的是一份可以交给不信任 Agent 的人的记录。了解它与追踪器、护栏库和其他防篡改日志的比较，以及不适合使用它的情况： 比较。

与我们一起试点

你是否正在运行一个会操作真实系统的 Agent，并需要有人为此签字负责：客户、审计员、保险公司？我们可以免费与你一起部署 Tracekit，为期两周：在你的机器上运行一个 Agent。试点结束时，你会获得每次运行对应的已验证证据文件，以及一份书面审查报告，说明 Agent 做了哪些出乎意料的事。 发送电子邮件至 [email protected]，或提交试点申请。

命令

tracekit demo --server                      # allow, deny, approve, then a tampered copy fails verification
tracekit up                                 # start the dev signer, or find the running one
tracekit last                               # export your latest run, pin the dev key, verify it
tracekit view --dev                         # every run, verified: calls, decisions, gaps, replay, why
tracekit approvals list                     # calls held for a person; tracekit approvals approve ID
tracekit export --v2 --run ID -o run.tkb    # one run as one .tkb file
tracekit verify run.tkb --trust trust.json  # offline, against the keys you pinned in trust.json
                                            # (tracekit signer trust -o trust.json, or the one tracekit last wrote)
tracekit policy lint policy.yaml            # check a policy before the signer loads it
tracekit doctor                             # check this setup
tracekit init --dev --v2                    # wire Claude Code's hooks; add --agent codex, cursor, gemini or opencode

检查运行记录的人无需安装任何东西：浏览器验证器只有一个页面，接收 .tkb 文件及其信任文件，不会向任何地方发送数据，并会给出 VERIFIED、FAILED 或 UNVERIFIABLE，以及相应含义和后续操作。

证据格式

• 有规范。 证据格式 v2 力求足够精确，以便编写独立验证器，并提供规范性的测试向量。
• 基于标准构建。 记录使用 Ed25519 对 RFC 8785 规范化 JSON 进行签名。每个日志都是 RFC 6962 Merkle 树，采用了证书透明度所用的结构。检查点采用 C2SP 签名声明，见证方按照 C2SP tlog-cosignature 对其进行共同签名。
• 自包含。 .tkb 文件是一个 zip，包含记录、纳入证明、检查点以及用于判定调用的策略快照。文件中不包含验证代码。
• 旧文件仍可验证。 格式只会扩展，每种格式的验证器都会冻结；较旧的验证器遇到较新的文件时会报告 UNVERIFIABLE (needs tracekit >= x)，而不是 FAILED。可使用 uvx --from "tracekit-ai>=x" tracekit verify run.tkb --trust trust.json、npx -y @cygnuxlabs/tracekit@latest verify run.tkb --trust trust.json（Node 20.12 或更高版本），或浏览器验证器验证此类文件。浏览器验证器会在浏览器中检查文件，不会发送任何数据。从 1.4.0 起，较旧验证器可能无法读取的新增内容不再是关键项：证据包仍会验证通过，报告会指出该验证器未解读的内容。

在 GitHub Actions 中使用 uses: Cygnux-Labs/Tracekit@main（设置 bundle: 和 key: 或 witness:），即可验证 v1 证据包。require-anchor 默认为 true，因此未锚定的证据包会导致步骤失败；设置 require-anchor: "false" 则只会报告相关情况。

参与贡献

以下每项工作单独完成都很有价值，而且都不需要了解整个代码库：

• 用其他语言编写验证器。 证据格式有规范，并提供测试向量。仅根据规范编写 Go 或 Rust 验证器，是检验规范是否完整的最佳方式。
• 找出策略包放行的有害调用。 将其添加到tests/data/policy/deny/，并添加能够拦截它的规则；E17 会运行每个案例。
• 在自己的 Agent 上运行 Tracekit，并反馈问题。 在两个开源 Agent 上这样做发现了实际缺陷（案例研究）。
• 添加框架。 集成通过适配器契约后，即视为完成。
• 尝试攻破它。 找出 E1 和 E8 未能发现的篡改或绕过方式，并按照 SECURITY.md 中的说明私下报告。除非发现者要求不公开，否则我们会将其列入荣誉榜。

开始参与：运行 make install，然后运行 make check（贡献指南）。较小的任务会标记为适合新手的问题。所有参与者都应遵守行为准则。

文档

目标	从这里开始
阅读你的第一份验证报告	面向审计人员的 Tracekit
查看全新安装后的每个步骤	操作演示（录制于 1.2.0） · 录制演示 · 查看器导览
接入 Agent	v2 快速入门 · 编码 Agent · TypeScript SDK
将签名器置于无法触及的地方	部署 · compose · 容器 · Kubernetes · agent-sandbox · doctor
决定调用	策略参考 · 审批 · 事件 · webhook
检查证据	阅读验证报告 · 审计人员指南 · 见证者 · 监控 · 合规映射
询问某个操作为何发生	tracekit why · 其架构
了解设计	Tracekit 的工作原理 · 架构 · 评估 · 技术报告 · 案例研究
了解哪些内容稳定	支持 · 限制 · 常见问题 · 安全检查清单 · 更新日志
运行 v1 笔记本签名器	编码 Agent · 签名 · v1 适配器

许可证

MIT，版权所有 Cygnux Labs。当前版本为 1.4.2，1.x 是受支持的版本线。请按照 SECURITY.md 中的说明，私下报告漏洞。

引用

论文：Tracekit-v2-paper.pdf（arXiv:2609.35659）。

@misc{ghosh2026tracekit,
  author        = {Bravish Ghosh},
  title         = {Tracekit: Tamper-Evident Intent-Reasoning-Action Auditing for AI Agents},
  year          = {2026},
  eprint        = {2609.35659},
  archivePrefix = {arXiv},
  url           = {https://arxiv.org/abs/2609.35659},
  note          = {Code: \url{https://github.com/Cygnux-Labs/Tracekit}}
}

---