Rust-based security testing for zero-knowledge systems.
ZkPatternFuzz is a Rust-based security testing framework for zero-knowledge systems. It combines single-target fuzzing, batch pattern execution, backend readiness checks, and evidence-oriented reporting for Circom, Cairo, Noir, and Halo2 targets.
Index
Overview
zk-fuzzer: single-target scanning, legacy campaign execution, preflight checks, and tool bootstrap helpers.
zkpatternfuzz: batch execution across a target registry and pattern catalog.
zk0d_benchmark: repeated benchmark-suite runner.
zkf_checks: repository hygiene and policy checks.
zk-circuit-gen: adversarial circuit generation, compiler differential testing, and semantic-intent matching for hostile target creation.
The project is built for proof-oriented security work. A finding is only useful if it ends in one of two states:
- deterministic exploit replay with reproducible artifacts, or
- bounded non-exploitability evidence with clear assumptions.
The main moat is not just "fuzzing." It is the accumulation of operator-reviewed security knowledge as reusable assets: YAML attack patterns, bundled CVE fixtures, benchmark suites, and replay-oriented evidence bundles. That lets one audit's edge cases become the next audit's default checks.
Operator docs live under docs/INDEX.md. Validation artifacts and replay bundles are stored under artifacts/.
Use Cases
- Audit a single Circom, Cairo, Noir, or Halo2 target with one reproducible scan command.
- Run standardized
smoke, standard, and deep campaigns against a fixed target registry without rebuilding long CLI invocations.
- Regress known CVE-style patterns against portable in-repo fixtures before touching heavier external targets.
- Generate replayable findings and proof-status artifacts instead of stopping at hint-only detections.
- Preflight backend readiness, key setup, and local tooling before spending time on long fuzzing campaigns.
- Track batch outcomes across aliases, catalogs, and timestamped artifact bundles during repeated security work.
- Generate adversarial circuits and compiler-regression corpora instead of relying only on hand-written benchmark targets.
Comparison With Related Tools
These tools are complementary rather than interchangeable. For ZK work, the important distinction is whether a tool is doing runtime discovery, static analysis, or formal safety verification.
ZK-Native Tools
| Tool |
Primary scope |
Analysis style |
Main strength |
Best fit |
ZkPatternFuzz |
Circom, Cairo, Noir, Halo2, and batch ZK target registries |
Pattern-guided fuzzing plus replay/evidence orchestration |
Cross-backend discovery with reproducible scan, batch, and replay workflows |
ZK audits, regression lanes, and operator-driven triage |
Picus |
Circom / R1CS safety analysis |
Formal verification |
Proves or refutes weak/strong safety and can produce concrete counterexamples for underconstraint bugs |
Confirming or disproving safety properties after discovery |
Circomspect |
Circom source code |
Static analysis and linting |
Fast source-level checks for common Circom mistakes and vulnerability patterns |
Early CI linting and developer feedback before heavy runs |
CIVER |
Circom circuits and safety specifications |
SMT-backed formal verification |
Checks weak safety, tags, and pre/postconditions with modular analysis |
Determinism and specification checking in Circom-heavy codebases |
circom --inspect |
Circom compilation flow |
Built-in compiler inspection |
Cheap first-pass warnings for potentially underconstrained or unused signals |
Baseline hygiene checks during everyday circuit development |
Adjacent Smart Contract And Audit Tools
| Tool |
Primary scope |
Analysis style |
Main strength |
Best fit |
Echidna |
Solidity / EVM contracts |
Property-based fuzzing |
Invariant-driven contract fuzzing with shrinking |
Solidity invariant testing |
Medusa |
Solidity / EVM contracts |
Coverage-guided mutational fuzzing |
Parallel worker-based contract fuzzing |
Larger EVM fuzz workloads |
Halmos |
Solidity / Foundry EVM tests |
Symbolic testing |
Solver-backed exploration of EVM properties |
Targeted proof-style checks for Solidity tests |
Foundry / Forge |
Solidity development and testing |
Unit, fuzz, and invariant testing |
Tight developer loop inside Solidity repos |
App-dev feedback loops and contract test suites |
Slither |
Solidity and Vyper review |
Static analysis |
Fast detector-based audit triage and code comprehension |
Static review and CI policy gates |
Mode 2 Evidence Campaigns
campaigns/mode2/patterns/ is the deep single-target evidence lane. These patterns are heavier than the lightweight benchmark templates and are meant to surface high-signal single-circuit bugs before you move to Mode 3 chain fuzzing.
Current Mode 2 bundles include:
underconstrained_witness_deep.yaml: deep witness-pair search plus semantic cross-checks
soundness_forge_deep.yaml: deeper proof-forgery and verification-soundness pressure
Use Mode 2 when you want stronger single-circuit evidence and broader attack coverage than the standard benchmark templates, but you do not yet need multi-step protocol chains. For chain-focused work, step up to Mode 3 and the workflow in docs/CHAIN_FUZZING_GUIDE.md.
Semantic Analysis Lane
The semantic lane is wired into the repository as a checked-in campaign flow rather than a crate example only:
- wrapper:
scripts/run_semantic_exit_sample.sh
- checked-in execution evidence:
campaigns/semantic/semantic_exit_sample.execution_evidence.json
- runner:
cargo run -p zk-track-semantic --example semantic_exit_campaign -- ...
- aggregate report:
artifacts/semantic_exit/latest_report.json
Use this path when the security question is about intended behavior versus accepted behavior, not just constraint-level attack findings. That is the lane for "the circuit compiles, witnesses satisfy constraints, but the accepted behavior still violates the documented security model."
The operator workflow and manual-label precision loop are documented in docs/SEMANTIC_ANALYSIS_OPERATOR_GUIDE.md and campaigns/semantic/README.md.
Requirements
- Rust toolchain with Cargo
- Node.js and
npm for Circom-related fixtures and local JavaScript dependencies
- Z3 for symbolic execution and solver-backed checks
- backend tools as needed for the targets you run:
circom, snarkjs, nargo, scarb, and/or Halo2 Rust toolchains
Use docs/TOOLS_AVAILABLE_ON_HOST.md for the verified tool inventory in this workspace.
Build And Validation
git clone https://github.com/Teycir/ZkPatternFuzz.git
cd ZkPatternFuzz
cp config.env.example config.env
npm ci
cargo build --release --bins
cargo test
npm ci installs the small dependency surface used by local Circom fixtures and benchmark lanes. node_modules/ is intentionally ignored and should not be committed.
Validated CI coverage currently targets Ubuntu and Windows runners. macOS is intentionally excluded from the supported CI/build matrix until its toolchain path is restored.
Generate local API docs when needed:
cargo doc --workspace --no-deps
Runtime Environment
The tracked config.env.example is the supported baseline for both wrapper scripts and direct batch runs:
cp config.env.example config.env
set -a
source config.env
set +a
That loads the writable output roots, build cache paths, and the required zkpatternfuzz batch timeout settings. Override values in config.env only when you need a different local output root or a different standardized target binding.
Quick Start
Generate a pattern template:
target/release/zk-fuzzer init --output /tmp/zkf_sample.yaml --framework circom
Validate a real scan in dry-run mode against the local Cairo readiness target:
target/release/zk-fuzzer scan \
tests/patterns/scan_smoke_mono.yaml \
--target-circuit tests/cairo_programs/multiplier.cairo \
--main-component main \
--framework cairo \
--workers 2 \
--iterations 50 \
--timeout 30 \
--dry-run
Run a backend preflight for a legacy campaign:
target/release/zk-fuzzer preflight campaigns/examples/defi_audit.yaml --setup-keys
List the bundled CVE patterns:
target/release/zk-fuzzer --list-patterns
Standardized Routine Runs
For daily smoke, standard, and deep runs, use the fixed wrappers instead of rebuilding long CLI invocations:
scripts/run_std_smoke.sh
scripts/run_std_standard.sh
scripts/run_std_deep.sh
scripts/monitor_std_run.sh
The target bindings for those wrappers are the three config.env keys below:
ZKF_STD_TARGET_SMOKE
ZKF_STD_TARGET_STANDARD
ZKF_STD_TARGET_DEEP
Each binding can be either a named matrix entry or a direct target path such as /home/teycir/ZkRepos/tornado-core/circuits/withdraw.circom. When you bind a direct path and auto-detection is ambiguous, set the companion ZKF_STD_TARGET_*_FRAMEWORK and ZKF_STD_TARGET_*_MAIN_COMPONENT values in config.env.
To discover current runnable targets from a live checkout such as /home/teycir/ZkRepos, use:
python3 scripts/discover_zkrepos_targets.py --root /home/teycir/ZkRepos
python3 scripts/discover_zkrepos_targets.py --root /home/teycir/ZkRepos --match withdraw --format env --profile smoke
To start from a clean shortlist instead of the full raw inventory, use the curated intake pass:
python3 scripts/curate_zkrepos_targets.py --root /home/teycir/ZkRepos
python3 scripts/curate_zkrepos_targets.py --root /home/teycir/ZkRepos --verify --format json
The curated pass filters out framework source trees, workspace aggregates, tests/docs/fixtures, and non-runnable targets, then reports per-target prerequisites and dependency blockers. On the current live tree, the ready first-pass targets are tornado-core/circuits/withdraw.circom plus a set of noir-examples binary manifests; zkevm-circuits remains in the shortlist but is reported as blocked until its Rust git dependencies are locally available.
The operational contract for these profiles is documented in docs/STANDARDIZED_RUN_PROFILES.md.
For a full-coverage single-target campaign against the broad prod catalog, use:
scripts/run_full_coverage_target.sh
That runner defaults to /home/teycir/ZkRepos/tornado-core/circuits/withdraw.circom, uses --config-profile prod --alias always, and defaults to 50000 iterations unless you override ITERATIONS=....
Circuit Generation
zk-circuit-gen is the circuit-generation and compiler-testing lab that sits alongside the fuzzer. It generates hostile circuits, mutation-based corpora, semantic-intent checks, compiler crash probes, and differential compiler/version matrices across Circom, Noir, Halo2, and Cairo.
Useful entrypoints:
cargo run -q -p zk-circuit-gen --example generate_bulk_corpus -- --help
cargo run -q -p zk-circuit-gen --example generate_adversarial_corpus -- --help
cargo run -q -p zk-circuit-gen --example run_differential_version_matrix -- --help
cargo run -q -p zk-circuit-gen --example run_compiler_crash_detector -- --help
Use docs/CIRCUIT_GEN.md for the operator-facing overview and artifact layout.
Plugin API
External attack plugins are supported through the attack-plugins feature and the example crate crates/zk-attacks-plugin-example. The short contract is:
- build the host with
--features attack-plugins
- ship plugins as
cdylib
- export
zk_attacks_plugins
- implement
AttackPlugin metadata plus an Attack implementation
Use docs/PLUGIN_API.md for the minimal contract and docs/PLUGIN_SYSTEM_GUIDE.md for discovery, strict-mode behavior, and safety notes.
Direct Batch Runs
After sourcing config.env, you can inspect the catalog:
target/release/zkpatternfuzz \
--registry targets/fuzzer_registry.prod.yaml \
--alias always \
--jobs 1 \
--workers 2 \
--list-catalog
Run a dry-run batch against the local Cairo readiness target:
target/release/zkpatternfuzz \
--registry targets/fuzzer_registry.prod.yaml \
--alias readiness_cairo \
--target-circuit tests/cairo_programs/multiplier.cairo \
--main-component main \
--framework cairo \
--jobs 1 \
--workers 2 \
--iterations 50 \
--timeout 30 \
--dry-run \
--emit-reason-tsv
Batch runs write timestamped bundles under ZKF_SCAN_OUTPUT_ROOT/ResultJsonTimestamped/ and per-template artifacts under .scan_run_artifacts/.
Local Circom Bootstrap
To internalize local Circom assets under ./bins:
target/release/zk-fuzzer bins bootstrap
This stages:
circom from PATH
snarkjs from PATH
pot12_final.ptau from the local test fixture
pot12_final.ptau is only a small local fixture. Larger external Circom targets can require a bigger ceremony, for example:
mkdir -p bins/ptau
snarkjs powersoftau new bn128 19 bins/ptau/pot19_0000.ptau
snarkjs powersoftau prepare phase2 bins/ptau/pot19_0000.ptau bins/ptau/pot19_final.ptau
When multiple local .ptau files are available, ZkPatternFuzz now prefers one whose power is large enough for the compiled circuit.
Benchmarks And Repo Checks
Benchmark runner:
target/release/zk0d_benchmark --help
scripts/run_benchmarks.sh --help
Release gate:
scripts/release_candidate_gate.sh --help
Repo policy checks:
target/release/zkf_checks --help
For a local coverage artifact:
cargo llvm-cov --all-features --lcov --output-path lcov.info
Repository Layout
ZkPatternFuzz/
├── src/ # Primary Rust crate and CLI entrypoints
├── crates/ # Workspace crates (core, backends, attacks, symbolic, tracks)
├── campaigns/ # YAML patterns and campaign configs
├── scripts/ # Operational wrappers and release/readiness utilities
├── targets/ # Registries, matrices, benchmark suites
├── tests/ # Integration tests and portable local fixtures
├── artifacts/ # Generated reports, validation evidence, and run outputs
├── docs/ # Operator docs and technical reference
└── bins/ # Internalized local tooling assets
Documentation
Start with:
Operational references:
Validation references:
Historical context:
Attribution
Project home: teycirbensoltane.tn
Contact: teycir@pxdmail.net
License
Business Source License 1.1. See LICENSE for details. The license converts to GPL-3.0 after four years.
Citation
@software{zkpatternfuzz2024,
title={ZkPatternFuzz: A Zero-Knowledge Proof Security Testing Framework},
author={Ben Soltane, Teycir},
year={2024},
url={https://github.com/Teycir/ZkPatternFuzz}
}