Circom-Auditor：用于发现 Circom 代码漏洞的开源 Skills - ZK/SEC Quarterly

安全 · AI · 审计

Circom-Auditor：用于发现 Circom 代码漏洞的开源 Skills

在过去的几个月里，我们一直在撰写关于使用 AI 发现密码学代码漏洞的文章：包括 Cloudflare 的 CIRCL、OpenVM 的 zkVM、以及 Bron Labs 的 MPC 库，所有这些文章都收录在我们的 AI meets Cryptography 系列中。与此同时，我们一直在构建和改进 zkao，这是我们的一款 AI 审计器，它会持续审计密码学代码，直到深层漏洞浮出水面（它最近发布了 2.0 大版本）。

放眼更成熟的安全领域，ZK 开发中明显缺少一样东西：能够充当开发者和审计者第一道防线的开源 skills。这种工具便宜且快速，你可以赶在其他人查看之前，先在自己的代码上运行一遍。智能合约安全领域已经有了这样的先例：Pashov Audit Group 的 skills 证明了精心策划的一组 agent skills 可以产生多大的影响，而 zk-skills 的诞生直接受到了他们工作的启发；感谢他们铺平了道路。ZK 领域一直没有类似的东西。直到今天。

我们发布了 zk-skills v0.1.0，这是我们开源的（MIT 许可）ZK 安全 skills 集合。第一个版本包含 circom-auditor，这是一种专门用于发现 Circom 项目漏洞的方法论，兼容 Claude Code 和 Codex，也兼容采用相同 skill 格式的其他运行时，例如 Cursor。

这些 skills 的定位

Skills 是第一道防线和预审计检查。它们不能替代深入的人工安全审查、彻底的 AI 审计器运行或形式化验证。它们是安全生命周期的第一步，与上述手段相辅相成：尽早并频繁地运行它们，在彻底的安全审查之前修复漏洞。

circom-auditor 内部包含什么

Skill 是一个由指令和参考资料组成的包，当任务与之匹配时，编码 agent 会按需加载它：包含描述工作流程的 markdown 文件，以及 agent 可以运行的辅助脚本。Circom-auditor 为 Circom 电路打包了一套安全审查工作流程，用于查找健全性（soundness）、完备性（completeness）和隐私漏洞，一次运行会经历四个阶段。

范围界定（Scoping）。 一个打包的 Python 脚本解析范围内的 .circom 文件，构建 include 依赖图，并收集本地项目文档。随项目引入的第三方库（如 circomlib）被视为外围上下文：审计聚焦于你的代码，并标记调用方对库前置条件的误用。

猎寻（Hunting）。 审计被拆分为 17 个子 agent，最多同时运行 6 个。它们都阅读相同的代码，但每个都从不同的角度攻击它：

• 6 个 agent 检查代码中已知的 Circom 攻击向量：信号和有限域问题、范围检查、选择器和累加器、绑定（拆分为两个 agent）、以及正则/语言模式。这些是我们在审计中反复遇到的经典陷阱，其中很多已经记录在我们的 Common Circom Pitfalls 系列文章中。
• 6 个 agent 各自深入研究一类漏洞：未约束问题、比较器和 limb 边界、有限域算术与回绕、选择器和 mux 的布尔性、跨模板不变量、以及域绑定（nullifier、重放攻击、公共输入）。
• 2 个 agent 忽略已知攻击向量：一个试图违反每个电路的隐式假设，另一个则完全不使用检查清单，自由地进行对抗性检查。
• 3 个 agent 在尚未被探索的领域猎寻，寻找介于上述类别之间的数值、绑定和组合漏洞。

裁决（Judging）。 原始发现经过去重后，会依次经过四道关卡：攻击是否真的能够在约束系统上执行、坏 witness 是否可达、恶意 prover 能否利用它、以及它是否会造成实际危害。通过所有关卡的候选者还会再经过一轮对抗性复核，由一个全新的 agent 判断该漏洞是否真的可以被利用。

报告（Reporting）。 确认的发现会被整理成报告，包含根本原因、建议修复方案，并注明该漏洞是由哪个 agent 检测到的。任何没有具体可利用场景的发现会被降级为线索（lead），而不是被静默丢弃。

在不支持子 agent 的运行时上，该 skill 会回退到本地单 agent 模式，使用相同的分类目录和裁决关卡。一次完整的委派运行通常远不到半小时就能完成，具体取决于模型和范围。

Circom-auditor 针对小型到中型的代码库，大约 5k 行 Circom 以内。对于更大的项目，我们建议将目标指向特定电路，一次一个入口点，这样每次运行都能保持足够的上下文。

充分发挥它的作用

将协议说明和威胁模型放在 assets/docs/ 中；审计器会使用它们来理解预期语义。将之前的报告保留在 assets/findings/ 中，以便仍然相关的问题得到重新验证。另外，由于 LLM 审查是非确定性的，请对高风险代码多次运行：不同的运行会暴露不同的漏洞。

运行方式

安装只需要克隆仓库并创建符号链接。对于 Claude Code：

git clone https://github.com/zksecurity/zk-skills.git ~/zk-skills
mkdir -p ~/.claude/skills
ln -sfn ~/zk-skills/skills/circom-auditor ~/.claude/skills/circom-auditor

对于 Codex，将同一目录符号链接到 ~/.agents/skills（或 ~/.codex/skills，取决于你的配置）。然后在你要审计的项目中启动你的 agent，并询问：

Use $circom-auditor to audit the Circom circuits in this repo.

你还可以指定特定文件、使用“no subagents”强制进行本地单 agent 运行，或添加 --file-output 将报告写入 assets/findings/ 目录。

