🦅 Vulnerability Finder

AI-Powered Security Orchestration Engine

A high-performance, containerized vulnerability scanner that integrates traditional security tools with the Claude AI Assistant via the Bonsai proxy. It performs autonomous reconnaissance, vulnerability discovery, and risk analysis.

---

📊 Operational Flow

The following diagram showcases how the orchestrator manages the lifecycle of a scan, from initial authentication to advanced AI-driven discovery.

flowchart TD
    Start([User Starts Program]) --> LoadConfig[Load config.yaml]
    LoadConfig --> BonsaiAuth{Bonsai Login}
    
    subgraph "Authentication & Initialization"
    BonsaiAuth --> |Interactive| BrowserAuth[Browser Authentication via Proxy]
    BrowserAuth --> TargetInput[User Enters Target URL]
    end

    TargetInput --> Recon[<b>Phase 1: Reconnaissance</b><br/>Playwright-based Crawler<br/>JS Extraction & Subdomain discovery]
    
    Recon --> TechDetect[<b>Phase 2: Intelligence</b><br/>Tech Stack Detection<br/>React, Nginx, APIs, etc.]
    
    TechDetect --> AIPlanner[<b>AI Smart Planning</b><br/>Claude adjusts scan logic<br/>based on tech stack]
    
    AIPlanner --> ToolExec[<b>Phase 3: Parallel Execution</b><br/>Nuclei, Nmap, FFUF, HTTPX]

    subgraph "Advanced AI Assessment"
    ToolExec --> AIDiscovery[<b>Phase 4: Autonomous Discovery</b><br/>Claude brainstorms logic flaws<br/>using internal security reasoning]
    AIDiscovery --> Triage[<b>AI Triage & Scoring</b><br/>Categorization & Criticality<br/>Deduplication]
    end

    Triage --> ReportGen[<b>Phase 5: Reporting</b><br/>Glassmorphic HTML Dashboard<br/>Markdown & JSON Exports]
    
    ReportGen --> Finish([Scan Complete & Interactive Chat Ready])

Loading

---

🚀 Key Features

• AI-Autonomous Discovery: Beyond static tools, Claude analyzes the target's tech stack to brainstorm unique logic flaws and misconfigurations.
• Bonsai Proxy Integration: Seamlessly connects to Claude models through a specialized security proxy.
• Multi-Tool Orchestration:
  • Nuclei: Template-based scanning.
  • Nmap: Port and service discovery.
  • FFUF: Fast web fuzzing.
  • HTTPX: Probing and tech detection.
• Interactive Docker Mode: Run scans and interact with the AI assistant directly from your terminal.
• Glassmorphic Reporting: Generates premium HTML and Markdown dashboards with AI-driven risk scores.

---

🛠️ Prerequisites

• Docker Desktop installed and running.
• A Claude Assistant API Key.

---

🏁 Quick Start

1. Setup Configuration

Ensure your Claude API key is set in config.yaml:

claude_assistant:
  enabled: true
  api_key: "your_key_here"

2. Run with Docker

Use the following command to build and start the scanner:

docker compose up --build

⚡ Development Mode (Watch)

To automatically sync your code changes to the running container without restarting, use the Watch command:

docker compose up --watch

Changes to Python files will sync instantly, while changes to requirements.txt or Dockerfile will trigger an automatic rebuild.

3. Authenticate

When the container starts, it will print a Bonsai Login URL.

1. Copy the URL into your browser.
2. Sign in to authorize the proxy.
3. Return to the terminal to enter your target URL.

---

📂 Project Structure

• /crawler: Playwright-based engine for page discovery and JS analysis.
• /tools: Wrappers for Nuclei, FFUF, Nmap, and the AI Assistant.
• /orchestrator: The core logic that plans and manages the scan lifecycle.
• /reports: Where your premium scan results are saved.
• /config.yaml: The main settings file for all tools and AI features.

---

🛡️ Safety & Ethics

This tool is for authorized security testing only. Ensure you have permission from the target owner before scanning. The tool includes an allowlist.txt feature to prevent accidental out-of-scope scanning.