catitodev/stellarvallum

GitHub: catitodev/stellarvallum

一款面向 Stellar + Soroban 生态的测试网优先安全扫描器，集静态漏洞检测、密钥泄露发现与真实测试网对抗攻击测试于一体，帮助开发者在部署前快速发现合约、dApp 和后端中的安全隐患。

Stars: 1 | Forks: 0

**Stellar + Soroban 生态系统的 Testnet-First 安全框架**

[🇧🇷 Português](#-português) · [🇺🇸 English](#-english)

# 🇧🇷 葡萄牙语

## 📖 攻击之前筑起的城墙在每位 Web3 开发者的生命中，都有一个决定“之前”与“之后”的时刻。不是在写下第一行代码时。不是在首次编译时。而是在部署的那一刻——并意识到 **已经没有回头路了**。在区块链上，没有 Ctrl+Z。在 2024 年，由于 122 起 smart contract 事件，损失了 **$905 万**。那些“在测试中运行良好”的合约。那些盲目相信“看起来没问题”的团队。问题不在于你的合约*是否*存在漏洞。而在于*有哪些*漏洞——以及是你先发现它们，还是别有用心的人先发现它们。 **StellarVallum 在两秒钟内就能回答这个问题。** 你打开终端。导航到你的项目目录——Stellar 生态系统中的任何项目。输入一个命令。城墙随之拔地而起。在不到喝一口咖啡的时间里，StellarVallum 已经读取了每个文件，自动检测了项目类型，并应用了对齐 OWASP Smart Contract Top 10 (2026) 的九层验证。它找到了缺少 `require_auth` 的函数。缺少 `checked_add` 的算术。没有 TTL 的 storage。第 47 行硬编码的 API key。但它并不止步于静态分析。**SPEAR**——攻击性武器——会提取你的合约，将其部署到 testnet，并对其发起七种真实类型的攻击。这不是模拟。而是真实的网络上的真实交易，并附带链上证据。而所有这一切的发生，**都不会让你的哪怕一行代码离开你的机器**。因为安全性不是流程末尾的一个复选框。它是你构建的第一件事物。它是先于营地建起的城墙。

``` stellarvallum scan --path . ``` **就这样。城墙拔地而起。**

## 💡 这是什么？ StellarVallum 是一个用于 Stellar + Soroban 生态系统中**任何项目**的**安全扫描器**——包括 smart contract、dApp、后端、API、配置和 CI/CD 流水线。它通过命令行自动检测漏洞、暴露的 secrets 和不良实践。免费、私密且即时。

``` 📂 Seu projeto Soroban → 🔍 stellarvallum scan --path . → 📊 Relatório de segurança ```

### ✨ 亮点 | | 功能 | 描述 | |---|---------|-----------| | 🆓 | **免费** | 无 AI 模式无需 API key | | 🔒 | **私密** | 代码永远不会离开你的机器 | | ⚡ | **快速** | 不到 2 秒完成分析 | | 🎯 | **自动检测** | 自动检测项目类型 | | 🌐 | **多配置文件** | 合约、dApp、后端、配置、流水线 | | 🛡️ | **OWASP** | 对齐 Smart Contract Top 10 (2026) | | 🔑 | **Secrets** | 检测硬编码的密钥和凭证 | | ⚔️ | **对抗性测试** | 在 testnet 上测试 7 种攻击向量 | ## 🏗️ 架构

``` ┌──────────────────────────────────────────────────────────────────┐ │ STELLARVALLUM v0.2.0 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ 🛡️ SHIELD ─── Análise Estática Multi-Perfil │ │ │ ├── 🔐 Access Control (SC01) │ │ │ ├── 📝 Input Validation (SC05) │ │ │ ├── 🔗 Unchecked Calls (SC06) │ │ │ ├── 🧮 Arithmetic Errors (SC07) │ │ │ ├── 🔄 Reentrancy (SC08) │ │ │ ├── ⬆️ Upgradeability (SC10) │ │ │ ├── ⏰ TTL/Archival Risks │ │ │ ├── 💥 Resource Exhaustion │ │ │ └── 🔑 Secret Detection │ │ │ │ │ ⚔️ SPEAR ─── Testes Adversariais na Testnet Real │ │ │ └── 7 vetores: val_injection, auth_bypass, storage, │ │ │ cross_contract, replay, resource, front_running │ │ │ │ │ ⛓️ CHAIN ─── Trilha de Auditoria Imutável (SHA-256) │ │ │ │ │ 📊 DASHBOARD ─── API REST (Axum) │ │ │ │ │ 🤖 AI ─── Opcional: No-AI (padrão) | OpenRouter | Ollama │ │ │ └──────────────────────────────────────────────────────────────────┘ ```

## 📦 安装 ### 前置条件 - 🦀 [Rust 1.74+](https://rust-lang.org/tools/install) - 📋 Git ### 安装 ``` git clone https://github.com/catitodev/stellarvallum.git cd stellarvallum cargo build --release cargo install --path . ``` ### 验证 ``` stellarvallum --version # ⚡ stellarvallum 0.2.0-testnet ``` ## 🚀 使用方法 ### 🔍 自动扫描（推荐）进入你的项目目录并运行： ``` stellarvallum scan --path . ``` StellarVallum **自动检测**项目类型并应用正确的检查： | 检测到的类型 | 何时 | 检查什么 | |----------------|--------|----------------| | 🦀 `Contract` | 包含 `soroban-sdk` 的 `Cargo.toml` | OWASP SC Top 10, TTL, 资源 | | 🌐 `Dapp` | 包含 `react`/`next` + `@stellar/stellar-sdk` 的 `package.json` | 前端 secrets，RPC URL，钱包处理 | | ⚙️ `Backend` | 与 Stellar 交互的 Rust/JS | 无 TLS 的 HTTP，速率限制，密钥处理 | | 📄 `Config` | `.toml`、`.yaml`、`.env` 文件 | 配置中的 secrets，错误的密码短语 | | 🔄 `Pipeline` | `.github/workflows/*.yml` | CI 中的 secrets，未经审批的部署 | ### 📋 示例 ``` # 自动扫描（检测类型） stellarvallum scan --path . # 强制指定 profile stellarvallum scan --path ./src --profile contract # 单文件扫描 stellarvallum scan --path ./src/lib.rs # 保存 JSON 报告 stellarvallum scan --path . -f report.json # 保存 CSV 报告 stellarvallum scan --path . --output csv -f report.csv ``` ### ⚔️ 对抗性测试 (SPEAR) 在 testnet 上部署 + 真实攻击： ``` stellarvallum spear \ --wasm ./target/wasm32-unknown-unknown/release/contrato.wasm \ --secret-key S...YOUR_TESTNET_SECRET_KEY... ```

📋 输出示例

``` ⚔️ SPEAR ADVERSARIAL TESTING ═══════════════════════════════════════ Contract: CABC123... Network: testnet Vectors: 7 [1] val_injection ........... ✅ Resisted [2] auth_bypass ............. ✅ Resisted [3] storage_exhaustion ...... ✅ Resisted [4] cross_contract .......... ✅ Resisted [5] replay_attack ........... ✅ Resisted [6] resource_probing ........ ✅ Resisted [7] front_running ........... ⚠️ Inconclusive ⚔️ CAMPAIGN COMPLETE Vulnerabilities: 0 Status: ✅ All attacks resisted ```

### 🚀 部署到 Testnet ``` stellarvallum deploy-testnet \ --wasm ./target/wasm32-unknown-unknown/release/contrato.wasm \ --secret-key S...YOUR_TESTNET_SECRET_KEY... ``` ### 📊 仪表盘 ``` stellarvallum dashboard # → http://127.0.0.1:8501/api/v1/status ``` | 端点 | 描述 | |----------|-----------| | `GET /api/v1/health` | 健康检查 | | `GET /api/v1/status` | 系统状态，网络，活动模块 | ## 🛡️ 检测到的漏洞 ### Smart Contract (OWASP SC Top 10 2026) | | ID | 漏洞 | 严重性 | |---|---|---|---| | 🔐 | SC01 | 没有 `require_auth` 的函数 | 🔴 严重 | | 📝 | SC05 | 没有 `try_from_val` 的 `from_val`，无限制的 Vec/Map | 🟠 高危 | | 🔗 | SC06 | 没有 return 处理的 `invoke_contract` | 🟠 高危 | | 🧮 | SC07 | 没有零检查的除法，未经检查的算术 | 🟠 高危 | | 🔄 | SC08 | `invoke_contract` 之后修改的状态 | 🔴 严重 | | ⬆️ | SC10 | 没有 auth 的 `update_current_contract_wasm` | 🔴 严重 | | ⏰ | — | 没有 `extend_ttl` 的 storage | 🟠 高危 | | 💥 | — | 没有迭代限制的循环 | 🟠 高危 | | ⚠️ | — | 使用 `panic!` 而不是 `panic_with_error!` | 🟠 高危 | ### Secrets (所有配置文件) | | 类型 | 严重性 | |---|---|---| | 🔑 | Stellar Secret Key (S...) | 🔴 严重 | | 🔑 | OpenRouter/OpenAI API Key | 🔴 严重 | | 🔑 | AWS Access Key | 🔴 严重 | | 🔑 | Private Key (PEM) | 🔴 严重 | | 🔑 | JWT Token | 🟠 高危 | | 🔑 | 硬编码的 password/secret | 🟠 高危 | | 🔑 | Slack Webhook URL | 🟡 中危 | ### dApp / 后端 | | 检查 | 严重性 | |---|---|---| | 🌐 | 硬编码的 RPC URL (没有环境变量) | 🟡 中危 | | 🔓 | Stellar 端点使用无 TLS 的 HTTP | 🟠 高危 | | 🚫 | 无速率限制 | 🟡 中危 | | 💾 | localStorage 中的敏感数据 | 🟠 高危 | | ⚙️ | 没有环境变量的 Secret key | 🟠 高危 | ## 🤖 AI (可选)

模式	成本	隐私	速度
🆓 无 AI (默认)	免费	100%	即时
🌐 OpenRouter	按使用付费	API	~5秒
🏠 本地	免费	100%	~10秒

``` # config/vallum.toml [ai] provider = "none" # Padrão: gratuito e privado # provider = "openrouter" # 可选：多模型 # provider = "local" # 可选：本地 Ollama ``` ## 🔐 项目自身安全性 | | 措施 | 状态 | |---|--------|--------| | 🦀 | `#![forbid(unsafe_code)]` | ✅ | | 🔑 | `Secret` 中的 API key (从不记录日志) | ✅ | | 🔒 | 强制使用 HTTPS/TLS 1.2+ | ✅ | | ✅ | StrKey 验证 (G.../C.../S...) | ✅ | | 🧹 | 针对 injection 消毒过的 CSV | ✅ | | 🛤️ | 已验证防止 traversal 的路径 | ✅ | | 🌐 | 已根据真实 RPC 验证的密码短语 | ✅ | | 🧪 | 21 个自动化测试 | ✅ | ## 💰 获取测试 XLM ``` # 1. 创建 keypair：https://lab.stellar.org/ # 2. 注资（免费）： curl "https://friendbot.stellar.org?addr=G_SEU_ENDERECO" ``` ## 🗺️ 路线图 | 阶段 | 版本 | 状态 | 重点 | |------|--------|--------|------| | 🚧 Beta | v0.2.0 | ✅ 当前 | Testnet，多配置文件，secrets | | 👥 社区 | v0.3.0 | ⏳ | Bug bounty，更多启发式算法 | | 🔍 审计 | v0.4.0 | ⏳ | 外部审计，形式化验证 | | 🌐 主网 | v1.0.0 | ⏳ | 解锁 Mainnet，企业版 | ## 🤝 贡献 ``` git clone https://github.com/catitodev/stellarvallum.git cd stellarvallum cargo build && cargo test ``` **优先领域：** - 🧩 新的检测启发式算法 - 🔗 用于真实部署的完整 XDR 集成 - 🎨 仪表盘前端 - 🧪 使用社区真实合约进行测试 - 🌍 翻译 ## 📄 许可证 Apache License 2.0 — 详见 [LICENSE](LICENSE) ## 🔗 链接 | | 资源 | URL | |---|---------|-----| | 📦 | 仓库 | [github.com/catitodev/stellarvallum](https://github.com/catitodev/stellarvallum) | | 🏛️ | Vallum 原版 | [github.com/catitodev/vallum](https://github.com/catitodev/vallum) | | ⭐ | Stellar 开发者 | [developers.stellar.org](https://developers.stellar.org) | | 📚 | Soroban 文档 | [developers.stellar.org/docs/build/smart-contracts](https://developers.stellar.org/docs/build/smart-contracts/overview) | | 🛡️ | OWASP SC Top 10 | [scs.owasp.org/sctop10](https://scs.owasp.org/sctop10/) |

# 🇺🇸 英语

## 📖 攻击之前筑起的城墙在每位 Web3 开发者的生命中，都有一个决定“之前”与“之后”的时刻。不是在写下第一行代码时。不是在首次编译时。而是在部署的那一刻——并意识到 **已经没有回头路了**。在区块链上，没有 Ctrl+Z。在 2024 年，由于 122 起 smart contract 事件，损失了 **$905 万**。那些“在测试中运行良好”的合约。那些盲目相信“看起来没问题”的团队。问题不在于你的合约*是否*存在漏洞。而在于*有哪些*漏洞——以及是你先发现它们，还是别有用心的人先发现它们。 **StellarVum 在两秒钟内就能回答这个问题。** 你打开终端。导航到你的项目目录——Stellar 生态系统中的任何项目。输入一个命令。城墙随之拔地而起。在不到喝一口咖啡的时间里，StellarVallum 已经读取了每个文件，自动检测了项目类型，并应用了对齐 OWASP Smart Contract Top 10 (2026) 的九层验证。它找到了缺少 `require_auth` 的函数。缺少 `checked_add` 的算术。没有 TTL 的 storage。第 47 行硬编码的 API key。但它并不止步于静态分析。**SPEAR**——攻击性武器——会提取你的合约，将其部署到 testnet，并对其发起七种真实类型的攻击。这不是模拟。而是真实的网络上的真实交易，并附带链上证据。而所有这一切的发生，**都不会让你的哪怕一行代码离开你的机器**。因为安全性不是流程末尾的一个复选框。它是你构建的第一件事物。它是先于营地建起的城墙。

``` stellarvallum scan --path . ``` **就这样。城墙拔地而起。**

``` 📂 Your Soroban project → 🔍 stellarvallum scan --path . → 📊 Security report ```

### ✨ 亮点 | | 功能 | 描述 | |---|---------|-------------| | 🆓 | **免费** | 无 AI 模式无需 API key | | 🔒 | **私密** | 代码永远不会离开你的机器 | | ⚡ | **快速** | 不到 2 秒完成分析 | | 🎯 | **自动检测** | 自动检测项目类型 | | 🌐 | **多配置文件** | 合约、dApp、后端、配置、流水线 | | 🛡️ | **OWASP** | 对齐 Smart Contract Top 10 (2026) | | 🔑 | **Secrets** | 检测硬编码的密钥和凭证 | | ⚔️ | **对抗性测试** | 在 testnet 上测试 7 种攻击向量 | ## 📦 安装 ### 前置条件 - 🦀 [Rust 1.74+](https://rust-lang.org/tools/install) - 📋 Git ### 安装 ``` git clone https://github.com/catitodev/stellarvallum.git cd stellarvallum cargo build --release cargo install --path . ``` ### 验证 ``` stellarvallum --version # ⚡ stellarvallum 0.2.0-testnet ``` ## 🚀 使用方法 ### 🔍 自动扫描（推荐）导航到你的项目目录并运行： ``` stellarvallum scan --path . ``` StellarVallum **自动检测**项目类型并应用正确的检查： | 检测到的类型 | 何时 | 检查什么 | |---------------|------|----------------| | 🦀 `Contract` | 包含 `soroban-sdk` 的 `Cargo.toml` | OWASP SC Top 10, TTL, 资源 | | 🌐 `Dapp` | 包含 `react`/`next` + `@stellar/stellar-sdk` 的 `package.json` | 前端 secrets，RPC URL，钱包处理 | | ⚙️ `Backend` | 与 Stellar 交互的 Rust/JS | 无 TLS 的 HTTP，速率限制，密钥处理 | | 📄 `Config` | `.toml`、`.yaml`、`.env` 文件 | 配置中的 secrets，错误的密码短语 | | 🔄 `Pipeline` | `.github/workflows/*.yml` | CI 中的 secrets，未经审批的部署 | ### 📋 示例 ``` # 自动扫描（检测类型） stellarvallum scan --path . # 强制指定 profile stellarvallum scan --path ./src --profile contract # 单文件扫描 stellarvallum scan --path ./src/lib.rs # 保存 JSON 报告 stellarvallum scan --path . -f report.json # 保存 CSV 报告 stellarvallum scan --path . --output csv -f report.csv ``` ### ⚔️ 对抗性测试 (SPEAR) 在 testnet 上部署 + 真实攻击： ``` stellarvallum spear \ --wasm ./target/wasm32-unknown-unknown/release/contract.wasm \ --secret-key S...YOUR_TESTNET_SECRET_KEY... ```

📋 输出示例

### 🚀 部署到 Testnet ``` stellarvallum deploy-testnet \ --wasm ./target/wasm32-unknown-unknown/release/contract.wasm \ --secret-key S...YOUR_TESTNET_SECRET_KEY... ``` ### 📊 仪表盘 ``` stellarvallum dashboard # → http://127.0.0.1:8501/api/v1/status ``` | 端点 | 描述 | |----------|-------------| | `GET /api/v1/health` | 健康检查 | | `GET /api/v1/status` | 系统状态，网络，活动模块 | ## 🛡️ 检测到的漏洞 ### Smart Contract (OWASP SC Top 10 2026) | | ID | 漏洞 | 严重性 | |---|---|---|---| | 🔐 | SC01 | 没有 `require_auth` 的函数 | 🔴 严重 | | 📝 | SC05 | 没有 `try_from_val` 的 `from_val`，无限制的 Vec/Map | 🟠 高危 | | 🔗 | SC06 | 没有 return 处理的 `invoke_contract` | 🟠 高危 | | 🧮 | SC07 | 没有零检查的除法，未经检查的算术 | 🟠 高危 | | 🔄 | SC08 | `invoke_contract` 之后修改的状态 | 🔴 严重 | | ⬆️ | SC10 | 没有 auth 的 `update_current_contract_wasm` | 🔴 严重 | | ⏰ | — | 没有 `extend_ttl` 的 storage | 🟠 高危 | | 💥 | — | 没有迭代限制的循环 | 🟠 高危 | | ⚠️ | — | 使用 `panic!` 而不是 `panic_with_error!` | 🟠 高危 | ### Secrets (所有配置文件) | | 类型 | 严重性 | |---|---|---| | 🔑 | Stellar Secret Key (S...) | 🔴 严重 | | 🔑 | OpenRouter/OpenAI API Key | 🔴 严重 | | 🔑 | AWS Access Key | 🔴 严重 | | 🔑 | Private Key (PEM) | 🔴 严重 | | 🔑 | JWT Token | 🟠 高危 | | 🔑 | 硬编码的 password/secret | 🟠 高危 | | 🔑 | Slack Webhook URL | 🟡 中危 | ### dApp / 后端 | | 检查 | 严重性 | |---|---|---| | 🌐 | 硬编码的 RPC URL (没有环境变量) | 🟡 中危 | | 🔓 | Stellar 端点使用无 TLS 的 HTTP | 🟠 高危 | | 🚫 | 无速率限制 | 🟡 中危 | | 💾 | localStorage 中的敏感数据 | 🟠 高危 | | ⚙️ | 没有环境变量的 Secret key | 🟠 高危 | ## 🤖 AI (可选)

模式	成本	隐私	速度
🆓 无 AI (默认)	免费	100%	即时
🌐 OpenRouter	按使用付费	API	~5秒
🏠 本地	免费	100%	~10秒

``` # config/vallum.toml [ai] provider = "none" # Default: free and private # provider = "openrouter" # 可选：多模型 # provider = "local" # 可选：本地 Ollama ``` ## 🔐 项目安全性 | | 措施 | 状态 | |---|---------|--------| | 🦀 | `#![forbid(unsafe_code)]` | ✅ | | 🔑 | `Secret` 中的 API key (从不记录日志) | ✅ | | 🔒 | 强制使用 HTTPS/TLS 1.2+ | ✅ | | ✅ | StrKey 验证 (G.../C.../S...) | ✅ | | 🧹 | 针对 injection 消毒过的 CSV | ✅ | | 🛤️ | 已验证防止 traversal 的路径 | ✅ | | 🌐 | 已根据真实 RPC 验证的密码短语 | ✅ | | 🧪 | 21 个自动化测试 | ✅ | ## 💰 获取测试 XLM ``` # 1. 创建 keypair：https://lab.stellar.org/ # 2. 注资（免费）： curl "https://friendbot.stellar.org?addr=G_YOUR_ADDRESS" ``` ## 🗺️ 路线图 | 阶段 | 版本 | 状态 | 重点 | |-------|---------|--------|-------| | 🚧 Beta | v0.2.0 | ✅ 当前 | Testnet，多配置文件，secrets | | 👥 社区 | v0.3.0 | ⏳ | Bug bounty，更多启发式算法 | | 🔍 审计 | v0.4.0 | ⏳ | 外部审计，形式化验证 | | 🌐 主网 | v1.0.0 | ⏳ | 解锁 Mainnet，企业版 | ## 🤝 贡献 ``` git clone https://github.com/catitodev/stellarvallum.git cd stellarvallum cargo build && cargo test ``` **优先领域：** - 🧩 新的检测启发式算法 - 🔗 用于真实部署的完整 XDR 集成 - 🎨 仪表盘前端 - 🧪 使用社区真实合约进行测试 - 🌍 翻译 ## 📄 许可证 Apache License 2.0 — 详见 [LICENSE](LICENSE) ## 🔗 链接 | | 资源 | URL | |---|----------|-----| | 📦 | 仓库 | [github.com/catitodev/stellarvallum](https://github.com/catitodev/stellarvallum) | | 🏛️ | Vallum 原版 | [github.com/catitodev/vallum](https://github.com/catitodev/vallum) | | ⭐ | Stellar 开发者 | [developers.stellar.org](https://developers.stellar.org) | | 📚 | Soroban 文档 | [developers.stellar.org/docs/build/smart-contracts](https://developers.stellar.org/docs/build/smart-contracts/overview) | | 🛡️ | OWASP SC Top 10 | [scs.owasp.org/sctop10](https://scs.owasp.org/sctop10/) |

**⚡ 仅限 TESTNET — Mainnet 支持将在 v1.0 中推出**

_{使用 🦀 Rust 构建 · 由 🛡️ StellarVallum 保护 · 由 ⭐ Stellar 驱动}

标签：AI风险缓解, CI/CD流水线安全, CISA项目, DApp安全, DeFi安全, IP 地址批量处理, Rust, Soroban, Stellar, StruQ, Web3安全, 云安全监控, 代码安全, 加密, 加密货币, 区块链安全, 可视化界面, 后端安全, 安全扫描, 密钥泄露检测, 时序注入, 智能合约审计, 测试网, 测试网优先, 漏洞扫描器, 漏洞枚举, 网络流量审计, 通知系统, 静态分析