🛡️ 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)
• Gemini Model: Uses gemini-2.5-flash by default (configurable)

Setup

# 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:

# 1. Install globally
npm install -g gemini-bug-hunter

# 2. Set your API Key globally (Run once)
gbh config set-key <YOUR_GEMINI_API_KEY>

# 3. Ready to scan!
gbh scan

---

🧪 CLI Commands

Scan for Vulnerabilities

# 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

gbh doctor

View Configuration

gbh config

Explain Vulnerability

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

{
  "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

• 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 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
• 📖 Documentation: This README
• 🔑 API Key: Get Gemini API Key

---

Made with ❤️ by @holasoymalva