BBOT MCP Server

A Model Context Protocol (MCP) server for running BBOT security scans. This server provides tools to manage and execute bbot scans through the MCP interface.

Features

• Module Management: List and explore available bbot modules

• Preset Management: List and use predefined scan configurations

• Scan Execution: Start and manage long-running bbot scans

• Real-time Monitoring: Check scan status and retrieve results

• Wait & Progress Tracking: Wait for scan completion with timeout and progress reporting

• Concurrent Scans: Support for multiple simultaneous scans

• Dependency Management: Comprehensive sudo prevention and no-deps functionality

Installation

From PyPI (Recommended)

From Source

Using uvx (Run without installing)

Install dependencies

It is recommended to install all BBOT dependencies before invoking BBOT MCP server:

Usage

Running the MCP Server

After installation, the server can be started using the bbot-mcp command:

Or directly with Python:

Available Tools

The MCP server provides 8 tools for comprehensive bbot scan management:

1. list_bbot_modules()

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

2. list_bbot_presets()

Lists all available bbot presets for quick scan configuration.

3. start_bbot_scan(targets, modules="", presets="", flags="", no_deps=True)

Starts a new bbot scan with the specified parameters.

Parameters:

• targets: Comma-separated list of targets (domains, IPs, URLs)

• modules: Optional comma-separated list of modules to use

• presets: Optional comma-separated list of presets to apply

• flags: Optional comma-separated list of flags

• no_deps: Disable dependency installation to prevent sudo prompts (default: True)

Example:

Important: The no_deps=True parameter prevents bbot from attempting to install missing dependencies, which would cause sudo password prompts that hang the MCP server.

4. get_scan_status(scan_id)

Retrieves the current status of a specific scan.

5. get_scan_results(scan_id, limit=100)

Retrieves results from a completed or running scan.

Parameters:

• scan_id: The unique identifier of the scan

• limit: Maximum number of results to return (default: 100)

6. list_active_scans()

Lists all currently active scans with their basic information.

7. wait_for_scan_completion(scan_id, timeout=300, poll_interval=5, include_progress=True)

Waits for a scan to complete with timeout and progress reporting.

Parameters:

• scan_id: The ID of the scan to wait for

• timeout: Maximum time to wait in seconds (default: 300 = 5 minutes)

• poll_interval: How often to check scan status in seconds (default: 5)

• include_progress: Whether to include progress updates in the response (default: True)

Returns:

• Success response with completion details, elapsed time, and progress updates

• Timeout response if scan doesn't complete within the specified time

• Error response for invalid scan IDs or other issues

Example:

8. get_dependency_info()

Provides information about bbot's dependency management system and how the MCP server handles dependencies.

MCP config example:

Scan Management

Scan Lifecycle

1. Starting: Scan is being initialized

2. Running: Scan is actively executing

3. Completed: Scan finished successfully

4. Error: Scan encountered an error

Long-running Scans

Scans run in separate threads to avoid blocking the MCP server. You can:

• Start multiple scans concurrently

• Check status while scans are running

• Retrieve partial results from ongoing scans

Development

Testing

Run the test suite to verify functionality:

Project Structure

Example MCP Client Usage

Security Considerations

• This tool is designed for authorized security testing only

• Always ensure you have permission to scan target systems

• Be aware that bbot scans can be resource-intensive and may take significant time

• Some modules may be considered intrusive - use the --allow-deadly equivalent flags carefully

Dependency Management

The MCP server includes comprehensive dependency management to prevent sudo password prompts:

Automatic Protection Measures

• Default Behavior: no_deps=True - Dependencies are disabled by default

• Environment Variables: Multiple layers of sudo prevention (SUDO_ASKPASS, DEBIAN_FRONTEND, etc.)

• Stdin Redirection: Blocks all interactive input to prevent hanging

• Module Exclusions: Problematic modules (sslcert, trufflehog) are automatically excluded

• Force Configuration: Modules run even if dependencies fail

Key Features

• Comprehensive Sudo Prevention: Multiple environment variables and configurations prevent any sudo prompts

• Graceful Degradation: Scans continue even when some modules can't load dependencies

• Pre-installation Support: Install dependencies manually if needed: pip install <module-deps>

• macOS Compatibility: Special handling for Homebrew vs APT package manager conflicts

Excluded Modules

You can exclude problematic modules by setting following environment variable:

Example exclude mentioned modules if you have any dependency issues (i.e. on Mac OS X):

• sslcert: APT dependency incompatible with macOS Homebrew

• trufflehog: Dependency installation conflicts

Override Option: Set no_deps=False only if you're certain no sudo prompts will occur

For more information about bbot itself, visit: https://github.com/blacklanternsecurity/bbot