Al-Gharbi/smart-audit

## 什么是 smart-audit？ `smart-audit` 是一个使用 Go 编写的**零依赖 CLI 工具**，可对 Solidity 智能合约执行静态安全分析。它能检测 **18 类漏洞** —— 从经典的 reentrancy 到 DeFi 特有的闪电贷预言机操纵 —— 并生成 HTML、JSON 和 Markdown 格式的专业审计报告。 专为安全研究人员、DeFi 开发人员和 CI/CD pipeline 打造。无需任何设置，只需一个二进制文件即可运行。 ``` $ smart-audit scan ./contracts/ -r -f html -o audit-report.html ┌─────────────────────────────────────────────────┐ │ 🔒 SMART-AUDIT v1.0.0 │ │ Smart Contract Security Auditor │ └─────────────────────────────────────────────────┘ → Discovered 3 Solidity contract(s) ───────────────────────────────────────────────── AUDIT SUMMARY 7 finding(s) in 3 contract(s) ───────────────────────────────────────────────── CRITICAL 2 HIGH 3 MEDIUM 2 LOW 0 INFO 0 ───────────────────────────────────────────────── ⚠ VulnerableVault.sol [7 finding(s) · Risk 8.0/10] [CRITICAL] Reentrancy Vulnerability (line 22) [HIGH] tx.origin Authentication (line 28) ... ✓ Report saved → audit-report.html ``` ## 功能 - **🔍 18 条漏洞规则** — 涵盖 OWASP 智能合约安全 Top 10 + DeFi 特有风险 - **📊 3 种报告格式** — 包含可展开发现的独立 HTML、结构化 JSON、适配 GitHub 的 Markdown - **⚡ 零依赖** — 单个静态二进制文件，无 runtime 要求 - **🎯 风险评分** — 针对每个合约的加权风险评分（0–10） - **🔗 Slither 集成** — 安装 Slither 后，可进行更深入的 dataflow 分析 - **🐳 Docker 支持** — 可在任何容器化环境中运行 - **⚙️ CI/CD 就绪** — 可与 GitHub Actions、GitLab CI 和 pre-commit hooks 集成 - **🌐 跨平台** — 预编译版本支持 Linux、macOS（Intel + Apple Silicon）、Windows ## 安装说明 ### 预编译二进制文件（推荐） 从 [Releases](https://github.com/Al-Gharbi/smart-audit/releases/latest) 下载适合您平台的二进制文件： ``` # Linux (amd64) curl -L https://github.com/Al-Gharbi/smart-audit/releases/latest/download/smart-audit-linux-amd64 \ -o smart-audit && chmod +x smart-audit && sudo mv smart-audit /usr/local/bin/ # macOS (Apple Silicon) curl -L https://github.com/Al-Gharbi/smart-audit/releases/latest/download/smart-audit-darwin-arm64 \ -o smart-audit && chmod +x smart-audit && sudo mv smart-audit /usr/local/bin/ # 验证 smart-audit version # smart-audit 1.0.0 ``` ### 从源码构建（需要 Go 1.21+） ``` git clone https://github.com/Al-Gharbi/smart-audit.git cd smart-audit make install ``` ### Docker ``` docker pull algharbi/smart-audit:latest docker run --rm -v $(pwd):/data algharbisec/smart-audit \ scan /data/ -r -f html -o /data/audit-report.html ``` ## 使用说明 ``` smart-audit scan [options] [...] Options: -f, --format Report format: html | json | md (default: html) -o, --output Output file path -r, --recursive Scan directories recursively -s, --min-severity Minimum severity: critical|high|medium|low|info --slither Enable Slither integration -v, --verbose Verbose output -h, --help Show help ``` ### 示例 ``` # 扫描单个文件 smart-audit scan Token.sol # 递归扫描所有合约，生成 HTML 报告 smart-audit scan ./contracts/ -r -f html -o report.html # 仅报告 High 和 Critical 发现 smart-audit scan ./src/ -r -s high # 用于程序化处理的 JSON 输出 smart-audit scan Vault.sol -f json | jq '.summary' # 用于 GitHub PR 评论的 Markdown 报告 smart-audit scan ./contracts/ -r -f md -o SECURITY.md # 使用 Slither 进行更深入的污点分析 smart-audit scan ./contracts/ -r --slither # 扫描特定文件 smart-audit scan Token.sol Vault.sol Staking.sol -f html ``` ## 报告格式 ### HTML 报告 独立的交互式报告，包含可展开的发现、严重性徽章、代码片段和修复指南。  ### JSON 报告 ``` { "report_id": "SA-20250701-143022", "title": "Smart Contract Security Audit Report", "timestamp": "2025-07-01 14:30:22 UTC", "duration": "12ms", "summary": { "total_contracts": 2, "total_findings": 7, "critical": 2, "high": 3, "medium": 2, "overall_risk": "CRITICAL" }, "contracts": [...] } ``` ### Markdown 报告 非常适合用于 GitHub PR 描述和文档。示例输出： | 严重性 | 数量 | |---|---| | 🔴 Critical | 2 | | 🟠 High | 3 | | 🟡 Medium | 2 | ## 漏洞数据库 | ID | 标题 | 严重性 | SWC | |----|-------|----------|-----| | SA-001 | Reentrancy | 🔴 Critical | [SWC-107](https://swcregistry.io/docs/SWC-107) | | SA-002 | tx.origin Authentication | 🟠 High | [SWC-115](https://swcregistry.io/docs/SWC-115) | | SA-003 | Floating Pragma | 🔵 Low | [SWC-103](https://swcregistry.io/docs/SWC-103) | | SA-004 | Unprotected selfdestruct | 🔴 Critical | [SWC-106](https://swcregistry.io/docs/SWC-106) | | SA-005 | Block Timestamp Dependence | 🟡 Medium | [SWC-116](https://swcregistry.io/docs/SWC-116) | | SA-006 | Delegatecall Injection | 🟠 High | [SWC-112](https://swcregistry.io/docs/SWC-112) | | SA-007 | Unchecked Call Return Value | 🟡 Medium | [SWC-104](https://swcregistry.io/docs/SWC-104) | | SA-008 | Weak PRNG | 🟠 High | [SWC-120](https://swcregistry.io/docs/SWC-120) | | SA-009 | Deprecated Functions | 🔵 Low | [SWC-111](https://swcregistry.io/docs/SWC-111) | | SA-010 | Missing Zero Address Check | 🟡 Medium | [SWC-131](https://swcregistry.io/docs/SWC-131) | | SA-011 | Integer Overflow (< 0.8.0) | 🟠 High | [SWC-101](https://swcregistry.io/docs/SWC-101) | | SA-012 | Inline Assembly | 🟡 Medium | [SWC-127](https://swcregistry.io/docs/SWC-127) | | SA-013 | Hard-coded Address | 🔵 Low | [SWC-134](https://swcregistry.io/docs/SWC-134) | | SA-014 | Flash-Loan Oracle Manipulation | 🟠 High | custom | | SA-015 | Unchecked Arithmetic Block | 🟡 Medium | SWC-101 | | SA-016 | Missing Event Emission | 🔵 Low | custom | | SA-017 | Signature Replay | 🟠 High | [SWC-121](https://swcregistry.io/docs/SWC-121) | | SA-018 | DoS via Unbounded Loop | 🟡 Medium | [SWC-128](https://swcregistry.io/docs/SWC-128) | ## CI/CD 集成 ### GitHub Actions 添加到 `.github/workflows/security.yml`： ``` name: Smart Contract Security Audit on: push: paths: ['contracts/**', 'src/**'] pull_request: paths: ['contracts/**', 'src/**'] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install smart-audit run: | curl -L https://github.com/Al-Gharbi/smart-audit/releases/latest/download/smart-audit-linux-amd64 \ -o smart-audit && chmod +x smart-audit - name: Run security audit run: ./smart-audit scan ./contracts/ -r -s medium -f md -o AUDIT.md - name: Upload audit report uses: actions/upload-artifact@v4 with: name: security-audit-report path: AUDIT.md - name: Comment PR with findings if: github.event_name == 'pull_request' uses: actions/github-script@v7 with: script: | const fs = require('fs'); const report = fs.readFileSync('AUDIT.md', 'utf8'); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: report.slice(0, 65000) }); ``` ### Hardhat 集成 添加到 `hardhat.config.js`： ``` task("audit", "Run smart-audit on contracts", async () => { const { execSync } = require("child_process"); execSync("smart-audit scan ./contracts/ -r -f html -o audit-report.html", { stdio: "inherit" }); }); ``` ``` npx hardhat audit ``` ### Pre-commit Hook ``` # .git/hooks/pre-commit #!/bin/bash smart-audit scan ./contracts/ -r -s high if [ $? -ne 0 ]; then echo "❌ Security audit failed. Fix High/Critical findings before committing." exit 1 fi ``` ## 工作原理 smart-audit 使用多阶段分析 pipeline： ``` Solidity Files │ ▼ Strip Comments ──► prevents false positives from commented code │ ▼ Pattern Matching ──► 18 regex rules against clean source │ ▼ Context Analysis ──► maps matches to line numbers + snippets │ ▼ Risk Scoring ──► weighted formula: score = (max×0.6) + (avg×0.4) │ ▼ Report Generation ──► HTML / JSON / Markdown ``` ### 添加自定义规则 ``` // internal/analyzer/patterns.go var Patterns = []Pattern{ // ... existing patterns ... { ID: "SA-019", Title: "My Custom Rule", Description: "Description of what this detects.", Severity: "HIGH", SWC: "custom", Recommendation: "How to fix it.", Regex: regexp.MustCompile(`your_regex_here`), }, } ``` ## 可选：Slither 集成 如需更深入的 dataflow 和污点分析： ``` # 安装 Slither pip install slither-analyzer # 使用 Slither 运行 smart-audit scan ./contracts/ -r --slither ``` smart-audit 在没有 Slither 的情况下也能完全独立运行 —— 它完全是可选的。 ## 开发 ``` make build # Build binary make test # Run tests with race detector make release # Cross-compile for all platforms make docker # Build Docker image make help # Show all targets ``` ### 运行测试 ``` go test ./... -race -cover # 预期输出： # --- PASS: TestReentrancy (0.00s) # --- PASS: TestTxOrigin (0.00s) # --- PASS: TestFloatingPragma (0.00s) # ... 14 tests total # coverage: 78.4% of statements ``` ## 路线图 - [ ] SA-019：中心化风险检测 - [ ] SA-020：Chainlink 预言机陈旧度检查 - [ ] SA-021：ERC20 approval front-running - [ ] Foundry 项目集成 - [ ] 用于 GitHub Security 标签页的 SARIF 输出格式 - [ ] VS Code 扩展 ## 许可证 MIT © [Al-Gharbi](https://github.com/Al-Gharbi)

**如果 smart-audit 帮助您发现了一个 bug，请给该仓库点个 ⭐。** 由来自也门 🇾🇪 的一位安全研究员制作

标签：EVTX分析, Go, Ruby工具, Solidity, 云安全监控, 区块链安全, 日志审计, 智能合约审计, 请求拦截, 静态分析