BugTraceAI-CLI

📑 Table of Contents

🚨 Disclaimer
✨ Features
🔬 Core Methodology
🏗️ Architecture
🛠️ Technology Stack
🚀 Getting Started
🤖 AI Assistant Setup (MCP)
⚙️ Configuration
📊 Output
📜 License

🏆 The First Agentic Framework Intelligently Designed for Bug Bounty Hunting

BugTraceAI-CLI is an autonomous offensive security framework that combines LLM-driven analysis with deterministic exploitation tools. Unlike passive analysis tools, BugTraceAI-CLI actively exploits vulnerabilities using real payloads, SQLMap integration, and browser-based validation to deliver confirmed, actionable findings.

The core philosophy is "Think like a pentester, execute like a machine, validate like an auditor" - using AI for intelligent hypothesis generation, but relying on real tools for exploitation and validation.

🚨 Disclaimer

This tool is for authorized security testing only.

BugTraceAI-CLI performs active exploitation including:

Real SQL injection payloads via SQLMap
XSS payload execution in browsers
Template injection testing
Server-side request forgery probing

By using this tool, you acknowledge and agree that:

You will only test applications for which you have explicit, written permission
You understand this tool sends actual attack payloads to targets
The creators assume no liability for any misuse or damage caused

Unauthorized access to computer systems is illegal.

✨ Features

BugTraceAI-CLI implements a 6-phase pipeline that mirrors a professional penetration testing workflow.

Phase 1: Reconnaissance

🕷️ GoSpider Integration: Fast async crawling with JavaScript rendering and sitemap parsing
🔍 Parameter Extraction: Automatic identification of injectable parameters
🌐 API Endpoint Enrichment: Detail URL discovery from list endpoints
🧭 SPA Route Inference: Infers API endpoints from frontend routes

Phase 2: Discovery (DASTySAST)

🧠 Multi-Persona Analysis: 6 different AI "personas" analyze each URL (bug bounty hunter, code auditor, pentester, etc.)
✅ Consensus Voting: Requires 4/5 agreement from analysis personas to reduce false positives
🔎 Skeptical Review: The 6th "Skeptical" persona (Claude Haiku) performs final filtering
🎯 Nuclei CVE Scanning: Template-based detection of known vulnerabilities (runs in parallel)
🛡️ Parallel Execution: All personas analyze simultaneously for speed

Phase 3: Strategy

🎯 ThinkingConsolidationAgent: Central brain that routes findings to specialists
🔄 Deduplication: Eliminates redundant findings across URLs
⚡ Priority Routing: High-confidence findings get tested first
🛡️ SQLi Bypass: SQL injection candidates always reach SQLMap (tool decides, not LLM)
🧩 Auto-Dispatch: Framework detection triggers specialist agents automatically (e.g., Angular → CSTIAgent)

Phase 4: Exploitation

Real tools, real payloads, real results — 14 autonomous specialist agents:

Agent	Target	Method
🔥 XSSAgent	Cross-Site Scripting	Playwright browser + 6-level escalation pipeline
💉 SQLiAgent	SQL Injection	SQLMap with WAF bypass tamper scripts
🎭 CSTIAgent	Client/Server-Side Template Injection	AngularJS, Vue, Jinja2, Twig, Mako
🌐 SSRFAgent	Server-Side Request Forgery	OOB callback verification
📄 XXEAgent	XML External Entity	DTD injection + OOB exfiltration
🔓 IDORAgent	Insecure Direct Object Reference	ID manipulation + path segment testing
📁 LFIAgent	Local File Inclusion	Path traversal with filter evasion
🧩 PrototypePollutionAgent	Prototype Pollution	Browser-based property verification
🔌 APISecurityAgent	API Security	Broken Object Level Authorization (BOLA) testing
🔑 JWTAgent	JWT Vulnerabilities	Algorithm confusion, weak secrets, token forging
🔀 OpenRedirectAgent	Open Redirect	HTTP 3xx + DOM-based redirect detection
💀 RCEAgent	Remote Code Execution	Command injection + deserialization testing
📨 HeaderInjectionAgent	Header Injection	CRLF injection + response splitting
📦 MassAssignmentAgent	Mass Assignment	Parameter pollution + privilege escalation

Phase 5: Validation

🖥️ Chrome DevTools Protocol: Low-level browser verification for XSS
👁️ Vision AI: Screenshot analysis confirms visual vulnerabilities
📸 Evidence Capture: Every confirmed finding includes proof

Phase 6: Reporting

📊 AI-Powered Reports: LLM-generated executive and technical assessments
📝 Multiple Formats: JSON (machine-readable), Markdown, and HTML reports
🔬 PoC Enrichment: Batch proof-of-concept generation for confirmed findings
📁 Specialist Audit Trail: Per-agent WET/DRY/Results traceability

Intelligence Systems

🔀 LLM Shifting: Automatic fallback through model tiers (Gemini → DeepSeek → Claude → Qwen)
🛡️ WAF Detection: Identifies Cloudflare, Akamai, AWS WAF, ModSecurity
🎯 Adaptive Bypass: Encoding, chunking, and case mixing strategies per WAF type

