Veritas-Vaults-Network/Soroban-Guard-Core

# Soroban Guard Core Soroban Guard Core 是一个基于 CLI 的静态分析器，专为通过 Soroban 智能合约平台部署在 **Stellar 网络** 上的 Rust 智能合约设计。它能在你的代码上链之前检测出漏洞。 这是一个三仓库架构中的 **核心引擎**： | 仓库 | URL | |------|-----| | **Core**（本仓库） | [github.com/Veritas-Vaults-Network/Soroban-Guard-Core](https://github.com/Veritas-Vaults-Network/Soroban-Guard-Core) | | **Web dashboard** | [github.com/Veritas-Vaults-Network/Soroban-Guard-web](https://github.com/Veritas-Vaults-Network/Soroban-Guard-web) | | **Contracts** | [github.com/Veritas-Vaults-Network/soroban-guard-contracts](https://github.com/Veritas-Vaults-Network/soroban-guard-contracts) | ## 为什么选择 Soroban Guard？ Soroban 是 Stellar 的智能合约平台 —— 一个基于 WebAssembly 的执行环境，专为速度、低成本和可预测性而设计。但与任何智能合约平台一样，**Soroban 合约中的漏洞可能会在链上被利用，且不可逆转**。 Soroban Guard 可以在源码级别捕获常见的漏洞类型，这一切都在 `stellar contract deploy` 运行之前完成。 ## Stellar / Soroban 背景 Soroban 合约是编译为 WASM 并部署到 Stellar 网络的 Rust crate。本工具解决的关键安全问题： | 问题 | 对 Stellar/Soroban 的影响 | |---|---| | 缺少 `require_auth` | 任何调用者都可以调用特权合约函数 | | 未检查的算术运算 | token 余额或账本计算中的整数溢出/下溢 | | 未受保护的管理员 | admin 密钥可能会在未经授权的情况下被覆盖 | | 不安全的存储模式 | 持久化/临时账本存储的误用 | ## 环境要求 - Rust 1.74+（2021 edition） - 无需 Stellar SDK 或网络连接 —— 分析完全是纯静态的 ## 构建 ``` cargo build --release ``` 二进制文件是 `target/release/soroban-guard`（包名为 `soroban-guard-cli`）。 ## 用法 在部署到 Stellar 之前扫描 Soroban 合约 crate： ``` cargo run -p soroban-guard-cli -- scan ./path/to/contract-crate ``` 输出为 JSON 格式（适用于 CI pipeline 或 web dashboard）： ``` cargo run -p soroban-guard-cli -- scan ./path/to/contract-crate --json ``` ### 退出代码 | 代码 | 含义 | |------|---------| | `0` | 无高严重性发现 —— 可安全执行 | | `1` | 至少有一个高严重性发现 —— **切勿部署** | | `2` | 扫描错误（I/O 或解析失败） | ## Workspace 基础架构 ``` Soroban-Guard-Core/ ├── Cargo.toml # workspace root ├── crates/ │ ├── cli/ # clap entrypoint & reporting │ │ └── src/main.rs │ ├── analyzer/ # walks .rs files, parses with syn, runs checks │ │ └── src/lib.rs │ └── checks/ # Check trait + individual detectors │ └── src/ │ ├── lib.rs # trait definition, Finding, Severity, default_checks() │ ├── auth.rs # missing-require-auth │ ├── overflow.rs # unchecked-arithmetic │ ├── admin.rs # unprotected-admin │ └── storage.rs # unsafe-storage-patterns └── test-contracts/ # standalone Soroban crates (excluded from workspace) ├── vulnerable/ # triggers missing-require-auth ├── safe/ # passes missing-require-auth ├── arithmetic-vulnerable/ ├── arithmetic-safe/ ├── admin-vulnerable/ ├── admin-safe/ ├── storage-vulnerable/ └── storage-safe/ ``` ## 代码片段 ### 存在漏洞的合约 —— 触发 `missing-require-auth` ``` #![no_std] use soroban_sdk::{contract, contractimpl, symbol_short, Env, Symbol}; #[contract] pub struct VulnerableContract; const KEY: Symbol = symbol_short!("counter"); #[contractimpl] impl VulnerableContract { // ❌ No env.require_auth() — anyone on Stellar can call this pub fn bump(env: Env) { let mut n: u32 = env.storage().instance().get(&KEY).unwrap_or(0); n += 1; env.storage().instance().set(&KEY, &n); } } ``` ### 安全的合约 —— 通过 `missing-require-auth` ``` #![no_std] use soroban_sdk::{contract, contractimpl, symbol_short, Address, Env, Symbol}; #[contract] pub struct SafeContract; const KEY: Symbol = symbol_short!("owner"); #[contractimpl] impl SafeContract { // ✅ Caller must be the authorized Address on Stellar pub fn set_owner(env: Env, new_owner: Address) { env.require_auth(); env.storage().instance().set(&KEY, &new_owner); } } ``` ### 添加自定义检查 在 `crates/checks/src/` 中实现 `Check` trait，并在 `default_checks()` 中注册它： ``` use crate::{Check, Finding}; use syn::File; pub struct MyCustomCheck; impl Check for MyCustomCheck { fn name(&self) -> &str { "my-custom-check" } fn run(&self, file: &File, source: &str) -> Vec { // inspect the syn AST and return any findings vec![] } } ``` ``` // crates/checks/src/lib.rs — register it here pub fn default_checks() -> Vec> { vec![ Box::new(MissingRequireAuthCheck), Box::new(UncheckedArithmeticCheck), Box::new(UnprotectedAdminCheck), Box::new(UnsafeStoragePatternsCheck), Box::new(MyCustomCheck), // 👈 add your check ] } ``` ## Stellar 部署工作流 将 Soroban Guard 集成到你的 Stellar 部署 pipeline 中： ``` # 1. 构建前进行分析 cargo run -p soroban-guard-cli -- scan ./my-contract --json > findings.json # 2. 遇到 High 发现时快速失败 (exit code 1) # 3. 构建 WASM artifact cargo build --target wasm32-unknown-unknown --release # 4. 部署到 Stellar Testnet stellar contract deploy \ --wasm target/wasm32-unknown-unknown/release/my_contract.wasm \ --network testnet ``` ## Workspace 布局 | Crate | 作用 | |-------|------| | `crates/cli` | `clap` 入口点、报告生成 | | `crates/analyzer` | 遍历 `.rs` 文件，使用 `syn` 解析，执行检查 | | `crates/checks` | `Check` trait 及各个检测器 | 请参阅 [docs/checks.md](docs/checks.md) 了解已实现的规则，并阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以添加新的检查。 ## 测试 Soroban Guard 分析器为所有已实现的检查提供了全面的测试覆盖。测试嵌入在每个检查模块中，用于验证正向用例（检测到问题）和反向用例（正确忽略无问题项）。 ### 测试涵盖范围 - **150 多项安全检查**：`crates/checks/src/` 中每项检查的单元测试，验证检测器是否能正确识别漏洞并避免误报 - **检查类别**： - 身份验证检查（`auth.rs`、`require_auth` 等） - 存储安全检查（`storage.rs`、`instance_*`、`temp_*` 等） - 算术溢出/下溢检查（`overflow.rs`、`*_mul_overflow` 等） - 管理员/所有者权限检查（`admin.rs`、`ownership_*` 等） - 事件和日志检查（`event_*.rs`、`invoke_store_no_event` 等） - 合约部署和初始化检查（`deploy_*.rs`、`init_*` 等） - 密码学检查（`ed25519_unchecked`、`secp256k1_unchecked` 等） - 以及更多其他检查... ### 运行所有测试 ``` cargo test ``` ### 运行测试并显示输出 查看测试名称和输出（适用于调试）： ``` cargo test -- --nocapture ``` 或者禁用并行执行： ``` cargo test -- --test-threads=1 --nocapture ``` ### 运行特定检查的测试 运行单个检查的测试（例如，`self_transfer` 检查）： ``` cargo test self_transfer ``` 或者运行特定的测试函数： ``` cargo test self_transfer::tests::flags_transfer_without_ne_check ``` ### 在特定 crate 中运行测试 仅测试 `checks` crate： ``` cargo test -p soroban-guard-checks ``` 仅测试 `analyzer` crate： ``` cargo test -p soroban-guard-analyzer ``` ### 测试组织结构 - **`crates/checks/src/`**：每个 `.rs` 文件都实现了一个 `Check` trait，并包含一个带有多个测试函数的 `#[cfg(test)] mod tests {}` 代码块 - **测试命名**：测试通常遵循 `flags_*`、`passes_*`、`ignores_*` 等命名模式，以表明正在验证的行为 - **测试数据**：测试使用 Rust 代码片段（通过 `syn::parse_file`）来模拟智能合约源代码，并验证检测逻辑 ## 许可证 MIT OR Apache-2.0（参见 workspace 的 `Cargo.toml`）。

标签：AI工具, Rust, Stellar, 区块链, 可视化界面, 智能合约, 网络流量审计, 通知系统, 错误基检测, 静态代码分析