BBOT

You run BBOT security scans via a Model Context Protocol (MCP) server. This MCP server lets you manage modules and presets, start and monitor long-running scans, and retrieve results while keeping multiple scans running concurrently. It is designed to prevent unnecessary prompts and to provide real-time status and progress reporting for efficient security assessments.

How to use

Connect to the MCP server with your MCP client and use the available tools to list modules, presets, and to start scans. You can monitor ongoing scans, check statuses, and fetch results as soon as they are ready. Scans run in the background, and you can wait for completion with optional timeouts and progress updates. You can run multiple scans at the same time and retrieve partial results from those scans while they are still running.

How to install

Prerequisites: ensure you have Python and a working internet connection. You also need a runtime command available for the MCP integration shown here.

# Install the MCP server package from PyPI
pip install bbot-mcp

# Or install from source
git clone https://github.com/marlinkcyber/bbot-mcp.git
cd bbot-mcp
pip install -e .

# Run the MCP server directly
uvx bbot-mcp

# Or run via Python module
python -m bbot_mcp.server

# Optional: install all BBOT dependencies to prepare for scans
bbot --install-all-deps

Additional notes

The MCP server includes a ready-to-use configuration example that demonstrates how to register a local MCP host. This example shows a local stdio-based server that can be invoked via a wrapper like uvx.

{
  "mcpServers": {
    "bbot": {
      "command": "uvx",
      "args": ["--refresh","bbot-mcp"]
    }
  }
}

Available tools

list_bbot_modules

Lists all available bbot modules categorized by type (scan, output, internal).

list_bbot_presets

Lists all available bbot presets for quick scan configuration.

start_bbot_scan

Starts a new bbot scan with specified targets, modules, presets and flags. Includes an option to disable dependency installation to prevent sudo prompts.

get_scan_status

Retrieves the current status of a specific scan.

get_scan_results

Retrieves results from a completed or running scan with an optional limit.

list_active_scans

Lists all currently active scans with basic information.

wait_for_scan_completion

Waits for a scan to complete with timeout and progress reporting, returning completion details or a timeout/error.

get_dependency_info

Provides information about dependency management and how the MCP server handles dependencies.