Teycir/smartcontractpatternfinder

# 智能合约模式查找器 (SCPF) 🔍 用于检测以太坊智能合约中安全漏洞和模式的高性能工具。 **工作原理：** 在 YAML 模板中定义模式 → SCPF 扫描智能合约 → 查找匹配的模式 → 报告漏洞 [](https://www.rust-lang.org/) [](LICENSE) [](https://crates.io/crates/scpf-cli) [](https://docs.rs/scpf-core) [](https://github.com/Teycir/smartcontractpatternfinder/actions/workflows/ci.yml) **标签：** `rust` `smart-contracts` `security` `scanner` `ethereum` `blockchain` `vulnerability-detection` `pattern-matching` `defi` `web3` `solidity` `static-analysis` `open-source` `mit` ## 📑 目录 - [智能合约模式查找器 (SCPF)](#smart-contract-pattern-finder-scpf) - [📑 目录](#-table-of-contents) - [✨ 功能特性](#-features) - [💡 使用场景](#-use-cases) - [安全审计](#security-auditing) - [DeFi 研究](#defi-research) - [漏洞赏金狩猎](#bug-bounty-hunting) - [开发与 CI/CD](#development--cicd) - [教育与培训](#education--training) - [🚀 快速开始](#-quick-start) - [工作原理](#how-it-works) - [安装说明](#installation) - [初始化项目](#initialize-project) - [扫描合约](#scan-a-contract) - [📋 模板示例](#-template-example) - [🏗️ 架构设计](#️-architecture) - [模块概览](#module-overview) - [🛠️ CLI 命令](#️-cli-commands) - [`scpf scan`](#scpf-scan) - [`scpf init`](#scpf-init) - [🎯 支持的链](#-supported-chains) - [🔧 配置说明](#-configuration) - [获取 API Keys](#getting-api-keys) - [📊 输出格式](#-output-formats) - [🧪 开发指南](#-development) - [📝 创建模板](#-creating-templates) - [模板工作原理](#how-templates-work) - [创建模板](#creating-a-template) - [🤝 参与贡献](#-contributing) - [贡献指南](#contribution-guidelines) - [📄 许可证](#-license) - [👤 作者](#-author) - [🔗 链接](#-links) ## ✨ 功能特性 - 🌐 **以太坊支持** - 通过 Etherscan API 扫描主网合约 - 📁 **本地项目扫描** - 扫描工作区中的 .sol 文件 - 🔄 **Git Diff 扫描** - 仅扫描 PR 中变更的文件 - 🤖 **CI/CD 集成** - 支持 GitHub Actions, GitLab CI, Bitbucket Pipelines - 📝 **YAML 模板** - 易于编写的模式定义 - ✅ **ERC 合规性** - 检测 ERC-20/721/1155 实现 - 📊 **基于大小的风险评分加权** - 按 100KB 归一化，消除大小偏差 - 🧠 **上下文感知过滤** - 通过语义和上下文过滤器减少明显的误报 - ⚡ **分块扫描** - 处理大型源代码而不耗尽内存 - 💾 **智能缓存** - 避免冗余 API 调用 - 🔑 **级联 API Key 系统** - 支持多达 6 个 Key，自动滚动回退 - 🎯 **模块化架构** - CLI、核心引擎、服务器和 Web UI 组件 - 🔒 **安全聚焦** - 专为漏洞分类、报告和基于 SARIF 的代码扫描而构建 - 🚀 **高性能** - 使用 Rust 构建，速度极快 - 🔧 **可扩展** - 轻松添加自定义模式 - 🌐 **可选 Web UI** - `scpf-server` 和 `frontend/` 提供仪表板驱动的工作流 ## 💡 使用场景 ### 安全审计 - **自动化漏洞检测** - 扫描合约中的常见漏洞（重入攻击、delegatecall、未检查调用） - **部署前检查** - 在主网部署前验证合约 - **持续监控** - 监控新部署的易受攻击合约 ### DeFi 研究 - **模式分析** - 识别 DeFi 协议中的常见模式 - **协议比较** - 比较不同项目的安全实现 - **风险评估** - 评估智能合约风险概况 ### 漏洞赏金狩猎 - **自动化侦察** - 快速扫描多个合约以查找漏洞 - **模式发现** - 查找重复出现的漏洞模式 - **批量分析** - 一次扫描整个协议 ### 开发与 CI/CD - **Pre-commit 钩子** - 在提交前验证合约 - **CI/CD 集成** - 在流水线中进行自动化安全检查 - **代码审查** - 通过自动化发现辅助人工代码审查 ### 教育与培训 - **学习工具** - 了解常见的智能合约漏洞 - **模板库** - 研究真实世界的漏洞模式 - **安全培训** - 培训开发人员掌握安全编码实践 ## 🚀 快速开始 ### 工作原理 1. **创建模板** - 在 YAML 文件中定义漏洞模式 2. **加载模板** - SCPF 读取您的模式定义 3. **获取合约** - 从区块链浏览器检索智能合约源代码 4. **扫描与匹配** - 应用正则表达式模式查找漏洞 5. **报告结果** - 显示带有严重级别和上下文的发现 ### 安装说明 ``` git clone https://github.com/Teycir/smartcontractpatternfinder.git cd smartcontractpatternfinder cargo build --release ``` ### 初始化项目 ``` scpf init ``` ### 扫描合约 ``` # 扫描 blockchain contract scpf scan 0x1234567890abcdef --chains ethereum # 扫描本地项目（自动检测 .sol 文件） scpf scan # 仅扫描更改的文件（用于 PR） scpf scan --diff main..HEAD # 使用自定义模板扫描 scpf scan --templates ./my-templates # 扫描多个合约 scpf scan 0xabc... 0xdef... 0x123... --chains ethereum # 导出到 JSON/SARIF scpf scan --output json > results.json scpf scan --output sarif > results.sarif # 将结果限制为 critical findings scpf scan --min-severity critical ``` ## 📋 模板示例 模板定义了在智能合约中搜索的模式。SCPF 加载这些模板并将它们与合约源代码进行匹配。 ``` id: reentrancy-basic name: Basic Reentrancy Pattern description: Detects potential reentrancy vulnerabilities severity: high tags: - security - reentrancy patterns: - id: external-call-with-value pattern: '\.call\{value:' message: External call with value transfer detected - id: delegatecall-usage pattern: '\.delegatecall\(' message: Delegatecall usage detected ``` **执行流程：** 1. SCPF 从 `templates/reentrancy.yaml` 加载此模板 2. 从区块链浏览器获取合约源代码 3. 搜索 `.call{value:` 和 `.delegatecall(` 模式 4. 报告任何匹配项及其行号和上下文 ## 🏗️ 架构设计 ``` smartcontractpatternfinder/ ├── crates/ │ ├── scpf-types/ # Core types and data structures │ ├── scpf-core/ # Scanning, semantic analysis, caching │ ├── scpf-cli/ # Command-line interface │ └── scpf-server/ # Web server and scan orchestration ├── frontend/ # Optional web dashboard ├── templates/ # Pattern detection templates ├── benchmarks/ # Accuracy and SARIF benchmark tooling ├── scripts/ # Utility scripts (.sh, .py) ├── docs/ # Project documentation ├── sol/ # Solidity test files └── action.yml # GitHub Marketplace action definition ``` ### 模块概览 - **scpf-types**: 核心数据结构（Template, Pattern, Match, ScanResult） - **scpf-core**: 业务逻辑（Scanner, TemplateLoader, ContractFetcher, Cache, AST 和语义验证） - **scpf-cli**: 用户界面（CLI 命令、输出格式化） - **scpf-server**: 用于编排扫描和流式传输进度的 HTTP 服务器 - **frontend**: 用于启动扫描和审查结果的浏览器 UI ## 🛠️ CLI 命令 ### `scpf scan` 扫描智能合约中的模式。 ``` scpf scan [OPTIONS] [ADDRESSES]... Options: -n, --chains Comma-separated chain list -t, --templates Templates directory -o, --output

