BugTraceAI

Open-source, self-hosted web pentesting suite.
Agentic scanning, analyst tools, API testing and specialized security models.

BugTraceAI brings web and API testing engines, an analyst workspace, published model checkpoints and MCP integrations into one modular suite. Run the components you need on your own infrastructure and inspect the evidence behind each finding.

Install with Launcher · Read the docs · Explore a sample report · Browse BugTraceAI models · Join the community

Choose Your Workflow

WEB can connect to the CLI engine for web scans and the API engine for API-target scans. The Launcher lets you choose WEB, CLI, API or a combination.

Jump To

• Proven in the Security Community
• What is BugTraceAI?
• The Ecosystem
• Models and ModelLab
• Architecture
• Scanning Pipeline
• Current Public Releases
• Demo Report
• CI/CD Integration Proposal
• Quick Start
• Documentation
• Community & Support

Proven in the Security Community

CVEs Disclosed

Presented On Stage

• RootedCON 2026, Madrid, Spain
• HKOSCon 2026, Hong Kong
• DEF CON 34, Las Vegas, USA

See It Working

CLI 4.0.16-beta · interactive terminal workspace

The real TUI has five views: Pipeline, Findings, Agents, Timeline and Logs.
Configure the target, crawl limits, Provider/F7 and Auth/F8 from the workspace.
The terminal capture uses the built-in offline demo with sample data.
Open the CLI screenshot gallery and installation guide.

WEB · API discovery	WEB · specialist graph
WEB · scan console	WEB · report explorer

WEB captures show the scan and reporting interfaces using the BugStore practice
target. Report counts in screenshots describe those example sessions.

BugTraceAI combines AI-guided investigation with deterministic security tools. The AI prioritizes and reasons about hypotheses; tools and evidence validate what is real.

Disclaimer

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

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

Always verify findings manually.

What is BugTraceAI?

BugTraceAI is an open-source, self-hosted web pentesting suite for authorized security research. It combines agentic scanning, an analyst workspace, an independent API-testing engine, published model checkpoints and extensible tools. Its scanning engines connect AI investigation with security checks, validation and reporting.

Its agents plan and prioritize checks, route work to specialists and collect evidence through the scanning tools and validation stages.

Core Principles

The Ecosystem

The suite includes four independently deployable product components, published model checkpoints, MCP integrations and a dedicated practice target:

<th>Repository</th>

<td><a href="https://github.com/BugTraceAI/BugTraceAI-API">BugTraceAI-API</a></td>

<td><a href="https://github.com/BugTraceAI/BugTraceAI-CLI">BugTraceAI-CLI</a></td>

<td><a href="https://github.com/BugTraceAI/BugTraceAI-WEB">BugTraceAI-WEB</a></td>

<td><a href="https://github.com/BugTraceAI/BugTraceAI-Launcher">BugTraceAI-Launcher</a></td>

<td><a href="https://github.com/BugTraceAI/reconftw-mcp">reconftw-mcp</a></td>

<td><a href="https://github.com/BugTraceAI/BugStore">BugTraceAI/BugStore</a></td>

<td><a href="https://huggingface.co/BugTraceAI">BugTraceAI Models</a></td>

Use the CLI TUI locally, its API/MCP for automation, or the Launcher to install independent products or a combination. The WEB connects to the appropriate scanning backend for each engine; API scans use BugTraceAI-API and web scans use the CLI API.

Models and ModelLab

The suite's model ecosystem has three parts:

• BugTraceAI Models: published security-focused checkpoints for bug bounty and web pentesting workflows. See the model catalog and individual model cards for requirements and usage.
• External providers and models: configurable options supported by each product component. Provider support and model roles vary by module; follow its current configuration guide.
• ModelLab: a benchmarking workspace in WEB for comparing selected OpenRouter models and reviewing their results and costs.

Publishing a checkpoint does not imply it is the default model in every component. Check each module's documentation for supported connections and configuration.

Published model families

Consult each model card for serving requirements, formats, license terms and intended use.

Providers by workflow

Model support depends on the selected component, provider, task and configuration. Bedrock remains beta with real AWS account validation pending, as stated in its release notes.

Architecture

flowchart LR
    TUI[CLI terminal workspace] --> Engine[CLI scan engine]
    WEB[WEB dashboard] --> REST[CLI REST API]
    MCP[CLI MCP clients] --> Engine
    REST --> Engine
    WEB --> API[BugTraceAI-API]
    Engine --> Tools[Specialists and browser validation]
    Engine --> Reports[Scan reports]
    API --> Reports

The CLI stores scan metadata in SQLite and writes report artifacts to disk.
The WEB uses PostgreSQL for its own chats, settings and analysis. The Launcher
configures service connections and selected ports. Standalone local TUI setup
opens the engine without starting an API server.

See the component documentation for deployment details.

Scanning Pipeline

The CLI terminal and WEB display the same six scan phases:

