BugTraceAI-WEB

AI-powered web vulnerability analysis suite & CLI control center

---

Product Demo (English)	Demostración del producto (Español)

---

Table of Contents

• Disclaimer
• What is BugTraceAI-WEB?
• Features
• Architecture
• Getting Started
• Development Setup
• CLI Integration
• Tech Stack
• License

What's New in v1.5.40-beta

• Anthropic provider (Claude Messages API) — Select Anthropic alongside OpenRouter and Z.ai. Enter an sk-ant-... key, pick a Claude model, and chat, analysis, and the AIrepeater all run on the native Messages API (x-api-key).
• Curated model pack + Thinking control — The OpenRouter model picker loads a hand-picked, verified set from a single file, with Thinking / High / xHigh entries that enable OpenRouter's reasoning parameter for deeper responses.
• Model Lab module — Model Lab moved to its own sidebar entry at /modellab with its own OpenRouter key, independent of the scanner provider. Adds the recalibrated quick-v3 / advanced-v2 suites, a "Best per slot" leaderboard that recommends a model per MUTATION / SKEPTICAL / ANALYSIS / REPORTING slot, and an opt-in MUTATION diversity probe.
• Live Swarm Graph escalation ladders — Per-agent L1 → L6 escalation ladders now climb live as specialists work, so an in-progress agent visibly advances instead of appearing stuck.
• AuthDiscovery visibility — Follow authentication scanning URL by URL in Events and see JWT/cookie totals on the live Swarm Graph.
• 🧪 AIrepeater — Burp/Caido-style three-pane workbench (Request / Response / AI Agent) with manual and AI-driven modes, multi-tab sessions, response search, per-vulnerability playbooks, and report handoff.

Local beta: run BugTraceAI-WEB and BugTraceAI-CLI on your machine or a trusted LAN. Do not expose the CLI API directly to the Internet. Model Lab uses its own OpenRouter API key and provider charges may apply.

Disclaimer

This application is provided for educational and authorized security testing purposes only.

• AI output may contain inaccuracies, false positives, or false negatives
• It is not a substitute for professional security auditing
• Only test applications for which you have explicit, written authorization
• The creators assume no liability for misuse or damage

Always verify findings manually.

What is BugTraceAI-WEB?

BugTraceAI-WEB is part of the BugTraceAI ecosystem. It serves two purposes:

1. Standalone analysis toolkit — 20+ AI-powered security tools for manual pentesting (SAST, DAST, recon, payload generation, exploitation assistants).
2. CLI control center — Real-time dashboard to launch, monitor, and review BugTraceAI-CLI autonomous scans from the browser.

Each role works independently. You can use the web tools without the CLI, or connect to a CLI instance for full scan management.

Features

CLI Control Center

When connected to BugTraceAI-CLI (optional):

• Live Dashboard — Real-time metrics, findings count, scan progress
• Scan Launcher — Configure and launch CLI scans from the browser with support for YAML-based authenticated scanning (TOTP/2FA included)
• Scan Resume — Resume recoverable scans from previous state without restarting the full workflow
• Report Viewer — Browse, search, and view past scan reports (Markdown rendering)
• Configuration Editor — Modify CLI settings remotely
• Severity Charts — Visual breakdown of findings by severity
• Report Comparison — Side-by-side diff of two scan reports
• API Discovery — Active API endpoint discovery via Kiterunner with multi-filter, sort, speed control, and persistent history
• ModelLab beta — Compare OpenRouter models with live benchmark progress, cost visibility, and local run history

AI Assistants

• WebSec Agent — Integrated chat for security questions and unified control for Kali MCP and ReconFTW agents. Supports optional web browsing toggle for real-time research during analysis.
• Kali Expert Agent (MCP) — Real-time terminal access to the full Kali Linux toolset (Nmap, SQLMap, etc.) via the WebSec Chat.
• ReconFTW Agent (MCP) — Fully automated reconnaissance pipelines managed directly from the browser.
• XSS Exploitation Assistant — Given a confirmed XSS: cookie theft, keyloggers, phishing overlays, session hijacking
• SQL Exploitation Assistant — Given a confirmed SQLi: data extraction, auth bypass, privilege escalation, DB enumeration

