BugTraceAI-CLI is an LLM-guided web pentesting engine that runs a six-stage scan pipeline with specialist agents and browser validation, intended strictly for authorized security assessments.

BugTraceAI-CLI is the web-scanning engine of the broader BugTraceAI suite, an Apache-2.0 licensed Python project currently at 4.0.37-beta with roughly 185 stars. Its pitch is agentic web pentesting: LLM-guided investigation combined with deterministic specialist tools and browser-based validation, all observable from a terminal workspace built on Textual. The README is explicit and refreshingly direct on scope — use it only against applications you are authorized to test — and that framing matters for a tool whose pipeline literally includes an Exploit stage. For defenders and authorized testers, the interesting question is how the architecture separates LLM reasoning from evidence collection, and that separation is visible throughout the documentation.

The core workflow follows a fixed six-stage pipeline: Recon → Discovery → Strategy → Exploit → Validate → Report. The TUI keeps this pipeline permanently visible as a phase strip with counters and timings, so an operator can watch where the engine is spending its budget at any moment. Target configuration sits at the top of the interface — a target URL plus Depth and Max URLs crawl limits — which gives the operator direct control over scan blast radius, a detail that matters when testing shared staging environments. The stage names tell you the engine does not stop at passive fingerprinting; it attempts candidate findings and then validates them through tool and browser evidence before anything reaches the report.

Specialist coverage is the meat of the scan engine. The shared engine discovers endpoints, analyzes candidate findings, routes work to specialist agents, and collects evidence through validation and reporting. The listed specialist classes are SQL injection, XSS, SSRF, IDOR, LFI, RCE, template injection, XXE, JWT and redirect checks — a conventional DAST class list, but the differentiator is the routing model: rather than one monolithic scanner loop, work is queued to named specialists whose states, queues and processed counts are visible in the dedicated Agents view (F4). This multi-agent decomposition is what lets the operator reason about scan progress per vulnerability class instead of staring at an opaque progress bar.

The LLM side is provider-agnostic by design. Provider presets include OpenRouter, Anthropic and Z.ai, configured through the Provider dialog (F7) with a masked API key field. Notably, a real scan requires a provider key — the workspace opens without one, but the engine will not start. There is a session-only mode: unchecking Save this key in local .env keeps a new key in memory for the current session only, a sensible hygiene control for consultants rotating between client engagements. The README also repeatedly warns against pasting provider keys into AI coding-agent chats, which suggests the maintainers have seen operators fumble exactly that.

Target authentication is handled separately from provider configuration, in Auth (F8). The engine accepts a masked Bearer token or a WEB-compatible login YAML with optional TOTP/2FA, and those target credentials stay in the TUI session rather than being written to disk with the install profile. Auth can be edited before a scan or after it finishes, which supports re-authenticating against targets with short-lived session tokens mid-engagement. The YAML format and examples live in INSTALLATION.md, so the credential schema is inspectable before you trust the tool with a client login.

Installation is deliberately modular. The recommended path is the universal BugTraceAI-Launcher, which can install the WEB, CLI and API-target engines independently or in combination, with an Install with Wizard guided flow and an Install with AI assistant that itself runs inside the TUI using OpenRouter or Anthropic tokens. Direct installation from a checkout is also documented: ./scripts/install-runtime.sh --interface tui --runtime local --global yes registers the global btai command, while --interface api or --runtime docker produce an API/MCP deployment with FastAPI, Uvicorn, WebSockets and MCP support. Choices persist in .bugtrace-install.env without API keys, and --reuse updates or repairs a saved profile.

The automation surface is where BugTraceAI-CLI distinguishes itself from a typical TUI scanner. The same engine backs BugTraceAI-WEB for a browser workspace, and exposes REST and MCP interfaces for programmatic control — meaning the scanner can be orchestrated by other agents or CI pipelines rather than driven by hand. The Docker profiles reflect this split: docker-compose.tui.yml runs an interactive scanner with no published server ports, while the combined profile lets you open the TUI inside the API container with docker compose exec api python3 -m bugtrace tui. Some specialist tools also use Docker during local scans, which is worth knowing before pointing this at a hardened engagement laptop.

Keyboard-driven operation is thorough: F2 through F6 cover Pipeline, Findings, Agents, Timeline and Logs views, with Ctrl+S/Ctrl+X to start and stop, Ctrl+E to export findings, and a command bar accepting /help, /provider, /auth, /pause, /resume, /stop, /findings and /export. Pause only takes effect at the next pipeline checkpoint, which implies the engine runs stage-atomic work units rather than interruptible requests — relevant when you need a scan to halt cleanly without orphaning half-finished validation attempts. The Logs view filters engine output by agent, and Timeline records scan milestones and alerts, which together give a defensible audit trail of what the tool did and when.

Evidence handling appears designed for professional reporting rather than flag-dumping. The Findings view supports search, sort, inspection and export, and the README states that tool and browser evidence accompanies reported findings — meaning each specialist conclusion is backed by reproducible artifacts, not just an LLM's assertion. For bug bounty work this is the difference between a submittable report and a hallucinated finding; the validation stage exists precisely to keep the LLM honest by confirming candidates through deterministic tools and a real browser before they are surfaced.

A few operational cautions are worth flagging. The project is beta-versioned (4.0.37-beta), the screenshots partly use an offline demo mode (./bugtraceai-cli tui --demo), and the installer can pull Docker tooling automatically — reviewing the checked modules and runtime before installing, as the README itself advises, is sound practice. The curl-pipe-to-bash Launcher pattern is documented but should be read before run. From a defensive perspective, the engine's crawl-plus-inject behavior across ten vulnerability classes produces highly recognizable traffic signatures; blue teams should treat coordinated multi-vector probing with browser-like validation as a signal of automated agentic tooling, authorized or otherwise. Within scope, on owned targets, this is a well-architected example of the current agentic-scanner generation.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.

Related coverage

• SUASS for centralized offensive security study notes


• commix-testbed for studying command and code injection flaws in a controlled lab


• 3os.org as a shared knowledge base for devops, pentest and sysadmin work