AI导哈

安全事件分析服务器

QRadar MCP Server是一款智能安全事件分析助手，提供数据查询和自动化根因分析功能，适用于IBM QRadar的安全事件处理。

  • by azixiong
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 azixiong/QRadar_MCP_Server

使用说明

QRadar MCP 服务器

一个生产就绪的模型上下文协议（MCP）服务器，作为IBM QRadar的智能安全事件分析助手。此服务器提供数据查询功能和安全事件的高级自动化根本原因分析。

概述

QRadar MCP服务器弥合了QRadar SIEM和人工智能安全分析之间的差距。它提供：

  1. 数据查询模块：与QRadar REST API直接集成，用于检索安全事件、日志和执行自定义查询
  2. 智能分析模块：自动根本原因分析、指标提取、时间线重建和可操作的调查建议

特性

数据查询工具

  • search_offenses：按时间范围、严重程度、状态和类型搜索安全违规行为
  • get_offense_details：检索特定犯罪的全面细节
  • get_offense_logs：获取与犯罪相关的所有日志条目
  • execute_aql_query：执行自定义AQL（Ariel查询语言）查询，以获得最大的灵活性

智能分析工具

  • analyze_offense：执行全面的根本原因分析，包括：

    • 自动指示符提取（IP、域、用户名、哈希）
    • 攻击时间线重建
    • 攻击模式识别
    • 结构化调查报告生成

  • recommend_investigation_actions：生成优先、可操作的建议，例如：

    • EDR端点查询
    • 网络隔离步骤
    • 用户帐户调查
    • 威胁情报检查
    • IAM权限审查

安装

先决条件

  • Python 3.11或更高版本
  • 使用API凭据访问QRadar实例
  • QRadar用于身份验证的用户名和密码

设置

  1. 克隆或下载此存储库

  2. 安装依赖项:

    pip install -r requirements.txt

    这将安装所有必需的依赖，包括 python-dotenv（用于加载 .env 文件）。

  3. 配置环境变量:

    重要：必须创建 .env 文件来配置环境变量！

    a. 复制示例配置文件：

    Windows（PowerShell）:

    Copy-Item env.example .env

    Windows（CMD）:

    copy env.example .env

    Linux/Mac:

    cp env.example .env

    b. 编辑 .env 文件，填入你的 QRadar 配置信息：

    视窗: 使用记事本或其他文本编辑器打开 .env 文件

    notepad .env

    Linux/Mac: 使用你喜欢的文本编辑器

    nano .env
# 或
vim .env

    c. 在 .env 文件中设置以下必需的环境变量：

    QRADAR_HOST=https://your-qradar-instance.com
QRADAR_USERNAME=your-username
QRADAR_PASSWORD=your-password

    d. 可选的环境变量（如不设置将使用默认值）：

    QRADAR_TIMEOUT=30          # 请求超时时间（秒），默认：30
QRADAR_VERIFY_SSL=true     # SSL 证书验证，默认：true

    注意：

    • .env 文件包含敏感信息，请确保不要将其提交到版本控制系统
    • .env 文件已在 .gitignore 中被忽略
    • 不要使用 export 命令设置环境变量，请使用 .env 文件

  4. 验证安装：

    确保 .env 文件已正确配置后，可以运行服务器进行测试：

    python main.py

    如果配置正确，服务器将启动并显示初始化成功的日志信息。

运行服务器

发展模式

在开发模式下运行MCP服务器：

mcp dev main.py

或者直接使用Python：

python main.py

服务器使用stdio传输与MCP客户端通信。

生产部署

对于生产部署，您可能需要：

  1. 使用流程管理器，如 systemd 或 supervisord
  2. 配置正确的日志记录
  3. 设置监测和健康检查
  4. 确保 .env 文件通过适当的文件权限（例如。， chmod 600 .env)

使用示例

示例1：搜索最近的严重犯罪

# Using the search_offenses tool
{
  "tool": "search_offenses",
  "arguments": {
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-31T23:59:59Z",
    "severity": 8,
    "status": "OPEN",
    "limit": 50
  }
}

示例2：获取犯罪细节

{
  "tool": "get_offense_details",
  "arguments": {
    "offense_id": 12345
  }
}

示例3：分析犯罪行为

{
  "tool": "analyze_offense",
  "arguments": {
    "offense_id": 12345
  }
}

响应包括:

  • 犯罪汇总和统计
  • 提取的安全指标（IP、域、用户名）
  • 重建攻击时间线
  • 已识别的攻击模式
  • 主要调查结果和建议

示例4：获取调查建议

{
  "tool": "recommend_investigation_actions",
  "arguments": {
    "offense_id": 12345
  }
}

或具有特定指标：

{
  "tool": "recommend_investigation_actions",
  "arguments": {
    "indicators": [
      "192.168.1.100",
      "malicious-domain.com",
      "suspicious_user"
    ]
  }
}

示例5：执行自定义AQL查询

