Teycir/ZkPatternFuzz

ZkPatternFuzz 是一个基于 Rust 的零知识系统安全测试框架。它结合了单目标模糊测试、批量模式执行、后端就绪检查以及面向证据的报告功能，支持 Circom、Cairo、Noir 和 Halo2 目标。 ## 目录 - [概述](#overview) - [用例](#use-cases) - [与相关工具的比较](#comparison-with-related-tools) - [Mode 2 证据活动](#mode-2-evidence-campaigns) - [语义分析通道](#semantic-analysis-lane) - [环境要求](#requirements) - [构建与验证](#build-and-validation) - [运行环境](#runtime-environment) - [快速开始](#quick-start) - [标准化例行运行](#standardized-routine-runs) - [电路生成](#circuit-generation) - [插件 API](#plugin-api) - [直接批量运行](#direct-batch-runs) - [本地 Circom 引导](#local-circom-bootstrap) - [基准测试与仓库检查](#benchmarks-and-repo-checks) - [仓库布局](#repository-layout) - [文档](#documentation) - [许可证](#license) ## 概述 - `zk-fuzzer`：单目标扫描、遗留活动执行、预检以及工具引导助手。 - `zkpatternfuzz`：跨目标注册表和模式目录的批量执行。 - `zk0d_benchmark`：重复基准测试套件运行器。 - `zkf_checks`：仓库规范和策略检查。 - `zk-circuit-gen`：用于创建敌对目标的对抗性电路生成、编译器差异测试以及语义意图匹配。 本项目专为面向证明的安全工作而构建。只有当一项发现最终呈现为以下两种状态之一时，它才具有实用价值： - 具有可复现产物的确定性漏洞利用重放，或 - 具有明确假设的有界不可利用性证据。 其核心壁垒不仅仅是“模糊测试”。它是将操作员审查过的安全知识积累为可重用的资产：YAML 攻击模式、打包的 CVE 测试夹具、基准测试套件以及面向重放的证据包。这使得一次审计发现的边缘用例能够成为下一次审计的默认检查项。 操作员文档位于 [docs/INDEX.md](docs/INDEX.md)。验证产物和重放包存储在 `artifacts/` 下。 ## 用例 - 使用一个可复现的扫描命令审计单个 Circom、Cairo、Noir 或 Halo2 目标。 - 在不重新构建冗长 CLI 调用的情况下，针对固定的目标注册表运行标准化的 `smoke`、`standard` 和 `deep` 活动。 - 在触及较重的外部目标之前，针对仓库内置的可移植测试夹具对已知的 CVE 风格模式进行回归测试。 - 生成可重放的发现结果和证明状态产物，而不是仅仅停留在仅提供提示的检测层面。 - 在花费时间进行长时间的模糊测试活动之前，对后端就绪状态、密钥设置和本地工具进行预检。 - 在重复的安全工作中跟踪跨别名、目录和带时间戳的产物包的批量执行结果。 - 生成对抗性电路和编译器回归语料库，而不是仅仅依赖手写的基准测试目标。 ## 与相关工具的比较 这些工具是互补的，而非相互替代。对于 ZK 工作，重要的区别在于工具是进行运行时发现、静态分析，还是形式化安全验证。 ### ZK 原生工具 | 工具 | 主要范围 | 分析方式 | 主要优势 | 最适场景 | | --- | --- | --- | --- | --- | | `ZkPatternFuzz` | Circom、Cairo、Noir、Halo2 以及批量 ZK 目标注册表 | 模式引导的模糊测试加重放/证据编排 | 通过可复现的扫描、批量和重放工作流实现跨后端发现 | ZK 审计、回归测试通道以及操作员驱动的分类筛选 | | [`Picus`](https://docs.veridise.com/picus/) | Circom / R1CS 安全分析 | 形式化验证 | 证明或反驳弱/强安全性，并能针对约束不足的漏洞生成具体的反例 | 在发现之后确认或反驳安全属性 | | [`Circomspect`](https://github.com/trailofbits/circomspect) | Circom 源代码 | 静态分析和检测 | 针对常见 Circom 错误和漏洞模式进行快速的源码级检查 | 在执行繁重任务之前进行早期 CI 检测和开发者反馈 | | [`CIVER`](https://github.com/costa-group/circom_civer) | Circom 电路和安全规范 | 基于 SMT 的形式化验证 | 通过模块化分析检查弱安全性、标签以及前置/后置条件 | 在严重依赖 Circom 的代码库中进行确定性和规范检查 | | [`circom --inspect`](https://docs.circom.io/circom-language/code-quality/inspect/) | Circom 编译流程 | 内置编译器检查 | 针对潜在约束不足或未使用的信号提供低成本的初步警告 | 在日常电路开发期间的基准规范检查 | ### 相邻的智能合约与审计工具 | 工具 | 主要范围 | 分析方式 | 主要优势 | 最适场景 | | --- | --- | --- | --- | --- | | `Echidna` | Solidity / EVM 合约 | 基于属性的模糊测试 | 具有输入缩减功能的不变量驱动合约模糊测试 | Solidity 不变量测试 | | `Medusa` | Solidity / EVM 合约 | 覆盖率引导的变异模糊测试 | 基于并行 Worker 的合约模糊测试 | 较大的 EVM 模糊测试工作负载 | | `Halmos` | Solidity / Foundry EVM 测试 | 符号化测试 | 基于 Solver 的 EVM 属性探索 | 针对 Solidity 测试的定向证明式检查 | | `Foundry / Forge` | Solidity 开发与测试 | 单元测试、模糊测试与不变量测试 | Solidity 仓库内紧密的开发者循环 | 应用开发反馈循环和合约测试套件 | | `Slither` | Solidity 和 Vyper 审查 | 静态分析 | 快速的基于检测器的审计分类和代码理解 | 静态审查和 CI 策略门控 | ## Mode 2 证据活动 `campaigns/mode2/patterns/` 是深入的单目标证据通道。这些模式比轻量级的基准测试模板更重，旨在您转向 Mode 3 链式模糊测试之前，暴露出高信号的单电路漏洞。 当前的 Mode 2 包含： - `underconstrained_witness_deep.yaml`：深度的 witness 对搜索加语义交叉检查 - `soundness_forge_deep.yaml`：更深层次的证明伪造和验证可靠性压力测试 当您需要比标准基准测试模板更强的单电路证据和更广泛的攻击覆盖，但还不需要多步协议链时，请使用 Mode 2。对于面向链的工作，请升级到 Mode 3 并参考 [docs/CHAIN_FUZZING_GUIDE.md](docs/CHAIN_FUZZING_GUIDE.md) 中的工作流。 ## 语义分析通道 语义通道作为已提交的活动流程接入仓库中，而不仅仅是一个 crate 示例： - 封装脚本：`scripts/run_semantic_exit_sample.sh` - 提交的执行证据：`campaigns/semantic/semantic_exit_sample.execution_evidence.json` - 运行器：`cargo run -p zk-track-semantic --example semantic_exit_campaign -- ...` - 汇总报告：`artifacts/semantic_exit/latest_report.json` 当安全问题涉及预期行为与接受行为的差异，而不仅仅是约束级别的攻击发现时，请使用此路径。该通道适用于“电路可以编译，witness 满足约束，但接受的行为仍然违反了文档化的安全模型”的情况。 操作员工作流和手动标签精度循环记录在 [docs/SEMANTIC_ANALYSIS_OPERATOR_GUIDE.md](docs/SEMANTIC_ANALYSIS_OPERATOR_GUIDE.md) 和 [campaigns/semantic/README.md](campaigns/semantic/README.md) 中。 ## 环境要求 - Rust 工具链及 Cargo - Node.js 和 `npm`，用于 Circom 相关的测试夹具和本地 JavaScript 依赖 - Z3，用于符号化执行和基于 Solver 的检查 - 根据您运行的目标按需配备后端工具：`circom`、`snarkjs`、`nargo`、`scarb` 和/或 Halo2 Rust 工具链 使用 [docs/TOOLS_AVAILABLE_ON_HOST.md](docs/TOOLS_AVAILABLE_ON_HOST.md) 查看此工作区中已验证的工具清单。 ## 构建与验证 ``` 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` 会安装本地 Circom 测试夹具和基准测试通道所使用的少量依赖项。`node_modules/` 被有意设置为忽略，不应被提交。 当前已验证的 CI 覆盖范围针对 Ubuntu 和 Windows 运行器。在 macOS 的工具链路径恢复之前，它被有意排除在受支持的 CI/构建矩阵之外。 根据需要生成本地 API 文档： ``` cargo doc --workspace --no-deps ``` ## 运行环境 受版本控制的 `config.env.example` 是封装脚本和直接批量运行受支持的基线： ``` cp config.env.example config.env set -a source config.env set +a ``` 它会加载可写的输出根目录、构建缓存路径以及所需的 `zkpatternfuzz` 批量超时设置。仅当您需要不同的本地输出根目录或不同的标准化目标绑定时，才在 `config.env` 中覆盖这些值。 ## 快速开始 生成模式模板： ``` target/release/zk-fuzzer init --output /tmp/zkf_sample.yaml --framework circom ``` 以 dry-run 模式针对本地 Cairo 就绪目标验证真实的扫描： ``` 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 ``` 为遗留活动运行后端预检： ``` target/release/zk-fuzzer preflight campaigns/examples/defi_audit.yaml --setup-keys ``` 列出内置的 CVE 模式： ``` target/release/zk-fuzzer --list-patterns ``` ## 标准化例行运行 对于日常的 `smoke`、`standard` 和 `deep` 运行，请使用固定的封装脚本，而不是重新构建冗长的 CLI 调用： ``` scripts/run_std_smoke.sh scripts/run_std_standard.sh scripts/run_std_deep.sh scripts/monitor_std_run.sh ``` 这些封装脚本的目标绑定是以下三个 `config.env` 键： - `ZKF_STD_TARGET_SMOKE` - `ZKF_STD_TARGET_STANDARD` - `ZKF_STD_TARGET_DEEP` 每个绑定可以是具名的矩阵条目，也可以是直接的目标路径，例如 `/home/teycir/ZkRepos/tornado-core/circuits/withdraw.circom`。当您绑定直接路径且自动检测存在歧义时，请在 `config.env` 中设置配套的 `ZKF_STD_TARGET_*_FRAMEWORK` 和 `ZKF_STD_TARGET_*_MAIN_COMPONENT` 值。 要从实时代码检出（例如 `/home/teycir/ZkRepos`）中发现当前可运行的目标，请使用： ``` 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 ``` 要从干净的候选列表而不是完整的原始清单开始，请使用精心挑选的筛选流程： ``` python3 scripts/curate_zkrepos_targets.py --root /home/teycir/ZkRepos python3 scripts/curate_zkrepos_targets.py --root /home/teycir/ZkRepos --verify --format json ``` 精心挑选的流程会过滤掉框架源码树、工作区聚合、测试/文档/夹具以及不可运行的目标，然后报告每个目标的先决条件和依赖阻塞因素。在当前的活跃代码树中，通过首轮筛选的就绪目标是 `tornado-core/circuits/withdraw.circom` 以及一组 `noir-examples` 的二进制清单；`zkevm-circuits` 保留在候选列表中，但在其 Rust git 依赖项在本地可用之前，将被报告为受阻状态。 这些配置文件的操作契约记录在 [docs/STANDARDIZED_RUN_PROFILES.md](docs/STANDARDIZED_RUN_PROFILES.md) 中。 要针对广泛的生产目录运行全覆盖的单目标活动，请使用： ``` scripts/run_full_coverage_target.sh ``` 除非您覆盖了 `ITERATIONS=...`，否则该运行器默认使用 `/home/teycir/ZkRepos/tornado-core/circuits/withdraw.circom`，使用 `--config-profile prod --alias always`，并且默认迭代次数为 `50000`。 ## 电路生成 `zk-circuit-gen` 是位于模糊测试器旁边的电路生成和编译器测试实验室。它生成敌对电路、基于变异的语料库、语义意图检查、编译器崩溃探针，以及跨 Circom、Noir、Halo2 和 Cairo 的差异编译器/版本矩阵。 有用的入口点： ``` 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 ``` 使用 [docs/CIRCUIT_GEN.md](docs/CIRCUIT_GEN.md) 获取面向操作员的概述和产物布局。 ## 插件 API 通过 `attack-plugins` 特性和示例 crate `crates/zk-attacks-plugin-example` 支持外部攻击插件。简短的契约如下： - 使用 `--features attack-plugins` 构建主机 - 将插件作为 `cdylib` 发布 - 导出 `zk_attacks_plugins` - 实现 `AttackPlugin` 元数据以及 `Attack` 实现 使用 [docs/PLUGIN_API.md](docs/PLUGIN_API.md) 获取最小契约，使用 [docs/PLUGIN_SYSTEM_GUIDE.md](docs/PLUGIN_SYSTEM_GUIDE.md) 了解发现、严格模式行为和安全说明。 ## 直接批量运行 在 source 了 `config.env` 之后，您可以检查目录： ``` target/release/zkpatternfuzz \ --registry targets/fuzzer_registry.prod.yaml \ --alias always \ --jobs 1 \ --workers 2 \ --list-catalog ``` 针对本地 Cairo 就绪目标运行 dry-run 批处理： ``` 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 ``` 批量运行会在 `ZKF_SCAN_OUTPUT_ROOT/ResultJsonTimestamped/` 下写入带有时间戳包，并在 `.scan_run_artifacts/` 下写入每个模板的产物。 ## 本地 Circom 引导 要将本地 Circom 资产暂存到 `./bins` 下： ``` target/release/zk-fuzzer bins bootstrap ``` 这会暂存： - 来自 `PATH` 的 `circom` - 来自 `PATH` 的 `snarkjs` - 来自本地测试夹具的 `pot12_final.ptau` `pot12_final.ptau` 只是一个小型的本地测试夹具。较大的外部 Circom 目标可能需要更大的仪式（ceremony），例如： ``` 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 ``` 当有多个本地 `.ptau` 文件可用时，ZkPatternFuzz 现在会优先选择其幂次足以满足编译后电路要求的文件。 ## 基准测试与仓库检查 基准测试运行器： ``` target/release/zk0d_benchmark --help scripts/run_benchmarks.sh --help ``` 发布门控： ``` scripts/release_candidate_gate.sh --help ``` 仓库策略检查： ``` target/release/zkf_checks --help ``` 生成本地覆盖率产物： ``` cargo llvm-cov --all-features --lcov --output-path lcov.info ``` ## 仓库布局 ``` 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 ``` ## 文档 从以下开始： - [docs/INDEX.md](docs/INDEX.md) - [docs/TUTORIAL.md](docs/TUTORIAL.md) - [docs/TARGETS.md](docs/TARGETS.md) - [docs/TROUBLESHOOTING_PLAYBOOK.md](docs/TROUBLESHOOTING_PLAYBOOK.md) - [docs/BACKEND_SETUP.md](docs/BACKEND_SETUP.md) 操作参考： - [docs/STANDARDIZED_RUN_PROFILES.md](docs/STANDARDIZED_RUN_PROFILES.md) - [docs/TOOLS_AVAILABLE_ON_HOST.md](docs/TOOLS_AVAILABLE_ON_HOST.md) - [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) 验证参考： - [docs/VALIDATION_CORPUS.md](docs/VALIDATION_CORPUS.md) - [docs/VALIDATION_EVIDENCE.md](docs/VALIDATION_EVIDENCE.md) - [docs/GROUND_TRUTH_REPORT.md](docs/GROUND_TRUTH_REPORT.md) - [CVErefs/README.md](CVErefs/README.md) - [campaigns/semantic/README.md](campaigns/semantic/README.md) 历史背景： - [ARCHITECTURE.md](ARCHITECTURE.md) - [ROADMAP.md](ROADMAP.md) - [docs/CIRCUIT_GEN.md](docs/CIRCUIT_GEN.md) - [docs/PLUGIN_API.md](docs/PLUGIN_API.md) ## 署名 项目主页：[teycirbensoltane.tn](https://teycirbensoltane.tn) 联系方式：`teycir@pxdmail.net` ## 许可证 Business Source License 1.1。详情请参阅 [LICENSE](LICENSE)。该许可证在四年后转换为 GPL-3.0。 ## 引用 ``` @software{zkpatternfuzz2024, title={ZkPatternFuzz: A Zero-Knowledge Proof Security Testing Framework}, author={Ben Soltane, Teycir}, year={2024}, url={https://github.com/Teycir/ZkPatternFuzz} } ```

标签：MITM代理, Rust, 可视化界面, 安全测试, 攻击性安全, 网络流量审计, 通知系统, 零知识证明