Nanle-code/clarus

# Clarus Clarus 可在部署前检测 `.clar` 文件中的常见漏洞模式 —— 为开发者提供快速、可操作的反馈，而无需进行全面审计。 ## 为什么选择 Clarus？ Clarity 的设计初衷是安全的 —— 但安全设计并不意味着没有漏洞。随着 Stacks 生态系统的发展和 sBTC 将真实的比特币流动性带入 DeFi，单个漏洞的风险急剧上升。 Clarus 填补了一个空白：**目前还没有专门针对 Clarity 的静态分析工具**。Clarus 旨在成为 Stacks 生态系统中的 Slither。 ## 检测器 | ID | 严重程度 | 描述 | |----|----------|-------------| | `reentrancy` | 🔴 严重 | 在 `stx-transfer?`、`contract-call?` 或其他外部交互之后发生的状态更改 | | `access-control` | 🔴 高 | 修改状态但未检查 `tx-sender` 或 `contract-caller` 的 Public 函数 | | `integer-underflow` | 🟠 高 | 在没有前置边界检查的情况下对 `uint` 进行减法运算 | | `integer-overflow` | 🔵 低 | 没有上限验证的加法运算 | | `unchecked-returns` | 🟡 中 | 未使用 `try!` 或 `unwrap!` 包装返回值的外部调用 | ## 安装 ### 从源码安装 ``` git clone https://github.com/Nanle-code/clarus.git cd clarus cargo build --release ``` 二进制文件将位于 `./target/release/clarus`。 （可选）全局安装，以便您可以从机器上的任何位置运行 `clarus`： ``` cargo install --path . ``` ## 使用方法 ``` # 分析当前目录中的合约 clarus mycontract.clar # 分析系统上任意位置的合约 clarus /path/to/contract.clar # 输出为 JSON（用于 CI/CD pipelines） clarus mycontract.clar --json # 如果发现问题则以代码 1 退出（用于 CI/CD gates） clarus mycontract.clar --strict ``` ## 测试外部合约 Clarus 适用于您系统上任何位置的任何 `.clar` 文件 —— 不仅仅是 Clarus 项目文件夹中的合约。 **在开发期间（全局安装之前）：** ``` # 使用 cargo run 分析任意合约 cargo run -- ~/Desktop/mycontract.clar cargo run -- ~/projects/my-stacks-app/contracts/vault.clar # 使用 flags cargo run -- ~/Desktop/mycontract.clar --json cargo run -- ~/Desktop/mycontract.clar --strict ``` **直接使用 release 二进制文件：** ``` # 首先构建 optimized binary cargo build --release # 然后将其指向任意合约 ./target/release/clarus ~/Desktop/mycontract.clar ./target/release/clarus ~/projects/stacks-defi/contracts/pool.clar ``` **全局安装后：** ``` # 从机器上的任意目录运行 clarus clarus ~/Desktop/mycontract.clar clarus ~/projects/stacks-defi/contracts/pool.clar clarus ~/projects/stacks-defi/contracts/pool.clar --json ``` ## 示例输出 ``` Clarus — Clarity Smart Contract Analyzer Analyzing: vault.clar ──────────────────────────────────────────────────────────── [1] [CRITICAL] Reentrancy Function : withdraw Location : Line 8 Issue : 'map-set' called after external interaction on line 6 Fix : Move 'map-set' to before the external call on line 6 ──────────────────────────────────────────────────────────── [2] [HIGH] Missing Access Control Function : deposit Location : Line 3 Issue : Public function 'deposit' modifies state without access control check Fix : Add (asserts! (is-eq tx-sender contract-owner) (err u403)) at the top ──────────────────────────────────────────────────────────── Result : 2 total findings 1 critical 1 high ``` ## CI/CD 集成 将 Clarus 添加到您的 GitHub Actions 工作流中： ``` - name: Run Clarus run: | cargo install --path . clarus contracts/vault.clar --strict ``` `--strict` 标志会导致 Clarus 在检测到任何发现时以代码 `1` 退出，这将使工作流失败并阻止 pull request。 ## 漏洞模式 ### 重入攻击 (Reentrancy) 最关键的模式。当合约在更新自身状态之前执行外部调用（`stx-transfer?`、`contract-call?` 等）时，恶意合约可以重新进入并利用陈旧的状态。 **有漏洞：** ``` (define-public (withdraw (amount uint)) (begin (stx-transfer? amount (as-contract tx-sender) tx-sender) ;; external call first (map-set balances tx-sender u0) ;; state update after — dangerous )) ``` **安全（检查-生效-交互模式）：** ``` (define-public (withdraw (amount uint)) (begin (map-set balances tx-sender u0) ;; state update first (try! (stx-transfer? amount (as-contract tx-sender) tx-sender)) (ok true) )) ``` ### 未检查的返回值 在没有 `try!` 的情况下调用 `stx-transfer?` 或 `contract-call?` 意味着失败会被静默忽略，执行将继续进行。 **有漏洞：** ``` (stx-transfer? amount (as-contract tx-sender) tx-sender) (map-delete balances tx-sender) ``` **安全：** ``` (try! (stx-transfer? amount (as-contract tx-sender) tx-sender)) (map-delete balances tx-sender) ``` ## 项目结构 ``` clarus/ ├── src/ │ ├── main.rs — CLI entry point │ ├── ast.rs — AST node definitions │ ├── parser.rs — Clarity S-expression parser │ ├── analyzer.rs — Orchestrates all detectors │ ├── reporter.rs — Terminal and JSON output │ └── detector/ │ ├── mod.rs │ ├── reentrancy.rs — Reentrancy detector │ ├── integer_overflow.rs │ ├── access_control.rs │ └── unchecked_returns.rs └── tests/ └── contracts/ ├── vulnerable.clar ├── safe.clar └── bug.clar ``` ## 路线图 ### 阶段 1 — MVP ✅ - 单文件分析 - 重入检测 - 整数下溢/上溢 - 访问控制 - 未检查的返回值 - 带有 JSON 输出和严格模式的 CLI ### 阶段 2 - 多文件 / 多合约分析 - 基于 Trait 的动态分发检测 - 调用图可视化 - Clarinet 插件集成 ### 阶段 3 - GitHub Action - VS Code 扩展 - 基于 Web 的演练场 - 公共 Clarity 漏洞数据库 ## 贡献 Clarus 是开源的，欢迎贡献。如果您发现 Clarus 遗漏的 Clarity 漏洞模式，请提交一个包含最小复现合约的 issue。 ## 许可证 MIT

标签：Clarity, DeFi安全, pocsuite3, Rust, sBTC, Stacks, Streamlit, 云安全监控, 区块链安全, 可视化界面, 威胁情报, 开发者工具, 整数溢出, 文档结构分析, 智能合约审计, 网络流量审计, 访问控制, 软件测试, 通知系统, 通知系统, 通知系统, 重入攻击, 静态分析