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
- Install dependencies:
- Install bbot (if not already installed):
Usage
Running the MCP Server
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 usepresets
: Optional comma-separated list of presets to applyflags
: Optional comma-separated list of flagsno_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 scanlimit
: 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 fortimeout
: 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.
Scan Management
Scan Lifecycle
- Starting: Scan is being initialized
- Running: Scan is actively executing
- Completed: Scan finished successfully
- 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:
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
The following modules are automatically excluded due to dependency issues:
sslcert
: APT dependency incompatible with macOS Homebrewtrufflehog
: Dependency installation conflicts
Override Option: Set no_deps=False
only if you're certain no sudo prompts will occur
Troubleshooting
Common Issues
- Import Errors: Ensure bbot is properly installed:
pip install bbot mcp
- 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>
- Ensure
- Scan Timeouts: Use
wait_for_scan_completion
with appropriate timeout values - 0 Results: Check preset/flag configuration and module exclusions
- Long Scan Times: Bbot scans can take hours depending on scope and modules
- 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
This server cannot be installed
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.
Related MCP Servers
- AsecurityAlicenseAqualityA 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 -38PythonMIT License
- -securityFlicense-qualityMCP server to perform various OSINT tasks by leveraging common network reconnaissance tools.Last updated -28Python
- PythonApache 2.0
- -securityAlicense-qualityAn 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 -2PythonMIT License