Purpose

Primary launcher for Flow A. Parses every CLI flag, loads config.yaml, bootstraps API keys and the ChatGPT provider runtime (bun + oauth/), and dispatches to the WebUI daemon, doctor/self-test/demo/eval/ctf, or the MCP-backed AssessmentService exploit/recon session. Delegates real work to tools/run_service, tools/mcp_session, and tools/exploit_session so main.py stays thin.

Source Files

Re-wrapped helpers (module-level re-exports for test patch points):

Responsibilities

• Define the full argparse surface (main.py:334 parse_args): targeting (--target/--mode/--goal), API keys, output, swarm/reasoning, operational (--doctor/--self-test/--eval/--ctf/--demo/--resume), skills, plugins, WebUI (--daemon (legacy alias: --demon)/--web).
• Start the WebUI API daemon (main.py:708 _run_daemon) with loopback-only bind, optional WebUI build (main.py:464 _ensure_webui_build), and bearer-token gate.
• Ensure ChatGPT provider prerequisites (main.py:551 _ensure_chatgpt_runtime): bun install, oauth/ clone + bun install + bun run build.
• Provide async_main(args) (main.py:794) — the CLI adapter that builds a RunRequest, calls AssessmentService.prepare → renders summary via AttackUi → asks ready-to-begin confirmation → calls AssessmentService.execute.
• Emit per-run LLM telemetry (main.py:222 _llm_usage_line_count, main.py:269 _run_telemetry) from llm_usage.jsonl.

Public Interfaces

Constants / Globals

Functions

Inputs/Outputs

State/Persistence

• No DB writes directly; delegates to AssessmentService / ApiPersistence / RunManager.
• In-memory Callables bundle (main.py:895) threads patched symbols into service for test monkeypatching.
• WebUI token file .webui_secret_key (gitignored) loaded/created via tools/api/auth.load_or_create_token.

Configuration

All behavior via config.yaml top-level keys (see README §Configuration):

• models.provider (ollama default | chatgpt), ollama.host (https://api.ollama.com), ollama.embed_host
• mcp, nmap, exploit (permission, attack_mode, timeouts, allowed_targets), swarm, api (host/port, event_buffer_size, serve_webui, multi_operator)
• CLI flags override config; apply_skills_cli_overrides merges --skills*.

Dependencies

• tools/config_cli (load_config, bootstrap_startup_api_keys, add_target_to_allowlist)
• tools/mcp_session (open_exploit_mcp_session, mcp_tools_to_ollama, MCP_BOOT_TIMEOUT_SECONDS)
• tools/exploit_session (run_exploit_session)
• tools/run_service (AssessmentService, Callables, RunRequest, TerminalDecisionProvider, TerminalEventSink)
• tools/goal_engine.GoalEngine, tools/model_router.build_router, tools/safety_reviewer.SafetyReview, tools/attack_ui.get_ui, tools/exceptions._EXC_GROUP_CATCH
• app.create_app (via _run_daemon), uvicorn, webbrowser, shutil/subprocess for WebUI build

Used By

• Operator directly: python main.py ... (default entry point)
• Tests monkeypatch main.open_exploit_mcp_session, main.run_exploit_session, main.build_router, etc.
• app.py is invoked from main._run_daemon

Control Flow

flowchart TD
    A[parse_args] --> B{flags?}
    B -->|--web/--daemon| C[_run_daemon -> create_app -> uvicorn]
    B -->|--doctor| D[tools/doctor.run_doctor]
    B -->|--self-test| E[tools/self_test.run_self_test]
    B -->|--eval/--ctf/--demo| F[specialist harness]
    B -->|otherwise| G[async_main]
    G --> H[load_config + apply_skills_cli_overrides]
    H --> I[AssessmentService.prepare -> RunPreview]
    I --> J[render summary + ready-to-begin gate]
    J --> K[AssessmentService.execute -> MCP session -> exploit loop]
    K --> L[exit code]

Failure Modes

Invariants

• main.py never calls Ollama directly; all LLM I/O through build_router / run_exploit_session.
• --daemon (legacy alias: --demon)/--web mutually exclusive with --target/--mode/--goal/--doctor/--self-test (exit 2).
• Missing-key exploit permission falls back to read_only (via tools/cli_exploit_settings), never full_access.
• Fast path always forces MCP transport to http so target-IP lock reaches server.

Security Boundaries

• API daemon is loopback-only (127.0.0.1/localhost/::1); public bind refused.
• Bearer token from .webui_secret_key or BREACHPILOT_API_TOKEN guards /api/v1.
• Allowlist lock: AssessmentService.prepare resolves domain→IP and persists new domain IP to config.yaml exploit allowlist for interactive sessions.
• full_access is the lab attack posture; recon stays read_only.

Tests

Run: python -m pytest tests/test_main_fixes.py tests/test_config_cli.py -v

Common Changes

Update This Document When

• A top-level CLI flag, arg group, or mutual-exclusion rule is added/removed.
• Daemon/WebUI boot, ChatGPT runtime setup, or telemetry tail changes.
• async_main's RunRequest construction or Callables bundle changes.

Related Documentation

• docs/architecture.md §Entry Points / Flow A
• docs/runtime-flows.md §Exploit Session / Recon-First / Domain Targeting
• docs/cli-reference.md — full flag reference
• app.py (docs/components/root/app.md), tools/run_service/service.py, tools/mcp_session.py, tools/exploit_session.py