评估

为了评估该 skill，我们使用了 zkbugs 中的漏洞代码，这是我们之前撰写过文章的 ZK 电路漏洞数据集。zkbugs 已经维护了一份针对这些漏洞的 Circom 安全工具评估：包括符号化和形式化验证器（Picus、Ecne、ConsCS、Civer）、静态分析（Circomspect）和模糊测试（zkFuzz）。这为我们提供了比较的基线。

我们在两个运行时上运行了 circom-auditor：基于 Opus 4.8 的 Claude Code 和基于 GPT-5.5 的 Codex。为了保证比较的公平性，我们删除了所有 git 历史，这样模型就无法通过阅读修复提交来作弊；同时禁用了网络访问，这样它们就无法在线查找这些漏洞。

该基准测试支持两种模式。Direct 模式仅包含易受攻击的电路及其必需引用的电路，覆盖全部 70 个漏洞。Original 模式包含漏洞最初所在的完整代码库。

检测如何计数

对于两次 circom-auditor 运行，只有当经过裁决的报告与已记录的真实漏洞匹配时，才算检测到该漏洞；如果报告标记了其他问题但遗漏了实际漏洞，则计为未命中。

以下是 Direct 模式的结果：

两次运行都检测到了超过 90% 的漏洞：Claude 为 66/70，Codex 为 64/70。最好的经典工具 Ecne 达到了 30/70，而且每个经典工具在分析开始之前，就会因编译错误和超时在基准测试中丢掉相当一部分用例。1 这里需要为 Ecne 补充一点说明：它实际上并不做漏洞发现。它检查 R1CS 信号是否被唯一确定，并标记无法证明其健全性的约束，然后由你来判断其中哪些可以被利用、以及如何利用。这种输出本身很难直接据此采取行动，但将其作为线索交给 AI agent 去调查，是我们预期会很有效的组合方式，能够引导 agent 直奔漏洞。更普遍地说，这与我们在基准测试之外的体验一致：这些工具中的大多数在它们能够编译通过的电路上验证一个属性（通常是信号是否被正确约束），而 LLM 审计器则像人类审查者一样阅读电路，并且还能标记语义问题，例如缺少域分离，或无法绑定到正确操作的 nullifier。

Original 模式才是真正有趣的地方：

在完整代码库上，经典工具大多崩溃：Picus 什么都没检测到2，Ecne 下降到 8/56，而 Circomspect 的 13/56 来自于一般性的 lint 警告。使用 Claude 的 Circom-auditor 仍然检测到了 40/56（71%）。令人意外的是 Codex 下降到 14/56。最可能的解释是 Codex 的上下文窗口较小：在 Original 模式下，代码库可能已经无法被完整容纳，因此有更多内容不得不被摘要掉或跳过。此外，在此模式下，Codex 的运行耗时不到 Claude 的一半（中位数 8 分钟对 19 分钟）。

注意事项

zkbugs 是公开的，因此尽管删除了 git 历史并禁用了网络访问，这些漏洞仍可能已经泄露到模型的训练数据中；请将绝对数字视为上限，而将模式和工具之间的差距视为更可靠的信号。此外，LLM 审计是非确定性的，而且这些是针对每个漏洞的单次运行：不同的运行可能会发现不同的子集。最后，经典工具会生成机器可检查的判定和反例，而 LLM 报告仍然需要人工阅读。

结论

通过 circom-auditor，我们希望为 Circom 开发者提供一个额外的工具来构建成熟、安全的电路，也为审计者提供一个快速的预审计流程，尽早捕获那些简单的漏洞。我们将这些 skills 开源，以便社区能够随时间不断改进它们：新的攻击向量、更好的视角、更精准的裁决、更多的基准测试。我们接下来计划为其他证明系统和 DSL 开发 skills，例如 halo2-auditor 和 plonky3-auditor，以及更通用的 ZK 审计 skills。

从本质上讲，这样的 skill 只能触及部分漏洞：它是为现成的编码 agent 编写的方法论，受限于该 agent 在单次运行中能够探索的范围。zkao 则采用了截然不同的方法：它不是在一个通用 agent 上叠加指令，而是围绕模型构建的专用框架，它能进行远比 skill 更系统、更彻底的分析和漏洞探索。如果你维护着一个密码学或 ZK 项目，并且对以上任何内容感兴趣，我们很乐意与你一起审查，无论是通过 zkao、这些 skills，还是人工审计。欢迎通过 zksecurity.xyz/contact 联系我们。

致谢

这项工作的部分资金来自 Giveth 上的 Ethereum Security 二次方资助轮，这是有史以来规模最大的 QF 匹配资金池。衷心感谢引领本轮资助的捐赠者：TheDAO Security Fund、Quantstamp 和 Wintermute。你可以在轮次结果中找到所有主要捐赠者。感谢你们支持以太坊生态中的开源安全工作。

---

1. 经典工具以每个漏洞 5 分钟的超时时间运行，与 zkbugs 工具评估 的设置保持一致。这个限制并不是它们表现不佳的原因：该限制是凭经验选择的，使用更长的超时重新运行并没有改善结果。circom-auditor 的运行没有这样的限制：Direct 模式的中位运行时间约为 14 分钟（Claude）和 9 分钟（Codex），Original 模式约为 19 分钟和 8 分钟。↩
2. 这里以及整个评估中，我们运行的是 Picus 的开源版本。Veridise 还维护着一个专有版本，这些结果对该版本的表现不作任何评价。↩

• 原文链接： blog.zksecurity.xyz/post...
• 鸿途知科网 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～