{"slug": "circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code", "title": "Circom-Auditor: Open-Source Skills for Finding Vulnerabilities in Circom Code", "summary": "ZK Security released zk-skills v0.1.0, an MIT-licensed open-source collection of ZK security skills, with the first version shipping circom-auditor, a specialized methodology for finding vulnerabilities in Circom projects. Compatible with Claude Code, Codex, and Cursor, circom-auditor runs a four-stage security review workflow—scoping, hunting, judging, and reporting—using 17 subagents to detect soundness, completeness, and privacy bugs. The release addresses the lack of open-source skills for ZK development, providing a cheap and quick first line of defense for developers and auditors.", "body_md": "Over the past months we have been writing about using AI to find vulnerabilities in cryptographic code: in [Cloudflare's CIRCL](https://blog.zksecurity.xyz/posts/circl-bugs/), in [OpenVM's zkVM](https://blog.zksecurity.xyz/posts/openvm-bugs/), and in [Bron Labs's MPC library](https://blog.zksecurity.xyz/posts/bron-bugs/), all collected in our [AI meets Cryptography](https://blog.zksecurity.xyz/series/ai-meets-cryptography/) series.\nIn parallel, we have been building and improving [zkao](https://zkao.io/), our AI auditor that runs continuously on cryptographic code until the deep bugs surface (it recently got a [big 2.0 release](https://blog.zksecurity.xyz/posts/zkao-2-0/)).\n\nLooking at more established security fields, one thing stood out as missing from ZK development: open-source skills that act as a first line of defense for developers and auditors alike.\nSomething cheap and quick you can run on your own code before anyone else looks at it.\nSmart contract security already has this: [Pashov Audit Group's skills](https://github.com/pashov/skills) showed how much impact a well-curated set of agent skills can have, and zk-skills is directly inspired by their work; credit to them for paving the way.\nZK had nothing comparable. Until today.\n\nWe are releasing [zk-skills v0.1.0](https://github.com/zksecurity/zk-skills), our open-source (MIT-licensed) collection of ZK security skills.\nThe first version ships **circom-auditor**, a specialized methodology for finding vulnerabilities in Circom projects, compatible with both Claude Code and Codex, as well as runtimes that share their skill formats, such as Cursor.\n\nSkills are a first line of defense and a pre-audit check. They do not replace a deep manual security review, a thorough AI-auditor run, or formal verification. They complement them as the first step of the security lifecycle: run them early and often, and fix the bugs before a thorough security review.\n\n## What is inside circom-auditor\n\nA skill is a package of instructions and references that a coding agent loads on demand when a task matches it: markdown files describing a workflow, along with helper scripts the agent can run. Circom-auditor bundles a security review workflow for Circom circuits, hunting for soundness, completeness, and privacy bugs, and a run goes through four stages.\n\n**Scoping.** A bundled Python script resolves the `.circom`\n\nfiles in scope, builds the include graph, and collects local project docs.\nVendored libraries like [circomlib](https://github.com/iden3/circomlib) are treated as peripheral context: the audit focuses on your code and flags caller-side misuse of library preconditions.\n\n**Hunting.** The audit is split across 17 subagents, with at most 6 running at once.\nThey all read the same code, but each attacks it from a different angle:\n\n- 6 agents look at the code for known Circom attack vectors: signal and field issues, range checks, selectors and accumulators, binding (split across two agents), and regex/language patterns. These are the classic footguns we keep running into during audits, many of which we have written up in our\n[Common Circom Pitfalls](https://blog.zksecurity.xyz/posts/circom-pitfalls-1/)series. - 6 agents each dig into one class of bugs: unconstrained issues, comparator and limb bounds, field arithmetic and wraparound, booleanity of selectors and muxes, cross-template invariants, and domain binding (nullifiers, replay, public inputs).\n- 2 agents ignore known vectors: one trying to violate every circuit's implicit assumptions, and one does a free adversarial pass with no checklist at all.\n- 3 agents hunt at whatever has been unexplored, looking for numerical, binding, and composition bugs that fall between the categories above.\n\n**Judging.** Raw findings are deduplicated and then pushed through four sequential gates: can the attack actually be executed against the constraint system, is the bad witness reachable, can a malicious prover exploit it, and does it cause real harm.\nCandidates that survive get one more adversarial triage pass asking a fresh agent whether the bug is really exploitable.\n\n**Reporting.** Confirmed findings are formatted into a report with the root cause, a proposed fix, and a note of which agent detected it.\nAnything without a concrete exploitable scenario is demoted to a lead rather than silently dropped.\n\nOn runtimes without subagent support, the skill falls back to a local single-agent pass over the same catalogs and judging gates. A full delegated run typically finishes in well under half an hour, depending on model and scope.\n\nCircom-auditor targets small to medium codebases, roughly under 5k lines of Circom. For larger projects we recommend pointing it at specific circuits, one entrypoint at a time, so each run keeps enough context.\n\nPut protocol notes and threat models in `assets/docs/`\n\n; the auditor uses them to understand intended semantics.\nKeep previous reports in `assets/findings/`\n\nso still-relevant issues are revalidated.\nAnd since LLM review is non-deterministic, run it more than once on high-risk code: different passes surface different bugs.\n\n## Running it\n\nInstallation is a clone and a symlink. For Claude Code:\n\n```\ngit clone https://github.com/zksecurity/zk-skills.git ~/zk-skills\nmkdir -p ~/.claude/skills\nln -sfn ~/zk-skills/skills/circom-auditor ~/.claude/skills/circom-auditor\n```\n\nFor Codex, symlink the same directory into `~/.agents/skills`\n\n(or `~/.codex/skills`\n\n, depending on your setup).\nThen start your agent inside the project you want audited and ask:\n\n```\nUse $circom-auditor to audit the Circom circuits in this repo.\n```\n\nYou can also name specific files, force a local single-agent pass with \"no subagents\", or add `--file-output`\n\nto write the report under `assets/findings/`\n\n.\n\n## Evaluation\n\nTo evaluate the skill we used the vulnerable code from [zkbugs](https://github.com/zksecurity/zkbugs), our dataset of ZK circuit vulnerabilities that we have [written about before](https://blog.zksecurity.xyz/posts/zkbugs-website/).\nzkbugs already maintains an [evaluation of Circom security tools](https://bugs.zksecurity.xyz/tools-evaluation) on these bugs: symbolic and formal verifiers (Picus, Ecne, ConsCS, Civer), static analysis (Circomspect), and fuzzing (zkFuzz).\nThat gave us a baseline to compare against.\n\nWe ran circom-auditor on two runtimes: Claude Code with Opus 4.8 and Codex with GPT-5.5. To keep the comparison honest, we removed all git history so the models could not cheat by reading the fix, disabled web access so they could not look the bugs up online.\n\nThe benchmark supports two modes.\n**Direct** contains only the vulnerable circuit along with the essential circuits it includes, for all 70 bugs.\n**Original** contains the entire codebase in which the bug originally existed.\n\nFor the two circom-auditor runs, a bug only counts as detected when the triaged report matches the documented ground-truth bug; a report that flags other issues but misses the actual bug counts as a miss.\n\nHere are the results on direct mode:\n\nBoth runs detect over 90% of the bugs: 66/70 with Claude and 64/70 with Codex.\nThe best classic tool, Ecne, reaches 30/70, and every classic tool loses a chunk of the benchmark to compilation errors and timeouts before analysis even starts. 1\nEcne deserves a caveat here: it does not really do bug finding.\nIt checks whether R1CS signals are uniquely determined and flags the constraints it cannot prove sound, leaving you to work out whether and how any of that is exploitable.\nThat output is hard to act on by itself, but feeding it to an AI agent as leads to investigate is a combination we expect to work well and to point the agent straight at bugs.\nMore generally, this matches our experience beyond the benchmark: most of these tools verify one property (usually that signals are properly constrained) on circuits they manage to compile, while an LLM auditor reads the circuit the way a human reviewer does and can also flag semantic issues like missing domain separation or a nullifier that fails to bind to the right action.\n\nOriginal mode is where things get interesting:\n\nThe classic tools mostly collapse on whole codebases: Picus detects nothing 2, Ecne drops to 8/56, and Circomspect's 13/56 comes from generic lint warnings.\nCircom-auditor with Claude still detects 40/56 (71%).\nThe surprise is Codex dropping to 14/56.\nThe most likely explanation is Codex's smaller context window: in original mode the codebase probably no longer fits, so more of it has to be summarized away or skipped.\nFurther, the Codex runs finished in less than half the time of the Claude ones in this mode (median 8 versus 19 minutes).\n\nzkbugs is public, so these bugs may have leaked into the models' training data despite the removed git history and disabled web access; treat the absolute numbers as an upper bound, and the gap between modes and tools as the more reliable signal. Also, LLM audits are non-deterministic and these are single runs per bug: a different pass may find a different subset. Finally, classic tools produce machine-checkable verdicts and counterexamples, while an LLM report still needs a human to read it.\n\n## Conclusion\n\nWith circom-auditor we want to give Circom developers one more tool for building mature, secure circuits, and auditors a fast pre-audit pass that catches the cheap bugs early. We are open-sourcing the skills so the community can improve them over time: new attack vectors, better lenses, sharper judging, more benchmarks. Next on our list are skills for other proof systems and DSLs, such as a halo2-auditor and a plonky3-auditor, along with more generic ZK auditing skills.\n\nBy its nature, a skill like this only reaches some of the bugs: it is a methodology written down for an off-the-shelf coding agent, bounded by what that agent can explore in a single run.\n[zkao](https://zkao.io/) takes a very different approach: instead of instructions layered on a general-purpose agent, it is a purpose-built harness around the models, and it performs far more systematic and thorough analysis and bug-finding exploration than a skill can.\nIf you maintain a cryptography or ZK project and any of this sounds interesting, we would love to look at it with you, whether through zkao, the skills, or a manual audit.\nReach out at [zksecurity.xyz/contact](https://zksecurity.xyz/contact).\n\n## Acknowledgements\n\nPart of this work was funded through the Ethereum Security quadratic funding round on Giveth, the largest QF matching pool ever run.\nA big shout-out to the donors who led this round: [TheDAO Security Fund](https://x.com/TheDAOfund), [Quantstamp](https://x.com/quantstamp) and [Wintermute](https://x.com/wintermute_t).\nYou can find all the big donors in the [round results](https://forum.giveth.io/t/ethereum-security-qf-round-results-april-23-may-14-2026/2201).\nThank you for supporting open-source security work in Ethereum.\n\n-\nThe classic tools run with a 5-minute per-bug timeout, matching the setup of the\n\n[zkbugs tools evaluation](https://bugs.zksecurity.xyz/tools-evaluation). That limit is not what holds them back: it was chosen empirically, and rerunning with a larger timeout did not improve the results. The circom-auditor runs have no such limit: the median run took about 14 minutes (Claude) and 9 minutes (Codex) in direct mode, and about 19 and 8 minutes in original mode.[↩](#fnref:timeouts) -\nHere, and throughout the evaluation, we run the\n\n[open-source version of Picus](https://github.com/Veridise/Picus). Veridise also maintains a proprietary version, and these results say nothing about how that one would do.[↩](#fnref:picus)", "url": "https://wpnews.pro/news/circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code", "canonical_source": "https://blog.zksecurity.xyz/posts/circom-auditor/", "published_at": "2026-08-05 00:00:00+00:00", "updated_at": "2026-08-09 12:26:31.058035+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["ZK Security", "zk-skills", "circom-auditor", "Claude Code", "Codex", "Cursor", "Pashov Audit Group"], "alternates": {"html": "https://wpnews.pro/news/circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code", "markdown": "https://wpnews.pro/news/circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code.md", "text": "https://wpnews.pro/news/circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code.txt", "jsonld": "https://wpnews.pro/news/circom-auditor-open-source-skills-for-finding-vulnerabilities-in-circom-code.jsonld"}}