Output format [default: console] --concurrency Concurrent requests [default: 2] --pages Number of explorer pages to fetch [default: 5] --diff Only scan changed files (e.g., main..HEAD) --min-severity Minimum severity to report [default: high] --only-templates Restrict scan to specific template IDs --exclude-templates Exclude specific template IDs --contract-type Filter by contract type (erc20, erc721, erc1155, proxy, defi) --fast Skip semantic analysis for speed --fetch-zero-day Pull recent exploit patterns before scanning --extract-sources Save the top N riskiest sources into the report directory -v, --verbose... Increase verbosity (-v, -vv, -vvv) -h, --help Print help ``` **示例：** ``` # 扫描本地项目 scpf scan # 扫描 blockchain contract scpf scan 0x1234567890abcdef --chains ethereum # 仅扫描更改的文件 scpf scan --diff main..HEAD # 使用自定义模板扫描 scpf scan --templates ./custom-templates # 扫描更多页面 scpf scan --chains ethereum --pages 10 # 将 findings 限制为选定的模板 scpf scan --only-templates reentrancy,delegatecall-user-input # 导出到 SARIF 用于 CI/CD scpf scan --output sarif > results.sarif ``` ### 其他命令 - `scpf audit` 使用相同的扫描参数运行更广泛的审计工作流 - `scpf templates` 列出、显示、安装、更新和浏览模板集合 - `scpf fetch-zero-day` 将最近的漏洞利用情报导入模板 - `scpf pattern-builder` 启动交互式模式助手 ### `scpf init` 初始化一个新的 SCPF 项目。 ``` scpf init [PATH] Options: -y, --yes Skip interactive prompts -h, --help Print help ``` **示例：** ``` # 在当前目录初始化 scpf init # 在特定目录初始化 scpf init ./my-project # 跳过提示 scpf init --yes ``` ## 🎯 支持的链 | 链 | 网络 | API 提供商 | 状态 | |-------|---------|--------------|--------| | **Ethereum** | Mainnet | Etherscan API | ✅ 活跃 | | **BSC** | BNB Smart Chain | BscScan API | 🚧 计划中 | | **Polygon** | Polygon PoS | PolygonScan API | 🚧 计划中 | | **Arbitrum** | Arbitrum One | Arbiscan API | 🚧 计划中 | | **Optimism** | OP Mainnet | Optimistic Etherscan API | 🚧 计划中 | | **Base** | Base Mainnet | BaseScan API | 🚧 计划中 | | **Avalanche** | Avalanche C-Chain | SnowTrace API | 🚧 计划中 | | **Fantom** | Fantom Opera | FtmScan API | 🚧 计划中 | | **Linea** | Linea Mainnet | LineaScan API | 🚧 计划中 | | **Scroll** | Scroll Mainnet | ScrollScan API | 🚧 计划中 | **注意**：目前仅完全支持以太坊主网。多链支持计划在未来版本中推出。有关实现详细信息，请参阅 [链支持状态](docs/CHAIN_SUPPORT_STATUS.md)。 ## 🔧 配置说明 ### API Key 设置 SCPF 使用 Etherscan API 获取合约源代码。通过环境变量配置 API Keys： ``` # Single key（必填） export ETHERSCAN_API_KEY="your-key" # 可选：添加最多 6 个 keys 以实现自动 cascade fallback export ETHERSCAN_API_KEY_2="your-key-2" export ETHERSCAN_API_KEY_3="your-key-3" export ETHERSCAN_API_KEY_4="your-key-4" export ETHERSCAN_API_KEY_5="your-key-5" export ETHERSCAN_API_KEY_6="your-key-6" ``` ### 级联 API Key 系统 SCPF 为 API Keys 实现了**滚动级联回退系统**： 1. **主 Key** - 首先尝试 `ETHERSCAN_API_KEY` 2. **自动轮换** - 如果遇到速率限制或失败，自动尝试下一个 Key 3. **多达 6 个 Keys** - 支持 `ETHERSCAN_API_KEY` 到 `ETHERSCAN_API_KEY_6` 4. **智能重试** - Key 尝试之间有 50ms 延迟 5. **速率限制** - 内置信号量（5 个并发请求） **优势：** - ✅ 避免速率限制错误（Etherscan 免费层：5 次调用/秒） - ✅ 使用多个 Key 提高吞吐量 - ✅ 如果一个 Key 失败，自动故障转移 - ✅ 零配置 - 只需添加更多 Key ### 获取 API Keys - **Etherscan**: https://etherscan.io/apis (免费层：5 次调用/秒) **提示**：创建多个免费 Etherscan 账户以获取 6 个 API Keys，从而实现最大吞吐量（30 次调用/秒）。 ## 📊 输出格式 - **console** - 人类可读的终端输出（默认） - **json** - 机器可读的 JSON - **sarif** - 用于 CI/CD 集成的 SARIF 格式 ## 🤖 CI/CD 集成 ### GitHub Actions 添加到 `.github/workflows/security.yml`： ``` name: Security Scan on: [push, pull_request] jobs: scpf: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - uses: actions/checkout@v4 - uses: teycir/smartcontractpatternfinder@v1 with: severity: high output-format: sarif fail-on-findings: true ``` **功能：** - ✅ 零配置 - ✅ SARIF 集成（结果显示在 Security 选项卡中） - ✅ 缓存安装 - ✅ 可通过 `--min-severity` 自定义严重性阈值 [📖 完整 GitHub Action 文档](docs/GITHUB_ACTION.md) ### GitLab CI ``` scpf-scan: image: rust:latest script: - cargo install scpf-cli - scpf scan --output sarif > results.sarif artifacts: reports: sast: results.sarif ``` [📖 完整 GitLab/Bitbucket 文档](docs/QUICK_WINS.md#4-gitlabbitbucket-ci-integration-) ### Pre-commit 钩子 ``` #!/bin/bash # .git/hooks/pre-commit scpf scan --diff HEAD || exit 1 ``` ## 🧪 开发指南 ``` # 运行测试 cargo test --all # 检查代码 cargo check # 格式化代码 cargo fmt # Lint cargo clippy # 构建 release cargo build --release ``` ## 📝 创建模板 模板是 SCPF 的核心 - 它们定义了在智能合约中查找哪些模式。 ### 模板工作原理 1. **定义模式** - 编写匹配易受攻击代码的正则表达式模式 2. **设置严重性** - 对发现进行分类（info, low, medium, high, critical） 3. **添加上下文** - 为发现提供描述和消息 4. **保存为 YAML** - 存储在 `templates/` 目录中 5. **SCPF 加载并扫描** - 工具自动使用您的模板 ### 创建模板 1. 在 `templates/` 中创建一个 `.yaml` 文件 2. 使用正则表达式定义模式 3. 设置严重级别（info, low, medium, high, critical） 4. 添加描述性标签 **模板结构：** ``` id: unique-template-id name: Human Readable Name description: Detailed description of what this detects severity: high # info | low | medium | high | critical tags: - category - subcategory patterns: - id: pattern-id pattern: 'regex-pattern' message: Description of what was found ``` ## 🤝 参与贡献 欢迎贡献！请遵循： - `.amazonq/rules/` 中的 Amazon Q 规则 - 模块化架构原则 - 测试驱动开发 - 整洁、有文档的代码 ### 贡献指南 1. Fork 本仓库 2. 创建一个功能分支 3. 遵循编码标准 4. 为新功能添加测试 5. 提交 Pull Request ## 📄 许可证 MIT License - 详见 [LICENSE](LICENSE)。 ## 👤 作者 **Teycir Ben Soltane** - 网站: [teycirbensoltane.tn](https://teycirbensoltane.tn) - GitHub: [@Teycir](https://github.com/Teycir) ## 🔗 链接 - [GitHub 仓库]() - [快速制胜功能](docs/QUICK_WINS.md) - ERC 合规性, L2 支持, 风险评分 - [生态与扩展性](docs/ECOSYSTEM.md) - 模板注册表, 插件系统 - [项目路线图](docs/ROADMAP.md) - 未来计划和状态 - [模板更新日志](docs/TEMPLATE_CHANGELOG.md) - 模板版本历史 - [GitHub Action 文档](docs/GITHUB_ACTION.md) - [Issue 跟踪器](https://github.com/Teycir/smartcontractpatternfinder/issues) - [作者网站](https://teycirbensoltane.tn) **由 [Teycir Ben Soltane](https://teycirbensoltane.tn) 使用 Rust 用 ❤️ 构建**

标签：DeFi, EVM, Rust, SARIF, Solidity, Web3, YAML配置, 云安全监控, 以太坊, 区块链, 可视化界面, 文档安全, 智能合约安全, 模式匹配, 网络流量审计, 自动化资产收集, 静态分析