The ultimate smart contract security CLI framework for solo bug bounty researchers
SmartContract VulnHunter orchestrates 15+ industry-leading security scanners, feeds the results to a Large Language Model (LLM) for deep analysis, generates Proof-of-Concept (PoC) exploits, and automatically produces submission-ready reports formatted specifically for major bug bounty platforms.
| Language | Scanners Included | Tool Details |
|---|---|---|
| Solidity | 10 | Slither, Aderyn, Solhint, Semgrep, 4naly3er, Mythril, Echidna, Medusa, Foundry, Heimdall |
| Rust / Solana | 3 | Trident, sec3 X-ray, cargo-audit |
| Vyper | 1 | Vyper (Slither-backed) |
| Cairo | 1 | Caracal |
Total Arsenal: 15 robust adapters ready out-of-the-box.
- Async Execution: Ultra-fast, semaphore-based concurrency wrapper limits performance bottlenecks.
- Auto-Detection: Detects toolsets dynamically based on availability.
- Data Normalization: Converts and normalizes all scanner outputs into valid SARIF format.
- Smart Deduplication: Fingerprint-based duplicate removal to eliminate noise.
- Kimi K2.5 Integration: Operates with OpenAI-compatible APIs dynamically.
- 6-Pass Auditor Pipeline:
- Protocol Understanding
- Attack Surface Mapping
- Invariant Violation Analysis
- Cross-Function Interaction
- Adversarial Modeling
- Boundary & Edge Cases
- Cost Reduction: Intelligent context caching drastically reduces API spend.
- Function Calling: Grants the AI the ability to orchestrate tools autonomously.
- Automatically generates robust Foundry test cases.
- Equipped with smart templates for:
ReentrancyFlash loansOracle manipulationAccess control
- Automated
forge test --jsonvalidation engine triggers autonomous iterative corrections.
Automatically builds the markdown logic specifically suited to individual bug bounty platforms:
- Immunefi: Calculates explicit funds-at-risk.
- Code4rena: Respects the established *High / Medium / QA * split framework.
- Sherlock: Operates on strict impact-based matrices.
- Codehawks: Calculates reports using their standard Impact × Likelihood logic.
pip install vulnhunter-
Initialize your configuration
vulnhunter config init
-
Scan a target codebase
vulnhunter scan ./my-contracts --tools slither,aderyn --parallel 5
-
Generate a formalized platform report
vulnhunter report ./results --platform immunefi --output report.md
-
Prepare an advanced bounty submission
vulnhunter bounty prepare findings.json --platform code4rena --output submission.md
The full docs cover:
- CLI command reference with all flags
- Configuration & LLM provider setup
- 10-phase Recon Engine deep-dive
- Scanner adapter internals
- LLM 6-pass pipeline details
- PoC generation & fork testing
- Platform-specific report formats
- MCP / OpenCode integration
- Knowledge base & methodology
vulnhunter/
├── adapters/ # 15 external tool adapters
├── commands/ # Interactive CLI commands
├── config/ # TOML config & extendable plugin systems
├── core/ # Engine: Tasks, orchestration, SARIF parsing
├── llm/ # Kimi client & 6-pass pipeline
├── models/ # Data models: Findings, Fingerprint maps
├── poc/ # Exploit generator & Foundry runner
└── reporters/ # Markdown generation for target platforms
Create a vulnhunter.toml at the root of your working directory to customize the experience:
[vulnhunter]
debug = false
[vulnhunter.scan]
timeout = 600
max_retries = 3
parallel = 5
[vulnhunter.llm]
api_key = "sk-xxxxxxxxxxxxxxx" # Or use VULNHUNTER_LLM__API_KEY env
model = "kimi-k2.5"Created and maintained by Abdelrehman Fouad.
Catch me online to discuss Web3 security, bug bounties, and AI:
- GitHub: @MaridWSH
- X (Twitter): @AbdelrehmanFou2
This project is for Non-Commercial Use Only. If you want to use it for commercial purposes, you must ask for permission first.