🔬 Core Methodology

BugTraceAI-CLI uses a multi-layered approach to maximize accuracy while minimizing false positives.

Multi-Persona Analysis

Instead of a single AI scan, each URL is analyzed by 6 different "personas" providing diverse perspectives:

Bug Bounty Hunter: Focuses on high-impact, reward-worthy issues (RCE, SQLi, SSRF)
Code Auditor: analyzing code patterns, input validation, and logic flaws
Pentester: Standard attack-surface mapping and OWASP Top 10 exploitation
Security Researcher: Novel attack vectors, race conditions, and edge cases
Red Team Operator: Advanced attack chains, privilege escalation, and lateral movement
Skeptical Reviewer: A separate "critic" agent that aggressively filters false positives

Consensus + Skeptical Review

5 Analysis Personas run in parallel
        ↓
Consensus voting (Agreement analysis)
        ↓
6th Persona "Skeptical Agent" Review (Claude Haiku)
        ↓
Passed to specialist agents

Tool-Based Validation

The key differentiator: AI hypothesizes, tools validate.

SQLi findings → SQLMap confirms with real injection
XSS findings → Playwright executes payload in browser
All findings → CDP + Vision AI provides evidence

This eliminates the "hallucination problem" of pure-AI scanners.

🏗️ Reactor Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         BUGTRACE REACTOR                             │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐   │
│  │   Phase 1  │   │   Phase 2  │   │   Phase 3  │   │   Phase 4  │   │
│  │   Recon    │ → │  Discovery │ → │  Strategy  │ → │Exploitation│   │
│  │  GoSpider  │   │ DASTySAST  │   │ ThinkingAg.│   │ 14 Agents  │   │
│  │ URL Enrich │   │ 6 Personas │   │   Dedup    │   │   SQLMap   │   │
│  │ SPA→API    │   │  + Nuclei  │   │  Routing   │   │ Playwright │   │
│  └────────────┘   └────────────┘   └────────────┘   └─────┬──────┘   │
│                                                            │         │
│                                                            ▼         │
│                                                     ┌────────────┐   │
│                                                     │   Phase 5  │   │
│                                                     │ Validation │   │
│                                                     │    CDP     │   │
│                                                     │ Vision AI  │   │
│                                                     └─────┬──────┘   │
│                                                           │          │
│                                                           ▼          │
│                                                     ┌────────────┐   │
│                                                     │   Phase 6  │   │
│                                                     │ Reporting  │   │
│                                                     │JSON/MD/HTML│   │
│                                                     └────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

Parallelization Control

Each phase runs with independent concurrency:

Phase	Concurrency	Configurable	Notes
Reconnaissance	1	No	GoSpider is already fast
Discovery	5	Yes	Parallel DAST per URL
Strategy	1	No	Sequential dedup + routing
Exploitation	10	Yes	Parallel specialist agents
Validation	1	No	CDP limitation (hardcoded)
Reporting	1	No	Sequential report generation

Why is Validation = 1? Chrome DevTools Protocol doesn't support multiple simultaneous connections. Additionally, alert() popups from XSS payloads block CDP indefinitely. Single-threaded with timeouts prevents crashes.

🛠️ Technology Stack

Language: Python 3.10+
AI Provider: OpenRouter (Gemini, Claude, DeepSeek, Qwen)
Local AI: BAAI/bge-small-en-v1.5 (SOTA Embeddings & Semantic Search)
Browser Automation: Playwright (exploitation), Chrome CDP (validation)
SQL Injection: SQLMap via Docker
Crawling: GoSpider via Docker
CVE Scanning: Nuclei via Docker
Database: SQLite with WAL mode
Async: asyncio + aiohttp

🚀 Getting Started

Prerequisites

For Docker: Docker & Docker Compose
For Local: Python 3.10+, Docker (for some agents), nmap (optional)
OpenRouter API key (get one here)

🎯 Quick Installation (Recommended)

Use the interactive installation wizard for automatic setup:

# Clone the repository
git clone https://github.com/BugTraceAI/BugTraceAI-CLI
cd BugTraceAI-CLI

# Run the installation wizard
./install.sh

The wizard will:

✅ Check system requirements automatically
🔍 Detect and use free ports for Docker (no conflicts!)
⚙️ Set up environment configuration
🐳 Build and start Docker containers OR configure local Python environment
🎨 Provide beautiful, interactive terminal UI

Installation Options:

Local Installation - Python virtual environment (best for development)
Docker Installation - Containerized deployment (best for production)

📖 Manual Installation

Click to expand manual installation instructions

Local Installation

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install browser
playwright install chromium

# Configure environment
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

Docker Installation

# Configure environment
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

Quick Start

# Full scan
./bugtraceai-cli scan https://target.com

# Clean scan (reset database)
./bugtraceai-cli scan https://target.com --clean

# Resume interrupted scan
./bugtraceai-cli scan https://target.com --resume

# Start API server (for Web UI)
./bugtraceai-cli serve --port 8000

Docker Users:

# API is already running at http://localhost:8000
# (or whatever port was auto-selected during installation)

# Execute scans via API or Web UI
curl http://localhost:8000/health

