Soroban Guard is a static analysis and security auditing toolchain for Soroban smart contracts — the Rust-based smart contract platform on the Stellar network. It analyzes Rust source code to detect common security vulnerabilities before deployment, providing actionable feedback through multiple output formats and CI/CD integrations.
This repository contains the analysis engine and CLI. Run it directly from the terminal, or wire it into CI/CD and editors via its SARIF output — see Integrations.
- Features
- Installation
- Usage
- Output Formats
- Configuration
- Rules Overview
- Security Scoring
- Integrations
- Documentation
- Development
- Contributing
- License
- Reentrancy Detection — Identifies state-after-call patterns, read-only reentrancy, missing guards, and cross-function reentrancy (R-01 to R-04).
- Arithmetic Overflow & Underflow — Detects unchecked operations on
i128/u128and other financial integer types (O-01 to O-05). - Access Control Analysis — Finds functions missing authorization checks, hardcoded addresses, and overly permissive visibility (A-01 to A-05).
- Storage Collision Detection — Prevents short or generic key names, type mismatches, and instance-vs-temporary access conflicts (S-01 to S-05).
- Security Scoring — Computes a 0–100 score with letter grades (A–F) and a severity breakdown for quick triage.
- Multiple Output Formats — Human-readable terminal output, structured JSON, and SARIF for GitHub Code Scanning.
- CI/CD Ready — Exits with code 1 when critical or high severity findings are present.
- Configurable — TOML-based configuration with exclusion patterns and output controls.
cargo install soroban-guard-coreThis installs the soroban-guard binary. See the crates.io page for releases and version history.
git clone https://github.com/Soroban-Guard/Core.git
cd Core
cargo build --release
./target/release/soroban-guard --help- Rust 1.85 or newer (MSRV)
- No external runtime dependencies — the binary is self-contained
# Scan a single file
soroban-guard ./contracts/my_contract.rs
# Scan an entire directory
soroban-guard ./contracts/
# Scan with JSON output
soroban-guard --format json ./contracts/
# Generate SARIF report for GitHub Code Scanning
soroban-guard --sarif --output results.sarif ./contracts/
# Filter by minimum severity
soroban-guard --min-severity high ./contracts/
# Exclude test files and fixtures
soroban-guard --exclude "**/test_*, **/fixtures/*" ./contracts/
# Use a configuration file
soroban-guard --config soroban-guard.toml ./contracts/| Option | Short | Description |
|---|---|---|---|
| PATH | | File or directory to scan (multiple allowed) |
| --format | -f | Output format: human, json, sarif (default: human) |
| --min-severity | -m | Minimum severity to report: info, low, medium, high, critical (default: low) |
| --output | -o | Write output to a file |
| --exclude | | Glob patterns to exclude (comma-separated) |
| --jobs | | Number of parallel workers (default: 4) |
| --all | | Enable all rule families (on by default; narrow with --rules or config) |
| --rules | | Comma-separated finding rule IDs to show (e.g. R-01,S-02) |
| --sarif | | Shorthand for --format sarif |
| --config | | Path to TOML configuration file |
Colored terminal output with findings grouped by severity, including rule IDs, file locations, descriptions, and remediation suggestions.
Soroban Guard Report
====================
Security Score: 72/100 (Grade B)
Critical: 1 | High: 2 | Medium: 3 | Low: 5 | Info: 2
Top issues: Function 'withdraw' writes to storage after an external call — reentrancy risk
Total files analyzed: 1
File: src/contract.rs
Score: 72/100 (Grade B)
CRITICAL:
[R-01] Function 'withdraw' writes to storage after an external call — reentrancy risk
Location: Vault:42:5
Suggestion: Move state updates before the external call, or use a reentrancy guard
HIGH:
[A-01] Function 'reset' modifies state without authorization check
Location: Vault:78:1
Suggestion: Add require_auth() with the appropriate Address at the start of this function
[...]
Structured output suitable for programmatic consumption:
{
"tool": "soroban-guard",
"version": "0.1.0",
"reports": [
{
"contract": "Vault",
"file": "src/contract.rs",
"score": {
"overall": 72,
"grade": "B",
"breakdown": { "critical": 1, "high": 2, "medium": 3, "low": 5, "info": 2 },
"top_issues": []
},
"findings": [
{
"severity": "critical",
"rule_id": "R-01",
"message": "Function 'withdraw' writes to storage after an external call — reentrancy risk",
"location": "Vault:42:5",
"suggestion": "Move state updates before the external call, or use a reentrancy guard"
}
],
"bonuses": { "reentrancy_guard": false, "version_key": true }
}
],
"total_score": {
"overall": 72,
"grade": "B",
"breakdown": { "critical": 1, "high": 2, "medium": 3, "low": 5, "info": 2 },
"top_issues": []
},
"summary": "Security Score: 72/100 (Grade B)\nCritical: 1 | High: 2 | Medium: 3 | Low: 5 | Info: 2\nTop issues: ",
"bonuses": { "reentrancy_guard": false, "version_key": true }
}Static Analysis Results Interchange Format — OASIS standard for static analysis tool output. Compatible with GitHub Code Scanning, Azure DevOps, and other SARIF consumers.
soroban-guard --sarif --output results.sarif ./contracts/Create a soroban-guard.toml file in your project root:
[general]
exclude = ["**/test_*", "**/fixtures/*"]
jobs = 4
[output]
format = "human"
min_severity = "low"
[rules.reentrancy]
enabled = true
severity = "high"
[rules.storage]
enabled = falseConfiguration file can be passed via --config.
| ID | Rule | Severity | Description |
|---|---|---|---|
| R-01 | Reentrancy | Critical | Storage write after an external call (checks-effects-interactions violation) |
| R-02 | Read-only reentrancy | Medium | External call between a storage read and write of the same key |
| R-03 | Missing reentrancy guard | Low | External calls found but no reentrancy guard storage key detected |
| R-04 | Cross-function reentrancy | High | Two externally-calling functions share a storage key |
| O-01 | Unchecked arithmetic | High | Unchecked +, -, * on i128/u128 types |
| O-02 | Threshold comparison | Medium | Arithmetic compared against a threshold without overflow protection |
| O-03 | Division by non-literal | Medium | Division or remainder by a non-literal divisor |
| O-04 | Loop accumulation | High | Compound accumulation inside a dynamically-bounded loop |
| O-05 | Truncating cast | Low | Narrowing cast from financial value to a smaller integer type |
| A-01 | Missing authorization | Critical/High | State-mutating function without access control |
| A-02 | Admin function | High | Admin-only function without authorization |
| A-03 | Delegate auth | Medium | require_auth_for_args used without direct require_auth |
| A-04 | Public callable | High/Medium/Info | Public function with no address parameter or auth check |
| A-05 | Hardcoded address | Medium | Hardcoded contract addresses that should be configurable |
| S-01 | Short storage key | Medium | Storage key ≤ 2 characters, risk of collision |
| S-02 | Generic key name | Low | Common key names like "balance", "owner" without namespacing |
| S-03 | Type mismatch | High | Same key written with different value types across functions |
| S-04 | Storage tier conflict | High | Same key accessed via both instance and temporary storage |
| S-05 | Missing version key | Info | No version key found — risk during contract upgrades |
The scoring engine starts at 100 and deducts points based on finding severity:
| Severity | Deduction |
|---|---|
| Critical | −30 |
| High | −15 |
| Medium | −7 |
| Low | −3 |
| Info | −1 |
Bonus points are awarded for defensive patterns:
| Condition | Bonus |
|---|---|
| Reentrancy guard storage key present | +5 |
| Version storage key present | +3 |
| Range | Grade |
|---|---|
| 90–100 | A |
| 70–89 | B |
| 50–69 | C |
| 30–49 | D |
| 0–29 | F |
The report includes up to five top critical/high findings for immediate triage.
Use the CLI in any CI pipeline and upload a SARIF report for GitHub Code Scanning:
- run: cargo install soroban-guard-core
- run: soroban-guard --sarif --output results.sarif ./contracts/
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: soroban-guard
name: Soroban Guard
entry: soroban-guard
language: system
files: '\.rs$'Run the analyzer from a build task to generate a JSON report as you edit. See docs/integrations.md for a ready-to-use tasks.json snippet.
- Getting Started — A walkthrough of installation, first scan, and understanding results.
- CLI Usage — Complete CLI reference with examples.
- Configuration — Detailed configuration file reference.
- Integrations — Setup guides for GitHub Actions, VS Code, and CI/CD pipelines.
- Architecture — Overview of the codebase structure and data flow.
- Changelog — Version history and release notes.
- Sample Contracts — Realistic Soroban contracts that demonstrate real findings across every rule family.
- Reentrancy Rules — R-01 through R-04
- Overflow Rules — O-01 through O-05
- Access Control Rules — A-01 through A-05
- Storage Rules — S-01 through S-05
cargo build
cargo build --releasecargo test # Unit and integration tests
cargo bench # Criterion benchmarks
cargo clippy # Lint
cargo fmt # Formatsrc/
├── main.rs # CLI entry point
├── lib.rs # Library root with public re-exports
├── config.rs # TOML config parsing and CLI config merge
├── error.rs # Unified error types
├── scoring.rs # Security scoring engine
├── parser/
│ ├── mod.rs # ContractParser — parses source into Contract AST
│ ├── ast.rs # AST types (Contract, ContractFn, FnBodyAnalysis)
│ ├── patterns.rs # Soroban-specific pattern matchers
│ └── visitors.rs # syn-based AST visitor
├── analysis/
│ ├── mod.rs # AnalysisEngine, AnalysisRule trait
│ ├── reentrancy.rs # R-01 to R-04 rules
│ ├── overflow.rs # O-01 to O-05 rules
│ ├── access_control.rs # A-01 to A-05 rules
│ └── storage.rs # S-01 to S-05 rules
└── report/
├── mod.rs # Report data structures
├── finding.rs # Finding data structure
├── severity.rs # Severity enum
└── output.rs # Human, JSON, and SARIF formatters
Contributions are welcome. Please see the Contributing Guide for details on:
- Code style and conventions
- Pull request process
- Testing requirements
- Adding new analysis rules
This project is developed as part of the Stellar Wave Program on Drips — a recurring contribution sprint for the Stellar open-source ecosystem.
Licensed under the MIT License.