TheHive MCP Server

# MCP Server for TheHive An MCP (Model Context Protocol) server that provides AI models and automation tools with access to TheHive incident response platform. ## Overview This server acts as a bridge between MCP clients (like AI assistants) and TheHive, allowing them to: - Retrieve and analyze security alerts - Access case information - Promote alerts to cases - Perform incident response operations ## Features ### Available Tools 1. **get_thehive_alerts** - Retrieve a list of alerts from TheHive - Optional `limit` parameter (default: 100) - Returns formatted alert information including ID, title, severity, and status 2. **get_thehive_alert_by_id** - Get detailed information about a specific alert - Required `alert_id` parameter - Returns comprehensive alert details 3. **get_thehive_cases** - Retrieve a list of cases from TheHive - Optional `limit` parameter (default: 100) - Returns formatted case information 4. **get_thehive_case_by_id** - Get detailed information about a specific case - Required `case_id` parameter - Returns comprehensive case details 5. **promote_alert_to_case** - Promote an alert to a case - Required `alert_id` parameter - Returns information about the newly created case 6. **create_thehive_case** - Create a new case in TheHive - Required `title` and `description` parameters - Optional parameters: `severity`, `tags`, `tlp`, `pap`, `status`, `assignee`, `case_template`, `start_date` - Returns information about the newly created case ## Installation ### Prerequisites - Access to a TheHive 5 instance - Valid TheHive API token ### Downloading Pre-compiled Binaries You can download pre-compiled binaries for various operating systems from the [GitHub Releases page](https://github.com/gbrigandi/mcp-server-thehive/releases). Download the appropriate binary for your system, make it executable, and place it in your desired location. ### Building from Source ```bash git clone <repository-url> cd mcp-server-thehive cargo build --release ``` ## Configuration The server requires the following environment variables: - `THEHIVE_URL` - TheHive API base URL (default: `http://localhost:9000/api`) - `THEHIVE_API_TOKEN` - TheHive API token (required) - `VERIFY_SSL` - Whether to verify SSL certificates (default: `false`) - `RUST_LOG` - Logging level (optional, e.g., `debug`, `info`) ### Environment File Create a `.env` file in the project root: ```env THEHIVE_URL=https://your-thehive-instance.com/api THEHIVE_API_TOKEN=your-api-token-here VERIFY_SSL=true RUST_LOG=info ``` ### Getting a TheHive API Token 1. Log into your TheHive instance 2. Go to **User Settings** → **API Keys** 3. Click **Create API Key** 4. Copy the generated token and use it as `THEHIVE_API_TOKEN` ## Usage ### Running the Server ```bash # Using cargo cargo run # Using the built binary ./target/release/mcp-server-thehive ``` ### Integration with MCP Clients The server communicates over stdio using the MCP protocol. Configure your MCP client to use this server: ```json { "mcpServers": { "thehive": { "command": "/path/to/mcp-server-thehive", "env": { "THEHIVE_URL": "https://your-thehive-instance.com:9000/api", "THEHIVE_API_TOKEN": "your-api-token-here" } } } } ``` ## Examples ### Retrieving Recent Alerts ```json { "method": "tools/call", "params": { "name": "get_thehive_alerts", "arguments": { "limit": 10 } } } ``` ### Getting Alert Details ```json { "method": "tools/call", "params": { "name": "get_thehive_alert_by_id", "arguments": { "alert_id": "~123456" } } } ``` ### Promoting an Alert to Case ```json { "method": "tools/call", "params": { "name": "promote_alert_to_case", "arguments": { "alert_id": "~123456" } } } ``` ### Creating a New Case ```json { "method": "tools/call", "params": { "name": "create_thehive_case", "arguments": { "title": "Potential Malware Outbreak", "description": "Multiple endpoints reporting suspicious process activity.", "severity": 3, "tags": ["malware", "endpoint", "epp"], "tlp": 2, "assignee": "soc_level2" } } } ``` ## Development ### Project Structure ``` mcp-server-thehive/ ├── src/ │ ├── main.rs # Main server implementation │ ├── lib.rs # Library exports │ └── thehive/ │ ├── mod.rs # Module declarations │ ├── client.rs # TheHive API client │ └── error.rs # Error types ├── tests/ │ ├── bin/ │ │ └── mock_thehive_server.rs # Mock TheHive API server for testing │ ├── integration_test.rs # Integration tests │ └── mcp_stdio_test.rs # Stdio interface tests ├── Cargo.toml # Dependencies and metadata └── README.md # This file ``` ### Dependencies - **rmcp** - MCP protocol implementation - **thehive-client** - TheHive API client library - **tokio** - Async runtime - **reqwest** - HTTP client - **serde** - Serialization framework - **tracing** - Logging and instrumentation ### Testing The project includes a comprehensive suite of integration tests that leverage a mock TheHive server. This mock server simulates the TheHive API, allowing for isolated and repeatable testing of the MCP server's functionality without requiring a live TheHive instance. **Running Tests:** ```bash # Run all tests (including integration tests that use the mock server) cargo test # Run tests with verbose logging (includes MCP server and mock server logs) RUST_LOG=debug MCP_SERVER_THEHIVE_VERBOSE_TEST_LOGS=true cargo test ``` ## Security Considerations - Store API tokens securely (use environment variables or secure credential stores) - Never commit API tokens to version control - Enable SSL verification in production environments - Limit network access to TheHive instance - Use least-privilege API tokens for TheHive access - Monitor and log all API interactions - Rotate API tokens regularly ## Troubleshooting ### Common Issues 1. **Connection Refused** - Verify `THEHIVE_URL` is correct - Check network connectivity to TheHive instance - Ensure TheHive is running and accessible 2. **Authentication Failed** - Verify `THEHIVE_API_TOKEN` is correct and not expired - Check if the API token has necessary permissions - Ensure the token is properly formatted 3. **SSL Certificate Errors** - Set `VERIFY_SSL=false` for testing (not recommended for production) - Install proper SSL certificates - Use valid certificate authority ### Logging Enable debug logging for troubleshooting: ```bash RUST_LOG=debug cargo run ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Related Projects - [thehive-client-rs](https://github.com/gbrigandi/thehive-client-rs) - Rust client library for TheHive API - [mcp-server-cortex](https://github.com/gbrigandi/mcp-server-cortex) - MCP server for Cortex - [mcp-server-wazuh](https://github.com/gbrigandi/mcp-server-wazuh) - MCP server for Wazuh SIEM