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

1. Install dependencies:

pip install -r requirements.txt

2. Install bbot (if not already installed):

pip install bbot

Usage

Running the MCP Server

python bbot_mcp_server.py

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:

start_bbot_scan("example.com,google.com", "httpx,nmap", "web-basic", "safe", True)

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:

# Wait for scan to complete with custom timeout
result = wait_for_scan_completion("scan-123", timeout=600, poll_interval=10)

8. get_dependency_info()

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

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

Testing

Run the test suite to verify functionality:

python test_server.py

Example MCP Client Usage

# Connect to the MCP server and use the tools
client = MCPClient("bbot-scanner")

# List available modules
modules = client.call_tool("list_bbot_modules")

# Start a scan
scan_result = client.call_tool("start_bbot_scan", {
    "targets": "example.com",
    "presets": "web-basic"
})

# Check scan status
status = client.call_tool("get_scan_status", {
    "scan_id": scan_result["scan_id"]
})

# Wait for scan to complete
completion = client.call_tool("wait_for_scan_completion", {
    "scan_id": scan_result["scan_id"],
    "timeout": 300
})

# Get results when complete
results = client.call_tool("get_scan_results", {
    "scan_id": scan_result["scan_id"],
    "limit": 50
})

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

The following modules are automatically excluded due to dependency issues:

• 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

Troubleshooting

Common Issues

1. Import Errors: Ensure bbot is properly installed: pip install bbot mcp
2. Sudo Password Prompts: The server includes comprehensive protection, but if you encounter prompts:
   • Ensure no_deps=True (default)
   • Check environment variables are set correctly
   • Manually install dependencies: pip install <module-deps>
3. Scan Timeouts: Use wait_for_scan_completion with appropriate timeout values
4. 0 Results: Check preset/flag configuration and module exclusions
5. Long Scan Times: Bbot scans can take hours depending on scope and modules
6. Memory Usage: Large scans may consume significant memory

macOS Specific Issues

• sslcert Module: Automatically excluded due to APT/Homebrew incompatibility
• Package Manager: Use Homebrew instead of APT for manual dependency installation
• OpenSSL: Ensure OpenSSL 3.x is installed via Homebrew

Development Notes

• Testing: Run python test_wait_completion.py to verify functionality
• Logs: Check console output for detailed scan progress and error information
• MCP Integration: Server runs on standard MCP protocol with JSON-formatted responses

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