# BBOT MCP Server
A Model Context Protocol (MCP) server for running [BBOT](https://github.com/blacklanternsecurity/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)
```bash
pip install bbot-mcp
```
### From Source
```bash
git clone https://github.com/marlinkcyber/bbot-mcp.git
cd bbot-mcp
pip install -e .
```
### Using uvx (Run without installing)
```bash
uvx bbot-mcp
```
## Install dependencies
It is recommended to install all BBOT dependencies before invoking BBOT MCP server:
```bash
bbot --install-all-deps
```
## Usage
### Running the MCP Server
After installation, the server can be started using the `bbot-mcp` command:
```bash
bbot-mcp
```
Or directly with Python:
```bash
python -m bbot_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 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:**
```python
# 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
## Development
### Testing
Run the test suite to verify functionality:
```bash
# Run all tests
pytest
# Run specific test categories
python tests/test_server.py
python tests/simple_test.py
python tests/test_imports.py
# Test the binary command
bbot-mcp --help
```
### Project Structure
```
bbot-mcp/
├── bbot_mcp/ # Main package
│ ├── __init__.py # Package initialization
│ └── server.py # MCP server implementation
├── tests/ # Test suite
├── pyproject.toml # Package configuration
├── README.md # This file
└── requirements.txt # Development dependencies
```
## Example MCP Client Usage
```python
# 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
You can exclude problematic modules by setting following environment variable:
```bash
export BBOT_EXCLUDE_MODULES="trufflehog,sslcert"
```
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
Raw data
{
"_id": null,
"home_page": null,
"name": "bbot-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bbot, mcp, scanner, security",
"author": null,
"author_email": "Vlatko Kosturjak <vlatko.kosturjak@marlink.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/d1/7db8a66761e36353baa47d0b561b41635de3fdc6a59971e7629fa312ed6c/bbot_mcp-0.1.4.tar.gz",
"platform": null,
"description": "# BBOT MCP Server\n\nA Model Context Protocol (MCP) server for running [BBOT](https://github.com/blacklanternsecurity/bbot) security scans. This server provides tools to manage and execute bbot scans through the MCP interface.\n\n## Features\n\n- **Module Management**: List and explore available bbot modules\n- **Preset Management**: List and use predefined scan configurations\n- **Scan Execution**: Start and manage long-running bbot scans\n- **Real-time Monitoring**: Check scan status and retrieve results\n- **Wait & Progress Tracking**: Wait for scan completion with timeout and progress reporting\n- **Concurrent Scans**: Support for multiple simultaneous scans\n- **Dependency Management**: Comprehensive sudo prevention and no-deps functionality\n\n## Installation\n\n### From PyPI (Recommended)\n```bash\npip install bbot-mcp\n```\n\n### From Source\n```bash\ngit clone https://github.com/marlinkcyber/bbot-mcp.git\ncd bbot-mcp\npip install -e .\n```\n\n### Using uvx (Run without installing)\n```bash\nuvx bbot-mcp\n```\n\n## Install dependencies\n\nIt is recommended to install all BBOT dependencies before invoking BBOT MCP server:\n\n```bash\nbbot --install-all-deps\n```\n\n## Usage\n\n### Running the MCP Server\n\nAfter installation, the server can be started using the `bbot-mcp` command:\n\n```bash\nbbot-mcp\n```\n\nOr directly with Python:\n```bash\npython -m bbot_mcp.server\n```\n\n### Available Tools\n\nThe MCP server provides **8 tools** for comprehensive bbot scan management:\n\n#### 1. `list_bbot_modules()`\nLists all available bbot modules categorized by type (scan, output, internal).\n\n#### 2. `list_bbot_presets()` \nLists all available bbot presets for quick scan configuration.\n\n#### 3. `start_bbot_scan(targets, modules=\"\", presets=\"\", flags=\"\", no_deps=True)`\nStarts a new bbot scan with the specified parameters.\n\n**Parameters:**\n- `targets`: Comma-separated list of targets (domains, IPs, URLs)\n- `modules`: Optional comma-separated list of modules to use\n- `presets`: Optional comma-separated list of presets to apply\n- `flags`: Optional comma-separated list of flags\n- `no_deps`: Disable dependency installation to prevent sudo prompts (default: True)\n\n**Example:**\n```\nstart_bbot_scan(\"example.com,google.com\", \"httpx,nmap\", \"web-basic\", \"safe\", True)\n```\n\n**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.\n\n#### 4. `get_scan_status(scan_id)`\nRetrieves the current status of a specific scan.\n\n#### 5. `get_scan_results(scan_id, limit=100)`\nRetrieves results from a completed or running scan.\n\n**Parameters:**\n- `scan_id`: The unique identifier of the scan\n- `limit`: Maximum number of results to return (default: 100)\n\n#### 6. `list_active_scans()`\nLists all currently active scans with their basic information.\n\n#### 7. `wait_for_scan_completion(scan_id, timeout=300, poll_interval=5, include_progress=True)`\nWaits for a scan to complete with timeout and progress reporting.\n\n**Parameters:**\n- `scan_id`: The ID of the scan to wait for\n- `timeout`: Maximum time to wait in seconds (default: 300 = 5 minutes)\n- `poll_interval`: How often to check scan status in seconds (default: 5)\n- `include_progress`: Whether to include progress updates in the response (default: True)\n\n**Returns:**\n- Success response with completion details, elapsed time, and progress updates\n- Timeout response if scan doesn't complete within the specified time\n- Error response for invalid scan IDs or other issues\n\n**Example:**\n```python\n# Wait for scan to complete with custom timeout\nresult = wait_for_scan_completion(\"scan-123\", timeout=600, poll_interval=10)\n```\n\n#### 8. `get_dependency_info()`\nProvides information about bbot's dependency management system and how the MCP server handles dependencies.\n\n## Scan Management\n\n### Scan Lifecycle\n1. **Starting**: Scan is being initialized\n2. **Running**: Scan is actively executing\n3. **Completed**: Scan finished successfully\n4. **Error**: Scan encountered an error\n\n### Long-running Scans\nScans run in separate threads to avoid blocking the MCP server. You can:\n- Start multiple scans concurrently\n- Check status while scans are running\n- Retrieve partial results from ongoing scans\n\n## Development\n\n### Testing\n\nRun the test suite to verify functionality:\n\n```bash\n# Run all tests\npytest\n\n# Run specific test categories\npython tests/test_server.py\npython tests/simple_test.py\npython tests/test_imports.py\n\n# Test the binary command\nbbot-mcp --help\n```\n\n### Project Structure\n\n```\nbbot-mcp/\n\u251c\u2500\u2500 bbot_mcp/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u2514\u2500\u2500 server.py # MCP server implementation\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 requirements.txt # Development dependencies\n```\n\n## Example MCP Client Usage\n\n```python\n# Connect to the MCP server and use the tools\nclient = MCPClient(\"bbot-scanner\")\n\n# List available modules\nmodules = client.call_tool(\"list_bbot_modules\")\n\n# Start a scan\nscan_result = client.call_tool(\"start_bbot_scan\", {\n \"targets\": \"example.com\",\n \"presets\": \"web-basic\"\n})\n\n# Check scan status\nstatus = client.call_tool(\"get_scan_status\", {\n \"scan_id\": scan_result[\"scan_id\"]\n})\n\n# Wait for scan to complete\ncompletion = client.call_tool(\"wait_for_scan_completion\", {\n \"scan_id\": scan_result[\"scan_id\"],\n \"timeout\": 300\n})\n\n# Get results when complete\nresults = client.call_tool(\"get_scan_results\", {\n \"scan_id\": scan_result[\"scan_id\"],\n \"limit\": 50\n})\n```\n\n## Security Considerations\n\n- This tool is designed for authorized security testing only\n- Always ensure you have permission to scan target systems\n- Be aware that bbot scans can be resource-intensive and may take significant time\n- Some modules may be considered intrusive - use the `--allow-deadly` equivalent flags carefully\n\n## Dependency Management\n\nThe MCP server includes comprehensive dependency management to prevent sudo password prompts:\n\n### Automatic Protection Measures\n- **Default Behavior**: `no_deps=True` - Dependencies are disabled by default\n- **Environment Variables**: Multiple layers of sudo prevention (SUDO_ASKPASS, DEBIAN_FRONTEND, etc.)\n- **Stdin Redirection**: Blocks all interactive input to prevent hanging\n- **Module Exclusions**: Problematic modules (sslcert, trufflehog) are automatically excluded\n- **Force Configuration**: Modules run even if dependencies fail\n\n### Key Features\n- **Comprehensive Sudo Prevention**: Multiple environment variables and configurations prevent any sudo prompts\n- **Graceful Degradation**: Scans continue even when some modules can't load dependencies\n- **Pre-installation Support**: Install dependencies manually if needed: `pip install <module-deps>`\n- **macOS Compatibility**: Special handling for Homebrew vs APT package manager conflicts\n\n### Excluded Modules\n\nYou can exclude problematic modules by setting following environment variable:\n```bash\nexport BBOT_EXCLUDE_MODULES=\"trufflehog,sslcert\"\n```\n\nExample exclude mentioned modules if you have any dependency issues (i.e. on Mac OS X):\n- `sslcert`: APT dependency incompatible with macOS Homebrew\n- `trufflehog`: Dependency installation conflicts\n\n**Override Option**: Set `no_deps=False` only if you're certain no sudo prompts will occur\n\nFor more information about bbot itself, visit: https://github.com/blacklanternsecurity/bbot\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for BBOT security scanner",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/marlinkcyber/bbot-mcp",
"Issues": "https://github.com/marlinkcyber/bbot-mcp/issues",
"Repository": "https://github.com/marlinkcyber/bbot-mcp"
},
"split_keywords": [
"bbot",
" mcp",
" scanner",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b57d420db2844948e55dbfe488976ea75f3084c7a8c4a4ecaedd39325a5235e8",
"md5": "77b155d5abd526b5c4a0fb9169d41593",
"sha256": "8507b13a8622061ed20d87e37154241088027c4890d7d2b4c08d0f9e20ad7949"
},
"downloads": -1,
"filename": "bbot_mcp-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77b155d5abd526b5c4a0fb9169d41593",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10451,
"upload_time": "2025-08-13T04:23:53",
"upload_time_iso_8601": "2025-08-13T04:23:53.594178Z",
"url": "https://files.pythonhosted.org/packages/b5/7d/420db2844948e55dbfe488976ea75f3084c7a8c4a4ecaedd39325a5235e8/bbot_mcp-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3d17db8a66761e36353baa47d0b561b41635de3fdc6a59971e7629fa312ed6c",
"md5": "72986a3818e981bfb5e87d185e1b00e8",
"sha256": "f2ee0faf613d2f3188d7aa45be6c7a1a2ca8e5a6c2afdeedccd4f348d7d3d5f6"
},
"downloads": -1,
"filename": "bbot_mcp-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "72986a3818e981bfb5e87d185e1b00e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18622,
"upload_time": "2025-08-13T04:23:54",
"upload_time_iso_8601": "2025-08-13T04:23:54.721965Z",
"url": "https://files.pythonhosted.org/packages/c3/d1/7db8a66761e36353baa47d0b561b41635de3fdc6a59971e7629fa312ed6c/bbot_mcp-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 04:23:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marlinkcyber",
"github_project": "bbot-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": []
},
{
"name": "bbot",
"specs": []
},
{
"name": "asyncio",
"specs": []
}
],
"lcname": "bbot-mcp"
}
JSON