Target authentication supports Bearer tokens and login YAML with optional
TOTP/2FA. In the TUI, configure it through Auth/F8, separately from the
LLM provider's API key in Provider/F7. See the
CLI installation guide.

Current Public Releases

These releases include the Bedrock beta CLI provider and WEB region controls,
model-override and scan safe-mode fixes, and tolerant Launcher output decoding.
The source and curated release copies passed offline checks. Real AWS account
validation remains pending; see the Bedrock guide.
A fresh full installation, macOS and ARM were not validated in this release review.

Demo Report

Want to see what BugTraceAI produces? Try the live demo or download a real scan report generated against BugStore -- our deliberately vulnerable practice app.

Benchmark note: This demo report was produced with an earlier scanner build. Results are useful for exploring the workflow, but should not be treated as a current performance claim for the latest CLI release until re-run under a versioned benchmark protocol.

The zip includes the full markdown report, validated findings JSON, specialist agent results with WET/DRY traceability, reconnaissance data, and PoC enrichment output.

CI/CD Integration Proposal

For CI/CD, automation can call the CLI REST/MCP interfaces for web scans or BugTraceAI-API for API-target testing. Reports and evidence are available for review in the WEB workspace. The diagram below proposes downstream AI review and ticketing integrations; connect them to the selected engine's supported interfaces.

This keeps external automation, autonomous scanning, evidence-rich reporting, human review, and remediation coordination connected without hard-coding deployment-specific service endpoints.

Quick Start

Choose your setup

• Terminal workspace: Linux and Python 3.10+ for local installation;
  some specialist tools also use Docker when scanning.
• API/MCP or full WEB platform: select the relevant profile and runtime in
  the installer. Docker deployments need Docker Engine, Compose and Git.
• Real scans: configure a supported provider's API key. Opening the TUI or
  its offline demo does not require starting a scan.

One-Command Install

One-liner (recommended):

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

Or clone and run manually:

git clone https://github.com/BugTraceAI/BugTraceAI-Launcher.git ~/bugtraceai-launcher
~/bugtraceai-launcher/launcher.sh

From this ecosystem checkout, ./install.sh opens the same universal menu
with full suggested. Component ./install.sh entry points suggest their
own product in that menu; they do not deploy a profile without your review.

Enter and verify a provider API key on the first screen, then choose
Install with Wizard or Install with AI. Both stay in the TUI. Wizard
supports every module combination. AI setup uses OpenRouter or Anthropic provider tokens; use Wizard for Z.ai.
See the current Launcher guide
for supported module combinations and installation options.
The review shows selected modules, runtime, ports and optional WEB toolboxes.
Terminal profiles can register a global btai command.

Let your AI coding agent run setup

If you use Codex, Claude Code, Cursor or another local terminal agent, give it
this prompt:

Help me install BugTraceAI using the official universal Launcher.

First read:
https://github.com/BugTraceAI/BugTraceAI#readme
https://github.com/BugTraceAI/BugTraceAI-Launcher#readme

Follow those instructions using the official installer:
https://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh

Ask which independent modules I want: BugTraceAI-WEB, BugTraceAI-CLI,
BugTraceAI-API, or a combination. Install only the modules I choose. Let me
choose Wizard or the built-in AI installer when my selection is supported;
use Wizard for other combinations.

Preserve any existing installation, configuration and data. Run the
Launcher in my local interactive terminal. I will enter and verify the
provider API key there, choose ports and review the plan before installation.
Keep credentials out of chat and logs. Do not start a scan.

Verify the selected services on their configured ports. If I enable the
global btai command, check it from a fresh shell. Report the installation
location, launch commands, checks completed and any checks still pending.

For direct component installation, use each checkout's explicit
scripts/install-runtime.sh backend or the documented Python/Compose commands. Follow
INSTALLATION.md; a bare WEB docker compose up is not a
complete configuration step.

Component entry points suggest their own module. A suggestion only sets the
initial checkboxes; review the exact modules before installation.

Documentation

Full documentation is available in the Project Wiki:

• Overview -- What BugTraceAI is and who it's for
• Architecture -- System design and communication protocols
• BugTraceAI-CLI -- Autonomous scanner documentation
• BugTraceAI-WEB -- Web dashboard documentation
• BugTraceAI-API -- REST/MCP API-security service, evidence artifacts, and deployment guidance
• BugTraceAI-API on DeepWiki -- AI-powered codebase documentation and architecture exploration
• BugTraceAI-Launcher -- Deployment guide
• CLI API Reference -- CLI REST API and WebSocket endpoints
• Getting Started -- Installation and first scan

Community & Support

Contributing

We welcome contributions: bug reports, feature requests, PRs, documentation improvements, and community tools. Open an issue on the respective repository to get started.

License

Apache License 2.0 — BugTraceAI-owned material is free to use, modify, and distribute under the terms of the Apache License, Version 2.0.

See LICENSE file in each repository.

BugTraceAI -- Build your own self-hosted pentesting platform.
If BugTraceAI helps your authorized security research, consider giving the project a star or joining the community on Discord.
Albert C (@yz9yt)