BugTraceAI-WEB

The analyst workspace for the BugTraceAI web pentesting suite.
Launch scans. Follow agents live. Investigate requests. Review the evidence.

BugTraceAI-WEB is the self-hosted browser workspace for the BugTraceAI security suite. Use its analysis tools independently, connect BugTraceAI-CLI for agentic web scans, or connect BugTraceAI-API for API-target testing.

Quick start · Workspace · Screenshots · Engine connections · Development · Documentation

See it in action

Watch the product walkthrough on YouTube

Quick start

Run the official BugTraceAI Launcher:

curl -fsSL https://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh | bash

The Launcher presents provider setup, installation choices, module selection, and ports before deploying the selected services.

• WEB only: choose Wizard and select WEB for the dashboard and analysis tools. Existing scanning engines can be connected later.
• WEB + scanning engines: select WEB with CLI, BugTraceAI-API, or both for the scan workflows you need.
• Full workspace: include the CLI terminal TUI alongside WEB and the selected engines.

WEB deployment uses Docker. Optional Kali and reconFTW toolboxes can be selected during setup. Review the installation plan, then open the WEB URL printed by the Launcher; the usual frontend port is 6869, but your configured port takes precedence.

From an existing WEB checkout, ./install.sh opens the same Launcher with WEB suggested. Direct standalone Docker setup and a copyable coding-agent prompt are in INSTALLATION.md.

Configure your workspace

In Settings, choose OpenRouter, Anthropic, or Z.ai, enter that provider's key locally, and select a model. ModelLab uses its own OpenRouter key inside the module, independently of the provider used for analysis.

The BugTraceAI model catalog contains the suite's published checkpoints. Follow each model card and the applicable module's configuration guide when choosing how to use a checkpoint.

For target login, use the scan launcher's Auth Config tab. Login YAML and optional TOTP/2FA are documented in the authentication guide.

For Launcher-managed deployments, run ./launcher.sh status, logs web, start, stop, or update --plan from the Launcher checkout. See its command guide.

Workspace

Area	What you can do
Web scans	Launch CLI scans, configure target authentication, follow the six scan phases and live Swarm Graph, resume recoverable scans, and review reports.
API testing	Connect the standalone BugTraceAI-API engine to launch API audits, follow progress, inspect findings and evidence, and download reports.
AIrepeater	Inspect HTTP requests and responses in a Request / Response / AI Agent workbench. Send requests manually or with AI assistance, use vulnerability playbooks, and hand findings into reports.
Analysis tools	Work with URL and source-code analysis, security headers, DOM XSS, JWT auditing, file uploads, and privilege-escalation research.
Discovery and payloads	Discover subdomains, historical URLs, JavaScript endpoints, and API routes. Prepare WAF-bypass and SSTI payloads or out-of-band interaction checks.
AI assistants	Investigate security questions in chat and connect optional Kali and reconFTW MCP toolboxes.
ModelLab	Compare OpenRouter models with live benchmark progress, per-slot recommendations, cost visibility, results, and run history.
Reports	Inspect severity, validation state, evidence, and PoCs; compare reports, search analysis history, and export results.

The scanning engines are independent products. WEB's own chat, settings, and analysis tools remain available without connecting either engine; engine-specific scan workflows require the corresponding service.

Screenshots

Live scan workspace	Specialist Swarm Graph
API route discovery	Findings and report explorer

These example captures use the BugStore practice target. Counts and findings belong to those sessions. The sample report linked above was generated with an earlier scanner build and is provided to explore the workflow.

Engine connections

flowchart LR
    WEB[WEB browser workspace] --> Backend[WEB Express backend]
    Backend --> DB[(PostgreSQL)]
    WEB --> CLI[BugTraceAI-CLI REST API]
    WEB --> API[BugTraceAI-API REST API]
    CLI --> WebScans[Autonomous web scans]
    API --> APIScans[API-target scans]

Loading

Service	Role
WEB backend + PostgreSQL	Store this WEB instance's chats, settings, and analysis history.
BugTraceAI-CLI	Run autonomous web scans and provide scan events, configuration, findings, and reports.
BugTraceAI-API	Run independent API-target audits over REST, with MCP available for external assistants.

The Launcher configures connections for the engines you select. For an existing or remote service, use the CLI API URL or BugTraceAI-API URL fields in Settings and the corresponding Test button.

Docker deployments use same-origin proxy routes (/cli-api and /btai-api). The usual direct REST ports are 8000 for CLI and 8005 for BugTraceAI-API; use the actual URLs from your deployment. Multiple WEB instances can connect to the same CLI service. WEB and the scanning services are intended for a local machine or trusted network.

Development

Local development requires Node/npm and a configured PostgreSQL database. Follow the development setup for environment variables and database credentials.

Backend terminal:

cd backend
npm install
# Configure backend/.env for your local PostgreSQL database.
npx prisma migrate dev
npm run dev

Frontend terminal, from the WEB repository root:

npm install
# Configure the frontend environment as described in INSTALLATION.md.
npm run dev

The backend defaults to 3001 and Vite to 5173. Run npm run build for the production frontend build.

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS
Backend and storage	Express 5, Prisma, PostgreSQL 16
Live events and visualization	Socket.IO, Recharts
HTTP and code workbench	Monaco Editor
Deployment	Docker Compose, Nginx

Documentation

Guide	Contents
Installation	Guided setup, standalone Docker, coding-agent prompts, configuration, and troubleshooting
Authentication	Target login YAML and TOTP/2FA
Launcher	Module selection, provider setup, service management, and updates
WEB documentation	Workspace and tool documentation
Changelog · Tags · Releases	Version history and published builds
BugStore	Deliberately vulnerable practice target

Responsible use and license

Use BugTraceAI only for educational work and testing you are authorized to perform. AI findings can be wrong; verify the evidence before relying on them.

Licensed under Apache-2.0. See LICENSE and CONTRIBUTORS.md.

Built by Albert C. · @yz9yt · bugtraceai.com · Discord community

Bedrock CLI provider (beta)

Configure the CLI engine with an AWS source region and an optional Bedrock API key. Region-only edits and AWS role/profile connection tests are supported. Scope and setup.