MCP Server for TheHive

TheHive MCP 服务

一个 MCP（Model Context Protocol）服务，为 AI 模型和自动化工具提供访问 TheHive 事件响应平台的能力。

概述

此服务充当 MCP 客户端（例如 AI 助手）与 TheHive 之间的桥梁，使其能够：

• 检索并分析安全警报
• 访问案件信息
• 将警报升级为案件
• 执行事件响应操作

功能

可用工具

1. get_thehive_alerts - 从 TheHive 检索警报列表

   • 可选的 limit 参数（默认值：100）
   • 返回格式化的警报信息，包括 ID、标题、严重程度和状态

2. get_thehive_alert_by_id - 获取特定警报的详细信息

   • 必需的 alert_id 参数
   • 返回全面的警报详情

3. get_thehive_cases - 从 TheHive 检索案件列表

   • 可选的 limit 参数（默认值：100）
   • 返回格式化的案件信息

4. get_thehive_case_by_id - 获取特定案件的详细信息

   • 必需的 case_id 参数
   • 返回全面的案件详情

5. promote_alert_to_case - 将警报升级为案件

   • 必需的 alert_id 参数
   • 返回新建案件的信息

6. create_thehive_case - 在 TheHive 中创建新案件

   • 必需的 title 和 description 参数
   • 可选参数：severity、tags、tlp、pap、status、assignee、case_template、start_date
   • 返回新建案件的信息

安装

先决条件

• 可访问 TheHive 5 实例
• 有效的 TheHive API 令牌

下载预编译二进制文件

你可以从 GitHub Releases 页面下载适用于各种操作系统的预编译二进制文件。下载适用于你系统的二进制文件，将其设为可执行文件，并放置在所需位置。

从源代码构建

git clone <repository-url>
cd mcp-server-thehive
cargo build --release

配置

服务需要以下环境变量：

• THEHIVE_URL - TheHive API 基础 URL（默认值：http://localhost:9000/api）
• THEHIVE_API_TOKEN - TheHive API 令牌（必需）
• VERIFY_SSL - 是否验证 SSL 证书（默认值：false）
• RUST_LOG - 日志级别（可选，例如 debug、info）

环境文件

在项目根目录中创建 .env 文件：

THEHIVE_URL=https://your-thehive-instance.com/api
THEHIVE_API_TOKEN=your-api-token-here
VERIFY_SSL=true
RUST_LOG=info

获取 TheHive API 令牌

1. 登录 TheHive 实例
2. 前往 用户设置 → API 密钥
3. 点击 创建 API 密钥
4. 复制生成的令牌，并将其用作 THEHIVE_API_TOKEN

使用方法

运行服务

# Using cargo
cargo run

# Using the built binary
./target/release/mcp-server-thehive

与 MCP 客户端集成

此服务使用 MCP 协议通过标准输入输出进行通信。配置 MCP 客户端以使用此服务：

{
  "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"
      }
    }
  }
}

示例

检索最近的警报

{
  "method": "tools/call",
  "params": {
    "name": "get_thehive_alerts",
    "arguments": {
      "limit": 10
    }
  }
}

获取警报详情

{
  "method": "tools/call",
  "params": {
    "name": "get_thehive_alert_by_id",
    "arguments": {
      "alert_id": "~123456"
    }
  }
}

将警报升级为案件

{
  "method": "tools/call",
  "params": {
    "name": "promote_alert_to_case",
    "arguments": {
      "alert_id": "~123456"
    }
  }
}

创建新案件

{
  "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"
    }
  }
}

开发

项目结构

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

依赖项

• rmcp - MCP 协议实现
• thehive-client - TheHive API 客户端库
• tokio - 异步运行时
• reqwest - HTTP 客户端
• serde - 序列化框架
• tracing - 日志记录和检测

测试

此项目包含一套全面的集成测试，利用模拟 TheHive 服务。该模拟服务会模拟 TheHive API，从而能够隔离并重复测试 MCP 服务的功能，无需连接实际的 TheHive 实例。

运行测试：

# 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

安全注意事项

• 安全存储 API 令牌（使用环境变量或安全凭据存储）
• 切勿将 API 令牌提交到版本控制系统
• 在生产环境中启用 SSL 验证
• 限制对 TheHive 实例的网络访问
• 使用具有最小权限的 API 令牌访问 TheHive
• 监控并记录所有 API 交互
• 定期轮换 API 令牌

故障排除

常见问题

1. 连接被拒绝

   • 确认 THEHIVE_URL 正确
   • 检查与 TheHive 实例的网络连接
   • 确保 TheHive 正在运行且可访问

2. 身份验证失败

   • 确认 THEHIVE_API_TOKEN 正确且未过期
   • 检查 API 令牌是否具有必要的权限
   • 确保令牌格式正确

3. SSL 证书错误

   • 测试时设置 VERIFY_SSL=false（不建议用于生产环境）
   • 安装正确的 SSL 证书
   • 使用有效的证书颁发机构

日志记录

启用调试日志以排查问题：

RUST_LOG=debug cargo run

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

相关项目

• thehive-client-rs - TheHive API 的 Rust 客户端库
• mcp-server-cortex - Cortex 的 MCP 服务
• mcp-server-wazuh - Wazuh SIEM 的 MCP 服务