https://github.com/holasoymalva/gemini-bug-hunter
Gemini Bug Hunter is an AI-first CLI tool that helps developers find, understand, and fix security vulnerabilities in their codebases using Gemini 3 (Next Gen) as the core intelligence engine.
https://github.com/holasoymalva/gemini-bug-hunter
agent agentic-ai agents cybersecurity cybersecurity-tools gemini gemini-ai gemini-api gemini-cli gemini-pro hacking hacking-tool llm llms
Last synced: 3 months ago
JSON representation
Gemini Bug Hunter is an AI-first CLI tool that helps developers find, understand, and fix security vulnerabilities in their codebases using Gemini 3 (Next Gen) as the core intelligence engine.
- Host: GitHub
- URL: https://github.com/holasoymalva/gemini-bug-hunter
- Owner: holasoymalva
- License: cc0-1.0
- Created: 2026-01-16T00:48:28.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-31T22:21:59.000Z (5 months ago)
- Last Synced: 2026-02-01T10:19:05.600Z (5 months ago)
- Topics: agent, agentic-ai, agents, cybersecurity, cybersecurity-tools, gemini, gemini-ai, gemini-api, gemini-cli, gemini-pro, hacking, hacking-tool, llm, llms
- Language: JavaScript
- Homepage: https://holasoymalva.github.io/gemini-bug-hunter/
- Size: 267 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 🛡️ Gemini Bug Hunter
### AI-Powered Security Vulnerability Hunter (CLI)
> **Gemini Bug Hunter** is an AI-first CLI tool that helps developers **find, understand, and fix security vulnerabilities** in their codebases using **Gemini 2.5 and Gemini 3 (Next Gen) as the core intelligence engine**.
Inspired by tools like **Gemini-CLI** and **Claude-Code**, Gemini Bug Hunter brings **ethical hacking and AppSec workflows** directly into the developer terminal.
---
## 🚀 Vision
Security tools are often:
* Too noisy
* Too complex
* Too disconnected from developer workflows
**Gemini Bug Hunter** solves this by using **Gemini 2.5 and Gemini 3 (Next Gen) as the main reasoning engine** to:
* Understand code context
* Detect vulnerabilities
* Explain real-world risks
* Propose secure fixes
* Apply safe auto-remediations
---
## 🧠 Core Principle
> **Gemini 3 is not an assistant — it is the brain of the system.**
All vulnerability analysis, risk reasoning, and fix generation are driven by Gemini 3.
---
## 🛠️ Tech Stack
* **Node.js** (v18+)
* **JavaScript (ES2022+)**
* **Gemini 2.5 Flash and Gemini 3** (Next Gen Analysis Engine)
* **Premium CLI Experience** (ASCII Art, Animations, Gradients)
* CLI Framework: `commander`
* Output Styling: `chalk`, `cli-table3`, `boxen`
* File traversal: `glob`
* Config: `.env` + `default.js`
---
## 📦 Installation
### Prerequisites
- Node.js 18 or higher
- Gemini API Key ([Get one here](https://aistudio.google.com/app/apikey))
- **Gemini Model**: Uses `gemini-2.5-flash` by default (configurable)
### Setup
```bash
# Clone the repository
git clone https://github.com/holasoymalva/gemini-bug-hunter.git
cd gemini-bug-hunter
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Test installation
npm start doctor
```
### Global Installation
To use `gbh` from anywhere in your terminal:
```bash
# 1. Install globally
npm install -g gemini-bug-hunter
# 2. Set your API Key globally (Run once)
gbh config set-key
# 3. Ready to scan!
gbh scan
```
---
## 🧪 CLI Commands
### Scan for Vulnerabilities
```bash
# Scan current directory
gbh scan
# Scan specific file or directory
gbh scan ./src
# Output to JSON file
gbh scan --output report.json
# JSON output to stdout
gbh scan --json
# Interactive Auto-Fix Mode
gbh scan --fix
```
> **Note**: The `--fix` option will interactively prompt you to apply AI-generated fixes for each vulnerability found.
### Check System Health
```bash
gbh doctor
```
### View Configuration
```bash
gbh config
```
### Explain Vulnerability
```bash
gbh explain "SQL Injection"
gbh explain "XSS"
```
---
## 🔍 How It Works
1. **Collect** - Scans project files based on configured patterns
2. **Sanitize** - Redacts secrets and sensitive data
3. **Analyze** - Sends code to Gemini 3 with structured prompts
4. **Parse** - Extracts structured vulnerability data
5. **Score** - Calculates risk scores using weighted algorithms
6. **Report** - Displays beautiful, actionable reports
---
## 🤖 Gemini 3 Integration
### System Prompt
Gemini receives a carefully crafted system prompt that instructs it to:
- Act as a professional ethical hacker
- Focus on OWASP Top 10 vulnerabilities
- Avoid false positives
- Return structured JSON responses
- Provide actionable recommendations
### Response Schema
```json
{
"projectRiskScore": 0-100,
"riskLevel": "LOW|MEDIUM|HIGH|CRITICAL",
"summary": "string",
"vulnerabilities": [
{
"id": "string",
"title": "string",
"severity": "LOW|MEDIUM|HIGH|CRITICAL",
"confidence": 0-1,
"category": "string",
"file": "string",
"line": number,
"description": "string",
"impact": "string",
"exploitationScenario": "string",
"recommendation": "string",
"secureCodeExample": "string",
"autoFixSafe": boolean
}
]
}
```
---
## 📊 Risk Scoring
The tool calculates risk scores using:
- **Severity** (40% weight) - CRITICAL, HIGH, MEDIUM, LOW
- **Confidence** (30% weight) - How certain is the detection
- **Exploitability** (20% weight) - How easy to exploit
- **Impact** (10% weight) - Business impact
Final score: **0-100%**
---
## 🔐 Security & Privacy
✅ **Explicit consent** before sending code to Gemini
✅ **Automatic secret redaction** (API keys, passwords, tokens)
✅ **No remote storage** of source code
✅ **Configurable privacy settings**
---
## 🗂️ Project Structure
```
gemini-bug-hunter/
├── cli/
│ └── index.js # Main CLI entry point
├── engine/
│ ├── gemini/
│ │ └── client.js # Gemini API client
│ ├── scanner/
│ │ └── scanner.js # Code scanner
│ └── risk/
│ └── calculator.js # Risk scoring
├── reporter/
│ └── console.js # CLI reporter
├── config/
│ └── default.js # Default configuration
├── .env.example # Environment template
├── package.json
└── README.md
```
---
## 🎯 Supported Vulnerability Categories
- SQL Injection
- XSS (Cross-Site Scripting)
- CSRF (Cross-Site Request Forgery)
- Authentication Issues
- Authorization Issues
- Sensitive Data Exposure
- Security Misconfiguration
- Insecure Deserialization
- Using Components with Known Vulnerabilities
- Insufficient Logging & Monitoring
- Command Injection
- Path Traversal
- Hardcoded Secrets
- Weak Cryptography
- Race Conditions
---
## 📈 Example Output
```
🛡️ GEMINI BUG HUNTER REPORT
📊 Risk Assessment
Risk Score: 81% ████████████████████
Risk Level: HIGH
Summary: Found 3 vulnerabilities including 1 CRITICAL issues requiring immediate attention
🎯 Severity Breakdown
● CRITICAL: 1
● HIGH: 1
● MEDIUM: 1
🔍 Detected Vulnerabilities
🔴 [1] SQL Injection in User Query
File: src/users.js:42
Category: SQL Injection
Severity: CRITICAL | Confidence: 95%
User input is directly concatenated into SQL query without sanitization.
⚠️ Impact: Attackers can extract or manipulate database data.
✓ Fix: Use parameterized queries and input validation.
✨ Auto-fix available
```
---
## 🔮 Future Roadmap
- [x] Auto-fix implementation (Interactive Mode)
- [ ] GitHub Actions integration
- [ ] CI/CD security gates
- [ ] PR comment integration
- [ ] Historical risk tracking
- [ ] Multi-language support (Python, Java, Go)
- [ ] Enterprise mode with team features
- [ ] Custom rule definitions
- [ ] Integration with SAST tools
---
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
---
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details
---
## 🙏 Acknowledgments
- Powered by **Google Gemini 2.5 and Gemini 3 Flash**
- Inspired by **OWASP Top 10**
- Built for the developer community
---
## 🆘 Support
- 📧 Issues: [GitHub Issues](https://github.com/holasoymalva/gemini-bug-hunter/issues)
- 📖 Documentation: This README
- 🔑 API Key: [Get Gemini API Key](https://aistudio.google.com/app/apikey)
---
**Made with ❤️ by [@holasoymalva](https://github.com/holasoymalva)**