Analysis Tools

• URL Analyzer (DAST) — Recon scan, active scan, grey-box scan with live JS analysis
• Code Analyzer (SAST) — SQLi patterns, XSS sinks, insecure functions, logic flaws
• Security Headers Analyzer — CSP, HSTS, X-Frame-Options grading with actionable recommendations
• DOM XSS Pathfinder — Source-to-sink data flow analysis (location.hash → innerHTML, eval, document.write)
• JWT Decompiler & Auditor — Blue team (weak algorithms, data exposure) + Red team (confusion attacks, claim manipulation)
• PrivEsc Pathfinder — CVE and Exploit-DB search by technology/version, privilege escalation vectors
• File Upload Auditor — Automatic form detection, malicious file generation (SVG XSS, polyglots, web shells)

Reconnaissance

• JS Reconnaissance — Hardcoded API endpoints, internal URLs, API keys, cloud credentials (AWS, GCP)
• URL List Finder — Wayback Machine historical URL discovery
• Subdomain Finder — Certificate Transparency search via crt.sh
• API Discovery — Active Kiterunner-powered endpoint discovery with wordlists, speed selector (slow/medium/fast), multi-filter, tag-based sorting, and backend persistence across sessions

Payload Generation

• Payload Forge — WAF bypass payloads (encoding, case manipulation, null bytes, comment injection)
• SSTI Forge — Template injection for Jinja2, Twig, Freemarker, Velocity
• OOB Interaction Helper — Blind XSS callbacks, Log4Shell, DNS exfiltration, interact.sh integration

Analysis Management

• Persistent storage of all analyses (PostgreSQL)
• Side-by-side report comparison with diff engine
• Export to JSON, CSV, and PDF
• Tagging and search across analyses

AI Analysis Methodology

Each analysis runs through multiple AI passes with different perspectives (Bug Hunter, Code Auditor, Pentester, Security Researcher), then consolidates and de-duplicates findings into a single report. An optional deep analysis pass refines each finding with better PoCs, impact scenarios, and remediation.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  BugTraceAI-WEB                                             │
│                                                             │
│  ┌──────────────────┐    ┌──────────────────┐              │
│  │  React Frontend   │───▶│  Express Backend  │              │
│  │  (Vite + TS)      │    │  (Prisma ORM)     │              │
│  │  Port 5173 / 6869 │    │  Port 3001        │              │
│  └──────────────────┘    └────────┬─────────┘              │
│                                    │                        │
│                            ┌───────▼────────┐              │
│                            │  PostgreSQL 16  │              │
│                            │  Chats, Settings│              │
│                            │  Analyses       │              │
│                            └────────────────┘              │
└──────────────────────────────┬──────────────────────────────┘
                               │ Optional
                    ┌──────────▼──────────┐
                    │  BugTraceAI-CLI API  │
                    │  (FastAPI)           │
                    │  Port 8000           │
                    │  SQLite (scans)      │
                    └─────────────────────┘

Dual database design:

• PostgreSQL (WEB) — Local to each WEB instance. Stores chat sessions, analysis reports, and app settings.
• SQLite (CLI) — Source of truth for all scan data. Accessed via CLI API on port 8000.

They work autonomously or together — the WEB app doesn't need the CLI to function, and vice versa.

Getting Started

Prerequisites

• Docker & Docker Compose
• An OpenRouter API key (for AI-powered analysis tools)

Installation (Docker)

Interactive wizard (recommended):

git clone https://github.com/BugTraceAI/BugTraceAI-WEB
cd BugTraceAI-WEB
chmod +x install.sh
./install.sh

The wizard guides you through port selection, database configuration, and CLI backend URL.

Authenticated Scanning (YAML + TOTP)

For targets that require login, BugTraceAI-WEB can configure authenticated scan sessions. Create an auth_config.yaml file:

login_url: https://target.com/login
username: your_user
password: your_password
totp_secret: YOUR_TOTP_SECRET    # optional, for 2FA targets
success_condition: "dashboard"   # string to confirm successful login