🤖 AI Assistant Setup (MCP)

BugTraceAI is MCP-compatible — control your security scans directly from your AI assistant through natural conversation.

Works with OpenClaw (Telegram-based AI assistant), Claude Code, Cursor, and any MCP-compatible client. Deploy once, control from anywhere.

How It Works

BugTraceAI exposes its scanning engine as MCP tools via the Model Context Protocol — the open standard for connecting AI assistants to external tools. Your AI assistant can start scans, monitor progress, query findings, and retrieve reports — all through chat.

Quick Setup for AI Agents

Using OpenClaw or another AI assistant? Just tell it:

Clone https://github.com/BugTraceAI/BugTraceAI-CLI and deploy it with Docker. Copy .env.example to .env and ask me for the OPENROUTER_API_KEY. Run docker compose up -d to start both the API and MCP server. Then add the MCP server to your config with base URL http://localhost:8001/sse.

Manual MCP Setup

# 1. Clone and configure
git clone https://github.com/BugTraceAI/BugTraceAI-CLI
cd BugTraceAI-CLI
cp .env.example .env
# Edit .env → add your OPENROUTER_API_KEY

# 2. Start services (API + MCP)
docker compose up -d

# 3. Verify endpoints
curl -f http://localhost:8000/health   # API health check
curl -sf http://localhost:8001/sse     # MCP SSE endpoint

Connect Your AI Assistant

Add BugTraceAI to your MCP client configuration:

{
  "mcpServers": {
    "bugtraceai": {
      "baseUrl": "http://localhost:8001/sse",
      "description": "BugTraceAI Security Scanner"
    }
  }
}

Available MCP Tools

Once connected, your AI assistant can use these tools:

Tool	Description
`start_scan`	Start a security scan on a target URL
`get_scan_status`	Check scan progress and current phase
`query_findings`	Retrieve vulnerability findings with filtering
`stop_scan`	Stop a running scan gracefully
`export_report`	Get scan report (summary, critical findings, or full)

Prerequisites

Docker & Docker Compose installed and running
OpenRouter API key (get one here)
An MCP-compatible AI assistant (OpenClaw, Claude Code, Cursor, or any MCP client)

Ports

Service	Port	Description
API	8000	REST API + health check
MCP	8001	SSE transport for AI assistants

⚙️ Configuration

All settings in bugtraceaicli.conf:

[API]
OPENROUTER_API_KEY = sk-or-v1-xxxxx

[SCAN]
MAX_URLS = 100
MAX_CONCURRENT_ANALYSIS = 5
MAX_CONCURRENT_SPECIALISTS = 10

[SCANNING]
MANDATORY_SQLMAP_VALIDATION = True
STOP_ON_CRITICAL = False

[VALIDATION]
CDP_ENABLED = True
VISION_ENABLED = True

Model Configuration

[LLM_MODELS]
DEFAULT_MODEL = google/gemini-2.0-flash-thinking-exp:free
SKEPTICAL_MODEL = anthropic/claude-3.5-haiku:beta
VISION_MODEL = google/gemini-2.0-flash-thinking-exp:free

📊 Output

Reports

Generated in /reports/:

report_*.json - Machine-readable findings
report_*.md - Markdown summary
report_*.html - Executive presentation

Logs

Located in /logs/:

execution.log - Detailed trace
llm_audit.jsonl - Every AI prompt/response
errors.log - Error tracking

Finding Status Flow

CANDIDATE → PENDING_VALIDATION → CONFIRMED / FALSE_POSITIVE → PROBE_VALIDATED

📜 License

AGPL-3.0 License

See LICENSE for details.

Made with ❤️ by Albert C. @yz9yt

bugtraceai.com

Name		Name	Last commit message	Last commit date
Latest commit History 531 Commits
.github/workflows		.github/workflows
alembic		alembic
bugtrace		bugtrace
docs/agents		docs/agents
documentation		documentation
tests		tests
tools		tools
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
bugtraceai-cli		bugtraceai-cli
bugtraceaicli.conf		bugtraceaicli.conf
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
install.sh		install.sh
logo.png		logo.png
openapi.yaml		openapi.yaml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

BugTraceAI/BugTraceAI-CLI

Folders and files

Latest commit

History

Repository files navigation

BugTraceAI-CLI

📑 Table of Contents

🚨 Disclaimer

✨ Features

Phase 1: Reconnaissance

Phase 2: Discovery (DASTySAST)

Phase 3: Strategy

Phase 4: Exploitation

Phase 5: Validation

Phase 6: Reporting

Intelligence Systems

🔬 Core Methodology

Multi-Persona Analysis

Consensus + Skeptical Review

Tool-Based Validation

🏗️ Reactor Architecture

Parallelization Control

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

🎯 Quick Installation (Recommended)

📖 Manual Installation

Local Installation

Docker Installation

Quick Start

🤖 AI Assistant Setup (MCP)

How It Works

Quick Setup for AI Agents

Manual MCP Setup

Connect Your AI Assistant

Available MCP Tools

Prerequisites

Ports

⚙️ Configuration

Model Configuration

📊 Output

Reports

Logs

Finding Status Flow

📜 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages