Skip to main content
Glama

BBOT MCP Server

by marlinkcyber

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
  1. 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

-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables users to run and manage BBOT security scans through the MCP interface. Provides comprehensive tools for executing reconnaissance scans, monitoring progress, and retrieving results with support for concurrent scanning operations.

  1. Features
    1. Installation
      1. Usage
        1. Running the MCP Server
        2. Available Tools
      2. Scan Management
        1. Scan Lifecycle
        2. Long-running Scans
      3. Testing
        1. Example MCP Client Usage
          1. Security Considerations
            1. Dependency Management
              1. Automatic Protection Measures
              2. Key Features
              3. Excluded Modules
            2. Troubleshooting
              1. Common Issues
              2. macOS Specific Issues
              3. Development Notes

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              A Model Control Protocol server that provides access to nmap network scanning functionality, allowing users to run customizable scans, store results, and analyze network security using AI prompts.
              Last updated -
              3
              8
              Python
              MIT License
              • Linux
            • -
              security
              F
              license
              -
              quality
              MCP server to perform various OSINT tasks by leveraging common network reconnaissance tools.
              Last updated -
              28
              Python
            • -
              security
              A
              license
              -
              quality
              An intelligent layered port scanning service based on MCP protocol, designed for AI assistants and development tools to perform network security analysis with real-time feedback.
              Last updated -
              2
              Python
              MIT License

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/marlinkcyber/bbot-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server