Upload it in the Scan Launcher → Auth Config tab before starting the scan. The CLI will handle TOTP token generation automatically.

See the CLI documentation for the full auth_config.yaml reference.

Quick start:

git clone https://github.com/BugTraceAI/BugTraceAI-WEB
cd BugTraceAI-WEB
chmod +x dockerizer.sh
./dockerizer.sh

Access at http://localhost:6869

Post-install

1. Open Settings (gear icon in the header)
2. Enter your OpenRouter API key
3. Select a model (the app fetches available models from OpenRouter automatically)
4. Start analyzing

Stop / Restart

docker compose down          # Stop
docker compose up -d         # Start again
docker compose logs -f       # View logs

Development Setup

For local development without Docker:

Backend

cd backend

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your PostgreSQL connection string

# Run database migrations
npx prisma migrate dev

# Start dev server (auto-reload)
npm run dev

Backend runs on http://localhost:3001.

Frontend

# From the project root
npm install

# Configure environment
cp .env.example .env
# Default values work if backend is on port 3001

# Start dev server
npm run dev

Frontend runs on http://localhost:5173 with Vite proxy forwarding /api to the backend.

Environment Variables

Frontend (.env):

VITE_API_URL=/api      # Backend API
VITE_CLI_API_URL=/cli-api      # BugTraceAI-CLI API (optional)

Backend (.env):

DATABASE_URL="postgresql://bugtraceai:your_password@localhost:5432/bugtraceai_web?schema=public"
PORT=3001
NODE_ENV=development
FRONTEND_URL="http://localhost:5173"

CLI Integration

Connecting to BugTraceAI-CLI unlocks the dashboard features (scan launcher, report viewer, config editor, etc.).

1. Start the CLI API server:

   cd BugTraceAI-CLI
   python3 -m uvicorn bugtrace.api.main:app --host 0.0.0.0 --port 8000

2. In BugTraceAI-WEB Settings → CLI Connector:

   • Enter CLI API URL (default: http://localhost:8000)
   • Enable the CLI Connector toggle

3. The CLI Dashboard tab becomes available automatically.

Multiple WEB instances can connect to the same CLI API server over the network.

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript 5, Vite 5
Styling	Tailwind CSS
State	React Context + Custom Hooks
Charts	Recharts
Code Editor	Monaco Editor
Backend	Express 5, TypeScript, Prisma ORM
Database	PostgreSQL 16
Real-time	Socket.IO
Validation	Zod
AI Provider	OpenRouter (200+ models) + Anthropic (Claude Messages API) + Z.ai (GLM family)
Testing	Vitest + Supertest
Deployment	Docker Compose, Nginx reverse proxy

Project Structure

BugTraceAI-WEB/
├── components/           # React components (70+)
│   ├── cli/              #   CLI dashboard (scan launcher, reports, config editor)
│   ├── analysis/         #   Analysis history, report viewer, comparison, export
│   └── ...               #   Tools: UrlAnalyzer, CodeAnalyzer, JwtAnalyzer, etc.
├── contexts/             # React Context providers (Chat, Analysis, Settings)
├── hooks/                # Custom hooks (13 files)
├── services/             # AI analysis service, CLI connector, system prompts
│   └── prompts/          #   Analysis-specific prompt templates
├── payloads/             # XSS payload wordlists
├── styles/               # Global CSS
├── utils/                # Utility functions
├── backend/              # Express + Prisma backend
│   ├── prisma/           #   Database schema & migrations
│   ├── src/
│   │   ├── controllers/  #   Chat, Analysis, Settings controllers
│   │   ├── routes/       #   API route definitions
│   │   ├── middleware/   #   Error handling, rate limiting, validation
│   │   └── utils/        #   Prisma client, exporters, comparison engine
│   └── tests/            #   Integration tests
├── App.tsx               # Main app (routing, providers)
├── docker-compose.yml    # 3-service stack (PostgreSQL, backend, frontend/nginx)
├── install.sh            # Interactive installation wizard
└── dockerizer.sh         # Quick Docker deploy script

License

AGPL-3.0 License. See LICENSE for details.

---

Made by Albert C. — @yz9yt
bugtraceai.com