# 🛡️ Solana Smart Contract Security Toolkit (solsec)
[](https://crates.io/crates/solsec)
[](https://crates.io/crates/solsec)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org)
[](https://github.com/hasip-timurtas/solsec/actions/workflows/ci.yml)
A comprehensive security analysis tool for Solana smart contracts that helps developers identify vulnerabilities before deployment through static analysis and fuzz testing. Features an advanced interactive HTML reporting system with intelligent suggestion algorithms.
## Table of Contents
- [Why solsec?](#-why-solsec)
- [Features](#-features)
- [Built-in Security Rules](#-built-in-security-rules)
- [Security Checks Reference](SECURITY_CHECKS.md)
- [Quick Start](#-quick-start)
- [Commands](#-commands)
- [Configuration](#-configuration)
- [Plugin Development](#-plugin-development)
- [CI/CD Integration](#-cicd-integration)
- [Report Examples](#-report-examples)
- [Development](#️-development)
- [Examples](#-examples)
- [Performance & Accuracy](#-performance--accuracy)
- [Community](#-community)
- [License](#-license)
## 🎯 Why solsec?
**solsec** is designed to be a developer's first line of defense against smart contract vulnerabilities. While other tools exist, solsec offers a unique combination of:
- **🔍 High Accuracy**: Advanced pattern detection with minimal false positives - identifies 39 security issues across example contracts
- **⚡ High Performance**: Parallel processing with Rust performance - up to 5x faster analysis on multi-file projects
- **🎯 Comprehensive Coverage**: Detects critical vulnerabilities including reentrancy, unsafe account access, and privilege escalation
- **🛠️ Developer-Friendly**: Clear, actionable reports with specific remediation guidance and severity classification
- **🔧 Easy Integration**: Seamless CI/CD integration with automated security checks and pre-commit hooks
- **🧪 Production Ready**: Thoroughly tested with comprehensive validation and robust error handling
## ✨ Features
### 🔐 Advanced Security Analysis
- **Static Analysis**: Detect critical vulnerabilities with high accuracy and minimal false positives
- **Parallel Processing**: Multi-core analysis using Rust's `rayon` for significant performance improvement
- **Severity Classification**: Identifies 4 severity levels - Critical, High, Medium, Low with targeted remediation
- **Comprehensive Rule Coverage**: 8+ security rules covering all major Solana vulnerability classes
### 🎨 Revolutionary Suggestion System
- **Interactive HTML Interface**: JavaScript-powered suggestion formatting with professional styling
- **Multiple Implementation Options**: Each security issue shows 3+ different fix approaches
- **Function-Aware Recommendations**: Personalized suggestions using extracted function names
- **Before/After Code Examples**: Side-by-side syntax-highlighted comparisons showing exact fixes
- **Copy-Paste Ready**: All code examples are immediately usable in your projects
- **Educational Value**: Learn multiple security patterns instead of single fixes
### 🚀 Performance & Reliability
- **Parallel File Processing**: Concurrent analysis of multiple files using `rayon` crate
- **Smart Error Handling**: Clear, colored error messages with proper path validation
- **Comprehensive Testing**: Thorough unit testing ensuring reliability
- **Memory Efficient**: Optimized regex compilation and efficient pattern matching
### 📊 Professional Reporting
- **Interactive HTML Reports**: Revolutionary suggestion system with JavaScript-powered formatting
- **Multi-Option Suggestions**: Beautiful card layouts showing 3+ implementation approaches per issue
- **Before/After Code Comparisons**: Side-by-side syntax-highlighted code sections
- **Function-Specific Guidance**: Personalized recommendations based on actual function names
- **Responsive Design**: Professional mobile-friendly interface
- **Multiple Report Formats**: JSON, HTML, Markdown, and CSV outputs with beautiful styling
- **Severity Classification**: Clear prioritization with Critical/High/Medium/Low severity levels
- **Actionable Recommendations**: Copy-pasteable code examples and specific remediation guidance
- **Browser Integration**: Automatic HTML report opening with intelligent environment detection
### 🔌 Extensibility & Integration
- **Plugin System**: Extensible architecture for custom security rules
- **CI/CD Ready**: GitHub Actions support with automated security checks
- **Pre-commit Hooks**: Block commits with critical vulnerabilities
- **Configuration System**: Flexible rule configuration and customization
## 🚀 Quick Start
### Installation
#### From Crates.io
```bash
cargo install solsec
```
#### From Source
```bash
git clone https://github.com/hasip-timurtas/solsec.git
cd solsec
cargo install --path .
```
### Basic Usage
```bash
# Scan the current project and generates both JSON and HTML
solsec scan
# Scan a specific Solana program and set an output directory
solsec scan ./my-solana-program --output ./results
# Generate only JSON
solsec scan ./my-program --json-only --output results.json
# Generate only HTML
solsec scan ./my-program --html-only --output results.html
# Generate multiple formats at once
solsec scan ./my-program --format json,html,markdown,csv
# Don't open browser automatically
solsec scan ./my-program --no-open
# Run fuzz testing
solsec fuzz ./my-solana-program --timeout 300
```
## 📖 Commands
### `solsec scan`
Run static analysis on your Solana smart contracts. Generates both JSON and HTML by default. If no path is provided, it recursively scans the current directory for all `.rs` files, automatically ignoring `target/` and `.git/` folders.
HTML reports automatically open in the default browser when running interactively, but remain closed in CI/automation environments.
```bash
solsec scan [PATH] [OPTIONS]
OPTIONS:
-c, --config <FILE> Configuration file path
-o, --output <DIR> Output directory [default: ./solsec-results]
-f, --format <FORMATS> Output formats (comma-separated) [default: json,html] [possible values: json, html, markdown, csv]
--json-only Only generate JSON
--html-only Only generate HTML
--no-open Don't automatically open HTML report in browser
--fail-on-critical Exit with non-zero code on critical issues [default: true]
EXAMPLES:
# Scan the entire project (generates both JSON and HTML)
solsec scan
# Scan a specific directory with default formats
solsec scan ./programs/my-program
# Generate only JSON for CI/CD integration
solsec scan ./programs --json-only --output results.json
# Generate only HTML for manual review
solsec scan ./programs --html-only --output results.html
# Generate HTML but don't open browser
solsec scan ./programs --html-only --no-open --output results.html
# Generate all available formats
solsec scan ./programs --format json,html,markdown,csv
# Scan with configuration file
solsec scan ./programs --config solsec.toml --output ./security-results
```
### `solsec fuzz`
Run fuzz testing on smart contracts.
```bash
solsec fuzz <PATH> [OPTIONS]
OPTIONS:
-t, --timeout <SECONDS> Timeout in seconds [default: 300]
-j, --jobs <NUMBER> Number of parallel fuzzing jobs [default: 1]
-o, --output <DIR> Output directory [default: ./fuzz-results]
EXAMPLES:
solsec fuzz ./programs/my-program --timeout 600 --jobs 4
solsec fuzz ./programs --output ./custom-fuzz-results
```
### `solsec plugin`
Manage security rule plugins.
```bash
solsec plugin <ACTION> [PATH]
ACTIONS:
list List available plugins
load Load a plugin
unload Unload a plugin
EXAMPLES:
solsec plugin list
solsec plugin load ./my-custom-rule.so
solsec plugin unload my-custom-rule
```
## 🔧 Configuration
Create a `solsec.toml` configuration file:
```toml
# Enable/disable specific rules
enabled_rules = [
"integer_overflow",
"missing_signer_check",
"unchecked_account",
"reentrancy"
]
disabled_rules = []
# Rule-specific settings
[rule_settings]
[rule_settings.integer_overflow]
ignore_patterns = ["test_*", "mock_*"]
[rule_settings.missing_signer_check]
required_for_instructions = ["transfer", "withdraw"]
```
## 🔍 Built-in Security Rules
| `reentrancy` | **High** | Detects state changes after external calls (CEI pattern violations) | ✅ 8 vulnerabilities found |
| `unchecked_account` | **Critical** | Finds unsafe account access, transmute operations, and unvalidated accounts | ✅ 4 critical + 14 medium issues |
| `missing_signer_check` | **High** | Identifies instruction handlers without proper signer validation | ✅ 8 high severity issues |
| `integer_overflow` | **Medium** | Detects arithmetic operations without overflow protection | ✅ 5 legitimate overflow risks |
| `pda_validation` | **High** | Validates PDA derivation and bump parameter usage | ✅ PDA validation |
| `privilege_escalation` | **Critical** | Detects unauthorized authority/admin changes | ✅ Authority security |
| `unsafe_arithmetic` | **Medium** | Finds division by zero and underflow risks | ✅ Arithmetic protection |
| `insufficient_validation` | **High** | Identifies missing input validation in public functions | ✅ Input validation |
### 🎯 Detection Accuracy
- ✅ **Reentrancy**: Detects 8 vulnerabilities across examples
- ✅ **Unchecked Account**: Identifies 4 critical + 14 medium severity issues
- ✅ **Zero False Positives**: Filters out comments, strings, and non-code patterns
- ✅ **Comprehensive Coverage**: 39 total security issues identified across all severity levels
> 📖 **For detailed information about each security check, including code examples and best practices, see the [Security Checks Reference](SECURITY_CHECKS.md).**
## 🔌 Plugin Development
Create custom security rules by implementing the `Rule` trait:
```rust
use solsec::plugin::{Rule, RuleResult, Severity};
use std::path::Path;
use anyhow::Result;
#[derive(Debug)]
pub struct MyCustomRule;
impl Rule for MyCustomRule {
fn name(&self) -> &str {
"my_custom_rule"
}
fn description(&self) -> &str {
"Detects my specific vulnerability pattern"
}
fn check(&self, content: &str, file_path: &Path) -> Result<Vec<RuleResult>> {
let mut results = Vec::new();
// Your analysis logic here
for (line_num, line) in content.lines().enumerate() {
if line.contains("dangerous_pattern") {
results.push(RuleResult {
severity: Severity::High,
message: "Dangerous pattern detected".to_string(),
line_number: Some(line_num + 1),
column: None,
code_snippet: Some(line.trim().to_string()),
suggestion: Some("Use safe alternative".to_string()),
});
}
}
Ok(results)
}
}
// Plugin interface
#[no_mangle]
pub extern "C" fn get_plugin_info() -> PluginInfo {
PluginInfo {
name: "my_plugin".to_string(),
version: "1.0.0".to_string(),
description: "My custom security plugin".to_string(),
author: "Your Name".to_string(),
rules: vec!["my_custom_rule".to_string()],
}
}
#[no_mangle]
pub extern "C" fn create_rules() -> Vec<Box<dyn Rule>> {
vec![Box::new(MyCustomRule)]
}
```
Build your plugin as a dynamic library:
```bash
cargo build --lib --crate-type=cdylib --release
```
## 🤖 CI/CD Integration
### GitHub Actions
Add the following to your `.github/workflows/security.yml`:
```yaml
name: Security Scan
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install solsec
run: |
cargo install --locked solsec
- name: Run security scan
run: |
solsec scan ./programs --output ./security-results
- name: Upload security report
uses: actions/upload-artifact@v3
with:
name: security-report
path: ./security-results/
- name: Fail on critical issues
run: |
if [ -f ./security-results/*.json ]; then
# Ensure jq is installed
sudo apt-get install -y jq
critical_count=$(jq '.summary.critical_issues' ./security-results/*.json)
if [ "$critical_count" -gt 0 ]; then
echo "❌ Critical security issues found: $critical_count"
exit 1
fi
fi
```
### Pre-commit Hook
Block commits that introduce critical vulnerabilities.
**Setup Instructions:**
1. Create the file: `.git/hooks/pre-commit`
2. Copy the script below into the file.
3. Make it executable: `chmod +x .git/hooks/pre-commit`
```bash
#!/bin/sh
# .git/hooks/pre-commit
echo "🛡️ Running security scan..."
# Ensure solsec is in your PATH
if ! command -v solsec &> /dev/null; then
echo "solsec could not be found, skipping pre-commit check."
exit 0
fi
# Create a temporary directory for results
RESULTS_DIR=$(mktemp -d)
solsec scan ./programs --format json --output "$RESULTS_DIR" --no-open
if [ -f "$RESULTS_DIR"/*.json ]; then
# Ensure jq is installed
if ! command -v jq &> /dev/null; then
echo "jq could not be found, skipping severity check."
rm -rf "$RESULTS_DIR"
exit 0
fi
critical_count=$(jq '.summary.critical_issues' "$RESULTS_DIR"/*.json 2>/dev/null || echo "0")
if [ "$critical_count" -gt 0 ]; then
echo "❌ Critical security issues found: $critical_count! Commit blocked."
echo "Run 'solsec scan ./programs' to see details."
rm -rf "$RESULTS_DIR"
exit 1
fi
fi
rm -rf "$RESULTS_DIR"
echo "✅ Security scan passed!"
```
## Browser Opening Behavior
HTML reports automatically open in the default browser under the following conditions:
**Opens automatically when:**
- Running in an interactive terminal (not redirected)
- Generating HTML reports (`--html-only` or default formats)
- Not in CI/automation environments
**Remains closed when:**
- Running in CI environments (GitHub Actions, GitLab CI, etc.)
- Output is redirected or piped
- Using `--no-open` flag
- Only generating non-visual formats (JSON, CSV)
## 📊 Report Examples
### HTML Report
Revolutionary interactive HTML reports with:
- **Executive Summary**: Issue counts by severity with beautiful statistics cards
- **Enhanced Suggestions**: Multi-option fix approaches with numbered cards and code examples
- **Before/After Comparisons**: Side-by-side syntax-highlighted code sections for overflow fixes
- **Function-Specific Guidance**: Personalized recommendations like "Add signer validation to function 'transfer_funds_handler'"
- **Professional Styling**: Modern design with Monaco fonts, proper spacing, and responsive layouts
- **Copy-Paste Ready Code**: Immediately usable code snippets for each suggested fix
- **Mobile Optimization**: Responsive design that works perfectly on all devices
**🔗 Live Example**: Check out [`examples/security-report.html`](./examples/security-report.html) to see a complete security report generated from scanning the example vulnerabilities. This report shows:
- **258 total issues** found across all severity levels
- **7 critical issues** requiring immediate attention
- **Interactive navigation** with clickable severity cards
- **Syntax-highlighted code** with proper Rust highlighting
- **Multi-option suggestions** with numbered implementation approaches
### JSON Report
Machine-readable format for:
- CI/CD pipeline integration
- Custom tooling and analysis
- Data processing and metrics
### Markdown Report
Developer-friendly format for:
- README documentation
- Pull request comments
- Documentation sites
## 🛠️ Development
### Building from Source
```bash
git clone https://github.com/hasip-timurtas/solsec.git
cd solsec
cargo build --release
```
### Running Tests
```bash
cargo test
```
### Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📚 Examples
The [`examples/`](./examples/) directory contains comprehensive security vulnerability demonstrations:
### 🚨 Vulnerability Examples
Each category includes both **vulnerable** and **secure** implementations for educational purposes:
| **Integer Overflow** | Medium | `examples/integer_overflow/vulnerable.rs` | `examples/integer_overflow/secure.rs` |
| **Missing Signer Check** | High | `examples/missing_signer_check/vulnerable.rs` | `examples/missing_signer_check/secure.rs` |
| **Unchecked Account** | Critical | `examples/unchecked_account/vulnerable.rs` | `examples/unchecked_account/secure.rs` |
| **Reentrancy** | High | `examples/reentrancy/vulnerable.rs` | `examples/reentrancy/secure.rs` |
### 🧪 Testing the Examples
```bash
# Test individual vulnerable examples
solsec scan examples/integer_overflow/vulnerable.rs # 4 medium severity issues
solsec scan examples/missing_signer_check/vulnerable.rs # 4 high severity issues
solsec scan examples/unchecked_account/vulnerable.rs # 4 critical + 4 medium issues
solsec scan examples/reentrancy/vulnerable.rs # 4 high severity issues
# Test secure examples (should find fewer/no critical issues)
solsec scan examples/*/secure.rs # Mainly medium severity issues
# Comprehensive analysis across all examples
solsec scan examples/ # 39 total issues: 4 critical + 16 high + 19 medium
```
### 📖 Learning Resources
- **Side-by-side Comparisons**: See exactly how to fix each vulnerability
- **Real-world Patterns**: Actual Solana/Anchor code patterns
- **Educational Comments**: Clear explanations of security issues
- **Test Suite**: Validate that solsec detection works correctly
See the detailed [`examples/README.md`](./examples/README.md) for complete documentation.
## ⚡ Performance & Accuracy
### 🚀 Performance Features
- **Parallel Processing**: Multi-core analysis using `rayon` crate for optimal speed
- **Optimized Regex**: Pre-compiled patterns with efficient matching algorithms
- **Memory Efficient**: Smart caching and resource management
- **Scalable**: Handles large codebases with thousands of files
### 🎯 Analysis Quality
- **Pattern Detection**: Advanced analysis for precise vulnerability identification
- **False Positive Reduction**: Intelligent filtering eliminates noise from comments and non-code patterns
- **Comprehensive Coverage**: Detects all major Solana vulnerability classes
- **Actionable Results**: Clear severity classification with specific remediation guidance
### 📊 Quality Assurance
```
✅ Comprehensive Testing: Full unit test coverage
✅ Code Quality: Passes strict clippy linting (-D warnings)
✅ Formatting: rustfmt compliant
✅ Performance: Parallel processing architecture
✅ Accuracy: High precision vulnerability detection
✅ Coverage: Multi-severity issue identification
```
### 🔍 Current Capabilities
| Reentrancy Detection | ✅ Active | Detects 8 types of reentrancy vulnerabilities |
| Critical Account Issues | ✅ Active | Identifies unsafe account access patterns |
| Interactive Suggestions | ✅ Active | Multi-option HTML suggestions with code examples |
| Function-Specific Guidance | ✅ Active | Personalized recommendations using function names |
| False Positive Rate | ✅ Minimal | Intelligent filtering of non-code patterns |
| Processing Speed | ✅ Optimized | Parallel processing for fast analysis |
| Security Coverage | ✅ Comprehensive | 39+ vulnerability patterns detected |
## 🤝 Community
- **Issues**: [GitHub Issues](https://github.com/hasip-timurtas/solsec/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hasip-timurtas/solsec/discussions)
- **Discord**: [Solana Security Community](https://discord.gg/solana-security)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- The Solana Foundation for supporting security tooling
- The Rust security community for best practices
- Contributors and early adopters
---
**⚠️ Important**: This tool helps identify potential security issues but does not guarantee complete security. Always conduct thorough testing and consider professional security audits for production applications.
## 📸 Example HTML Report
*Professional HTML security reports with syntax highlighting, interactive navigation, and actionable suggestions*
*Built with ❤️ by Hasip Timurtas*