{
  "tool": "execute_aql_query",
  "arguments": {
    "query": "SELECT sourceip, destinationip, COUNT(*) as event_count FROM events WHERE category=5001 GROUP BY sourceip, destinationip ORDER BY event_count DESC LAST 24 HOURS",
    "timeout": 120
  }
}

工具参考

搜索犯罪

使用各种过滤器搜索QRadar违规行为。

参数:

  • start_time （可选）：ISO 8601日期时间字符串
  • end_time （可选）：ISO 8601日期时间字符串
  • severity （可选）：整数1-10
  • status （可选）：“打开”、“关闭”或“隐藏”
  • offense_type （可选）：整数犯罪类型ID
  • limit （可选）：最大结果（默认值：50，最大值：1000）
  • offset （可选）：分页偏移量（默认值：0）

退货：犯罪对象列表

获取犯罪详情

获取有关特定犯罪的详细信息。

参数:

  • offense_id （必填）：整数犯罪ID

退货：带有完整细节的攻击对象

get_offense_logs

获取犯罪的所有日志条目。

参数:

  • offense_id （必填）：整数犯罪ID
  • limit （可选）：最大日志数（默认值：1000，最大值：10000）
  • offset （可选）：分页偏移量（默认值：0）

退货：日志条目对象列表

execute_aql_query

执行自定义AQL查询。

参数:

  • query （必填）：AQL查询字符串
  • timeout （可选）：超时秒数（默认值：60，最大值：300）

退货：查询结果为字典列表

分析犯罪

进行全面的根本原因分析。

参数:

  • offense_id （必填）：整数犯罪ID

退货：综合分析报告，包括：

  • 犯罪细节
  • 总结和统计
  • 提取指标
  • 攻击时间线
  • 已识别的模式

推荐_调查_行动

生成调查建议。

参数:

  • offense_id （可选）：整数犯罪ID
  • indicators （可选）：指示符字符串列表（IP、用户名、域）

退货：优先建议清单，包括：

  • 优先级
  • 操作类型
  • 标题和说明
  • 相关指标
  • 依据

建筑

代码库分为三个主要模块：

  1. main.py：MCP服务器入口点、工具注册和请求处理
  2. qradar_client.py：异步QRadar API客户端，具有全面的错误处理功能
  3. analysis_engine.py：用于根本原因分析和建议的智能分析逻辑

关键设计原则

  • 完全异步：所有I/O操作都使用 async/await 为了获得最佳性能
  • 类型安全：使用Pydantic模型的全面类型提示
  • 错误处理：针对网络问题、API限制和数据验证的强大错误处理
  • 模块化：明确区分数据访问和分析逻辑之间的关注点
  • 可扩展性：易于添加新的分析模式和推荐类型

错误处理

服务器处理各种错误情况：

  • 身份验证失败：清除无效用户名/密码的错误消息
  • 网络错误：超时处理和连接错误恢复
  • API费率限制：超出速率限制的正确错误报告
  • 无效数据：API响应的验证和清除
  • 缺失数据：巧妙地处理空结果

安全注意事项

  1. 凭证：永远不要硬编码QRadar凭据。始终使用 .env 配置文件。
  2. .env 文件安全性:
    • 这 .env 文件包含敏感凭据
    • 设置适当的文件权限： chmod 600 .env （Linux/Mac）
    • 永不承诺 .env 到版本控制（已在 .gitignore)
    • 使用 env.example 作为文档的模板
  3. SSL验证：默认情况下，会验证SSL证书。仅在开发中禁用。
  4. 密码安全性：密码应安全存储并定期轮换。
  5. 网络安全：确保服务器在安全的网络环境中运行。

故障排除

连接问题

如果遇到连接错误：

  1. 验证 QRADAR_HOST 正确且可访问
  2. 检查网络连接和防火墙规则
  3. 如果使用HTTPS，请验证SSL证书
  4. 测试用 curl 或 httpx 直接

身份验证错误

如果身份验证失败：

  1. 验证 QRADAR_USERNAME 和 QRADAR_PASSWORD 是正确的
  2. 检查帐户是否已锁定或过期
  3. 验证QRadar中的用户权限
  4. 使用curl或httpx通过直接API调用测试凭据

性能问题

对于大型数据集：

  1. 适当使用分页（限制/偏移）
  2. 设置合理的超时
  3. 考虑使用AQL查询进行复杂的过滤
  4. 监控QRadar API速率限制

贡献

这是一个生产就绪的实现。要扩展功能，请执行以下操作：

  1. 在中添加新的分析模式 analysis_engine.py
  2. 在中扩展QRadar API方法 qradar_client.py
  3. 在中注册新工具 main.py

许可证

本项目按原样提供，用于安全分析。

支持

关于以下问题：

  • QRadar API：请参阅IBM QRadar API文档
  • MCP协议：请参阅模型上下文协议规范
  • 此服务器：查看代码文档和错误消息

版本历史

  • v1.0.0：具有完整功能集的初始生产版本

相关 MCP