Teycir/ZkPatternMatcher

# ZkPatternMatcher 一个轻量级、独立的模式匹配库，用于检测零知识证明电路中的漏洞。 **状态**：稳定的扫描器和 CLI，支持 `regex`、`fancyregex`、`literal` 以及可选的两遍语义检查（`--semantic`）。验证包括基线包（3 个漏洞模式 + 2 个开发者标记）和自动化真实世界矩阵（16 个易受攻击固件 + 10 个安全控制）。有关当前功能的完全透明度，请参阅 [docs/reference/LIMITATIONS.md](docs/reference/LIMITATIONS.md)。 ## 目录 - [ZkPatternMatcher](#zkpatternmatcher) - [目录](#table-of-contents) - [概述](#overview) - [安装](#installation) - [配置](#configuration) - [快速开始](#quick-start) - [验证其有效性：运行验证套件](#prove-it-works-run-validation-suite) - [1. 扫描真实的易受攻击电路](#1-scan-a-real-vulnerable-circuit) - [2. 验证模式](#2-validate-a-pattern) - [3. 列出模式](#3-list-patterns) - [4. JSON 输出](#4-json-output) - [5. 作为库使用](#5-use-as-library) - [模式格式](#pattern-format) - [模式类型](#pattern-types) - [严重级别](#severity-levels) - [模式库](#pattern-library) - [使用案例](#use-cases) - [1. 审计前扫描](#1-pre-audit-scanning) - [2. CI/CD 集成](#2-cicd-integration) - [3. 模式开发](#3-pattern-development) - [4. 批量扫描](#4-batch-scanning) - [5. 差异分析](#5-differential-analysis) - [文档](#documentation) - [贡献](#contributing) - [添加新模式（简单！）](#adding-new-patterns-easy) - [模式来源](#pattern-sources) - [许可证](#license) - [联系方式](#contact) - [引用](#citation) - [相关项目](#related-projects) ## 概述 用于 ZK 电路漏洞检测的模式匹配库。根据 YAML 定义的模式扫描电路代码。 **状态：稳定** - 基线验证稳定（3 个漏洞模式 + 2 个标记），自动化真实世界矩阵目前涵盖 16 个易受攻击固件（+ 10 个安全控制）。 **基线已验证模式：** - ✅ 约束不足的赋值（`<--` 运算符） - ✅ 弱零化器赋值 - ✅ 缺失范围检查（通过注释检测） **开发者标记（非漏洞模式）：** - 🔍 `BUG:` 注释标记 - 🔍 `MISSING:` 约束标记 **⚠️ 重要限制：** - 匹配引擎包括 regex/fancyregex/literal，但默认扫描以语法优先，可能匹配注释/字符串中的标记 - 使用 `--semantic` 启用两遍跨行检查并减少误报 - 不变块已被解析并作为运行时警告显示；计划支持求解器强制执行 - 真实世界语料库正在扩展；自动化矩阵目前包括 16 个易受攻击固件 + 10 个安全控制 - 请参阅 [docs/reference/LIMITATIONS.md](docs/reference/LIMITATIONS.md) 以获取完全透明度 **测试结果：** - `cargo test -q` 本地通过（39 个通过，1 个忽略的集成测试） - 自动化矩阵中验证了 16 个真实世界漏洞固件（+ 10 个安全控制） - 矩阵中的 10 个安全控件上 0 个高/严重误报 - 模式文件：`patterns/real_vulnerabilities.yaml`（5 个条目：3 个模式 + 2 个标记） ## 安装 MSRV：**Rust 1.80+**（在语义分析内部使用 `std::sync::LazyLock`）。 ``` # 从源码安装 cargo install --path . --locked ``` ⚠️ **安全说明**：使用 `--locked` 确保具有固定依赖项的可重现构建。依赖项未在 `Cargo.toml` 中固定 - 请参阅 [docs/reference/LIMITATIONS.md](docs/reference/LIMITATIONS.md#security-considerations)。 ## 配置 通过 `.zkpm.toml` 配置限制（参见 `.zkpm.toml.example`）： - 最大文件大小：10MB - 最大模式文件：1MB - 最大模式数：1000 - 最大匹配数：10000 ## 快速开始 ### 验证其有效性：运行验证套件 ``` # 运行完整验证（core + extended patterns） ./scripts/validate_all.sh # 或仅运行 extended pattern 测试 ./scripts/test_extended_patterns.sh ``` **输出：** ``` ✓ ALL VALIDATION TESTS PASSED Summary: - Rust unit + integration suites passed - Real-world matrix: 16 vulnerable fixtures + 10 safe controls - 0 high/critical false positives on the safe controls - Pattern packs include baseline + extended libraries ``` ### 1. 扫描真实的易受攻击电路 ``` zkpm patterns/real_vulnerabilities.yaml tests/real_vulnerabilities/underconstrained_multiplier.circom ``` **输出：** ``` Found 4 matches: 🔴 [Critical] Unconstrained assignment operator (<--) detected Pattern: underconstrained_assignment Location: 15:7 Matched: <-- ``` ### 2. 验证模式 ``` zkpm validate patterns/underconstrained.yaml ``` ### 3. 列出模式 ``` zkpm list patterns/real_vulnerabilities.yaml ``` **输出：** ``` 🔴 underconstrained_assignment [Critical] - Unconstrained assignment detected 🟠 missing_constraint_comment [High] - Missing constraint Total: 5 patterns ``` ### 4. JSON 输出 ``` zkpm --format json patterns/real_vulnerabilities.yaml tests/real_vulnerabilities/underconstrained_multiplier.circom ``` **输出：** ``` { "matches": [ { "pattern_id": "underconstrained_assignment", "severity": "critical", "message": "Unconstrained assignment detected", "location": { "line": 15, "column": 7 } } ], "summary": { "total": 4, "critical": 3, "high": 1 } } ``` ### 5. 作为库使用 ``` use zk_pattern_matcher::{load_pattern_library, PatternMatcher}; let library = load_pattern_library("patterns/underconstrained.yaml")?; let matcher = PatternMatcher::new(library)?; let matches = matcher.scan_file("circuit.circom")?; for m in matches { println!("{:?}: {}", m.severity, m.message); } ``` ## 模式格式 ``` patterns: - id: unconstrained_assignment kind: regex pattern: '<--' message: 'Unconstrained assignment detected' severity: high ``` ⚠️ **重要：不变量强制执行状态** YAML 模式包含一个 `invariants` 部分。在当前版本中，不变量已被解析并通过运行时警告显示，但尚未由求解器强制执行。将它们视为结构化元数据/检查意图，而非加密证明保证。 ``` # 本节为 schema-level 元数据（当前版本仅 warning-only） invariants: - name: output_fully_constrained invariant_type: constraint relation: "rank(constraint_matrix) == num_signals - 1" oracle: must_hold severity: critical description: "Output signals must be fully constrained" ``` 详情请参阅 [docs/reference/LIMITATIONS.md](docs/reference/LIMITATIONS.md#invariant-system)。 ### 模式类型 - **regex**：正则表达式匹配 - **fancyregex**：高级正则表达式匹配（支持反向引用/环视） - **literal**：精确字符串匹配 - **ast**：保留的模式类型；当前在加载时会显式报错拒绝 ### 严重级别 - **critical**：可利用的漏洞 - **high**：可能存在的漏洞，需要审查 - **medium**：可疑模式 - **low**：代码异味 - **info**：信息提示 ## 模式库 **当前状态：稳定基线 + 扩展矩阵验证（16 个易受攻击固件，10 个安全控制）** ⚠️ **透明度说明**：基线覆盖率在 `real_vulnerabilities.yaml` 中最深。扩展包通过矩阵针对特定固件进行验证，旨在通过审查确认进行实际分类。 基线已验证模式（`patterns/real_vulnerabilities.yaml`）： | 模式 | 状态 | 测试文件 | |---------|--------|----------| | 约束不足的赋值 (`<--`) | ✅ 已验证 | `tests/real_vulnerabilities/underconstrained_multiplier.circom` | | 弱零化器 (`nullifier <--`) | ✅ 已验证 | `tests/real_vulnerabilities/weak_nullifier.circom` | | 缺失范围检查（注释） | ⚠️ 字面匹配 | `tests/real_vulnerabilities/missing_range_check.circom` | 开发者标记（非漏洞模式）： - `BUG:` - 匹配开发者编写的漏洞标记 - `MISSING:` - 匹配约束 TODO 注释 运行 `./scripts/validate.sh` 进行验证。 矩阵验证的扩展检测： | 模式包 | 预期检测 | 固件 | |---------|--------|----------| | `patterns/signal_aliasing.yaml` | `intermediate_array_unconstrained` | `tests/real_vulnerabilities/signal_aliasing.circom` | | `patterns/unchecked_division.yaml` | `division_operator_detected` | `tests/real_vulnerabilities/unchecked_division.circom` | | `patterns/production.yaml` | `vulnerability_marker` | `tests/real_vulnerabilities/nullifier_collision_real.circom` | | `patterns/production.yaml` | `vulnerability_marker` | `tests/real_vulnerabilities/underconstrained_merkle_real.circom` | | `patterns/array_bounds.yaml` | `signal_indexed_array_access` | `tests/real_vulnerabilities/array_no_bounds.circom` | | `patterns/array_bounds.yaml` | `signal_dependent_loop_bound` | `tests/real_vulnerabilities/unbounded_loop.circom` | | `patterns/equality_check.yaml` | `comparison_instead_of_constraint` | `tests/real_vulnerabilities/equality_no_constraint.circom` | | `patterns/merkle_path.yaml` | `merkle_root_comparison_not_constraint` | `tests/real_vulnerabilities/merkle_path/unconstrained_direction_vuln.circom` | | `patterns/commitment_soundness.yaml` | `deterministic_commitment` | `tests/real_vulnerabilities/commitment_soundness/deterministic_commit_vuln.circom` | | `patterns/commitment_soundness.yaml` | `nullifier_without_secret` | `tests/real_vulnerabilities/commitment_soundness/nullifier_no_secret_vuln.circom` | | `patterns/public_input_validation.yaml` | `public_input_declared` | `tests/real_vulnerabilities/nullifier_collision_real.circom` | | `patterns/missing_iszero.yaml` | `direct_zero_comparison_branch` | `tests/real_vulnerabilities/missing_iszero.circom` | **覆盖说明**（参见 [docs/reference/LIMITATIONS.md](docs/reference/LIMITATIONS.md)）： - `patterns/real_vulnerabilities.yaml` 仍然是具有完整端到端验证覆盖的最强基线包。 - 扩展包现在具有针对特定真实世界固件的针对性矩阵测试。 - 验证深度因包而异；矩阵覆盖范围持续扩大。 **模式文件：** - `patterns/real_vulnerabilities.yaml` - 3 个已验证模式 + 2 个开发者标记 - `patterns/production.yaml` - 精选的面向生产的集合，具有针对性的矩阵验证 - `patterns/underconstrained.yaml` - 专注于约束不足赋值规则 - `patterns/signal_aliasing.yaml` - Signal 别名检测（针对性矩阵验证） - `patterns/missing_iszero.yaml` - IsZero 相关检查（针对性矩阵验证） - `patterns/unchecked_division.yaml` - 除零检测（针对性矩阵验证） - `patterns/array_bounds.yaml` - 数组边界检查（针对性矩阵验证） - `patterns/equality_check.yaml` - 等号运算符误用（针对性矩阵验证） - `patterns/merkle_path.yaml` - Merkle 路径验证检查（针对性矩阵验证） - `patterns/commitment_soundness.yaml` - 承诺检查（针对性矩阵验证） - `patterns/public_input_validation.yaml` - 公共输入验证检查（针对性矩阵验证） - `patterns/TEMPLATE.yaml` - 新模式模板 ⚠️ `real_vulnerabilities.yaml` 具有最深的验证覆盖。扩展包已具有针对性的真实世界矩阵验证，更广泛的固件覆盖正在逐步增加。详情请参阅 [patterns/EXTENDED_PATTERNS.md](patterns/EXTENDED_PATTERNS.md)。 请参阅 [docs/patterns/PATTERN_GUIDE.md](docs/patterns/PATTERN_GUIDE.md) 以贡献模式。 ## 使用案例 ### 1. 审计前扫描 ``` # 人工审查前扫描 circuits for circuit in circuits/*.circom; do zkpm --format json patterns/production.yaml "$circuit" >> scan_results.json done ``` ### 2. CI/CD 集成 ``` # .github/workflows/security.yml name: ZK Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: cargo install zkpm --version 0.1.0 # Pin version for reproducibility - run: zkpm patterns/production.yaml circuits/main.circom ``` ### 3. 模式开发 ``` # 将新漏洞编码为 pattern cat > patterns/new_pattern.yaml <> "results/${repo##*/}.json" done done ``` ### 5. 差异分析 ``` # 比较更改前后的扫描结果 git checkout main zkpm --format json patterns/production.yaml circuit.circom > before.json git checkout feature-branch zkpm --format json patterns/production.yaml circuit.circom > after.json diff <(jq -S . before.json) <(jq -S . after.json) ``` ## 文档 完整文档请参阅 [docs/INDEX.md](docs/INDEX.md)。 - **[QUICKSTART.md](docs/guides/QUICKSTART.md)** - 分步教程 - **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - 系统设计 - **[CONTRIBUTING.md](docs/development/CONTRIBUTING.md)** - 贡献指南 - **[SECURITY.md](docs/SECURITY.md)** - 安全策略 - **[CHANGELOG.md](docs/CHANGELOG.md)** - 版本历史 - **[CODE_OF_CONDUCT.md](docs/development/CODE_OF_CONDUCT.md)** - 社区准则 ## 贡献 ### 添加新模式（简单！） **3 步流程：** 1. **复制模板**：`cp patterns/TEMPLATE.yaml patterns/your_pattern.yaml` 2. **填写详细信息**：使用您的漏洞模式编辑 YAML 3. **测试**：`zkpm validate patterns/your_pattern.yaml` 详细说明和示例请参阅 [docs/patterns/PATTERN_GUIDE.md](docs/patterns/PATTERN_GUIDE.md)。 **快速示例：** ``` patterns: - id: your_vulnerability kind: regex pattern: 'vulnerable_code_pattern' message: 'What this detects' severity: high ``` 欢迎所有贡献。完整指南请参阅 [CONTRIBUTING.md](docs/development/CONTRIBUTING.md)。 ## 模式来源 - zkB 数据集 - 公开审计报告 - CVE 数据库 ## 许可证 MIT - 详情请参阅 [LICENSE.md](LICENSE.md)。 ## 联系方式 **Teycir Ben Soltane** 邮箱：teycir@pxdmail.net 网站：https://teycirbensoltane.tn ## 引用 ``` @software{zkpatternmatcher2025, title={ZkPatternMatcher: Pattern-Based Vulnerability Detection for Zero-Knowledge Proofs}, author={Ben Soltane, Teycir}, year={2025}, url={https://github.com/Teycir/ZkPatternMatcher} } ``` ## 相关项目 - **[HoneypotScan](https://github.com/Teycir/honeypotscan)** - 智能合约蜜罐检测 - **[Sanctum](https://github.com/Teycir/Sanctum)** - 隐私优先的安全工具 - **[GhostChat](https://github.com/Teycir/GhostChat)** - 安全消息平台 - **[Timeseal](https://github.com/Teycir/Timeseal)** - 时间戳和验证

标签：Rust, TLS, Web3安全, YAML配置, ZK, 云安全监控, 代码安全, 区块链安全, 可视化界面, 安全工程, 安全扫描, 形式化验证, 文档结构分析, 无服务器架构, 时序注入, 模式匹配, 漏洞枚举, 电路审计, 网络流量审计, 自动化资产收集, 通知系统, 通知系统, 防御工具, 零知识证明, 静态分析, 预审计