rijul170/alertlogic-mcp

## 目录 - [概述](#overview) - [功能](#features) - [架构](#architecture) - [前置条件](#prerequisites) - [安装说明](#installation) - [配置](#configuration) - [Claude Code 集成](#claude-code-integration-http-mode) - [Claude Desktop 集成](#claude-desktop-integration-stdio-mode) - [模块概览](#module-overview) - [SOC 快速入门](#soc-quick-start) - [内置 SOC Playbook](#built-in-soc-playbooks) - [多账户 MSSP 用法](#multi-account-mssp-usage) - [安全注意事项](#security-notes) - [测试](#testing) - [故障排除](#troubleshooting) - [贡献指南](#contributing) - [许可证](#license) ## 概述 此 MCP 服务器封装了 AlertLogic MDR 平台的 API，并将其作为 473 多个结构化工具暴露出来，任何兼容 MCP 的 AI 客户端都可以直接调用。它涵盖了完整的 AlertLogic API 接口 —— 包括事件响应、基于 SQL 的日志搜索、SOAR playbook 自动化、资产管理、漏洞分析、用户和凭据管理、计费等 —— 并被组织成 46 个领域模块。身份验证、重试、分页、token 管理和 JSON 格式化都在服务器端处理；你的 AI 客户端只需按名称调用工具即可。 ## 功能 - **事件响应** — 列出、获取、详述（原始日志证据）、完成、重新打开、添加备注以及对事件添加反馈。支持友好的 ID 查找。 - **SQL 日志搜索** — 提交基于 SQL 的 AlertLogic 日志搜索查询、轮询状态、检索结果以及释放会话。 - **SOAR Playbook 自动化** — 列出、获取、执行和监控 SOAR playbook；管理查询、触发器和执行状态。 - **资产拓扑** — 查询完整的资产清单、声明和移除资产、设置属性，并检索任何部署的拓扑图。 - **漏洞管理** — 按严重程度列出暴露情况、检索每个资产的漏洞、搜索漏洞知识库以及管理修复项目。 - **用户与访问密钥管理** — 跨账户对用户、角色、访问密钥、MFA 设置和密码重置进行完整的 CRUD 操作。 - **多账户 MSSP 支持** — 支持按工具的 `account_id` 覆盖以及批量跨账户操作（批量部署、批量健康检查、合作伙伴事件）。 - **内置 SOC Playbook** — 六个工具可直接在上下文中展示预先编写好的 IR 指南、威胁狩猎工作流、MITRE ATT&CK 映射和工具参考指南。 - **工单与监控列表** — 创建、更新和关闭工单；管理告警监控列表。 - **Cloud 和 Azure Explorer** — 浏览跨 AWS 和 Azure 环境的云资源拓扑。 - **Analytics Engine** — 访问 AE 内容、规则、分析、标签、调优和发布，涵盖多个 AE 子系统。 - **基础设施运维** — 管理环境、扫描计划、扫描结果、网络控制、接入源和日志集成。 ## 架构 ``` +--------------------+ stdio / streamable-HTTP (MCP) +--------------------------------+ | MCP Client | <-------------------------------------> | AlertLogic MCP Server | | (Claude Desktop, | | (this repo, main.py) | | Claude Code, …) | | | +--------------------+ | 46 modules (~473 tools): | | incidents, soc, soar, | | assets, vuln, users, … | | | | | base.py (HTTP, AIMS auth, | | token cache, retries) | +----------+---------------------+ | v HTTPS + AIMS Bearer token +-----------------------------+ | AlertLogic MDR Platform | | api.cloudinsight....com | +-----------------------------+ ``` **Transport**：服务器支持通过 `MCP_TRANSPORT` 选择的三种 MCP 传输方式： - `stdio`（默认）— 由你的 MCP 客户端按需启动；不开放网络端口。 - `streamable-http` — 持久化的 HTTP 服务器；适用于 Claude Code 和远程客户端。 - `sse` — 为支持 SSE 的客户端提供 Server-Sent Events 传输。 **身份验证**：AlertLogic 使用 AIMS Bearer token 进行身份验证。服务器在首次使用时将你的 `access_key_id:secret_key` API 密钥交换为短期的 Bearer token，对其进行缓存，并在 token 过期时自动重新验证 —— 无需手动轮换 token。 **`base.py`** 集中了 HTTP 方法助手（`_get`、`_post`、`_put`、`_delete`）、按服务的 URL 路由（Account-Topology 服务、global 服务、以 `_at` 为前缀的路由）、错误转换以及 AIMS token 缓存。 ## 前置条件 - Python 3.10 或更高版本 - `uv`（推荐）或 `pip` - 启用了 API 访问权限的 AlertLogic 账户 - AlertLogic API 密钥（访问密钥 ID + 秘密密钥；详见[配置](#configuration)） ## 安装说明 ``` # 1. Clone the repository git clone https://github.com//.git cd # 2. Create a virtual environment 并安装依赖 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt # 或者使用 uv（更快）： uv venv uv pip install -r requirements.txt # 3. Configure credentials cp .env.example .env $EDITOR .env # fill in the required variables (see below) ``` ## 配置 所有配置均通过环境变量进行，并在启动时从 `.env` 加载。 ### 必选变量 | 变量 | 描述 | | -------------------------- | ------------------------------------------------------------------------------------------------ | | `ALERTLOGIC_API_KEY` | `access_key_id:secret_key` 格式的 API 密钥（创建方法见下文） | | `ALERTLOGIC_BASE_URL` | API 基础 URL — `https://api.cloudinsight.alertlogic.com` (美国) 或 `https://api.cloudinsight.alertlogic.co.uk` (英国) | | `ALERTLOGIC_ACCOUNT_ID` | 你的 AlertLogic 账户 ID（在控制台 URL 和账户设置中可见） | ### 可选变量 | 变量 | 默认值 | 描述 | | -------------------------- | -------------- | -------------------------------------------------------- | | `MCP_TRANSPORT` | `stdio` | 传输方式：`stdio`、`sse` 或 `streamable-http` | | `MCP_HOST` | `127.0.0.1` | 绑定主机（仅限 HTTP 传输方式） | | `MCP_PORT` | `8000` | 绑定端口（仅限 HTTP 传输方式） | ### 可选服务 URL 覆盖 这些默认指向 AlertLogic 的标准 endpoint。仅在你拥有自定义部署时才进行覆盖： ``` ALERTLOGIC_GLOBAL_BASE_URL=https://api.global-services.global.alertlogic.com ALERTLOGIC_AETUNER_BASE_URL=https://aetuner.mdr.global.alertlogic.com ALERTLOGIC_CONNECTORS_BASE_URL=https://connectors.mdr.global.alertlogic.com ALERTLOGIC_RESPONDER_BASE_URL=https://api.responder.alertlogic.com ``` ### 创建 API 密钥 1. 登录 AlertLogic 控制台。 2. 导航至 **Manage → Users**，选择你的用户，然后打开 **Access Keys → Create**。 3. 复制 **Access Key ID** 和 **Secret Key**。 4. 将它们组合为 `access_key_id:secret_key`（包含冒号），并将其设置为 `ALERTLOGIC_API_KEY`。 ## Claude Code 集成 (HTTP 模式) 以 HTTP 模式启动服务器： ``` MCP_TRANSPORT=streamable-http python main.py ``` 然后将其注册到你的 Claude Code 项目或用户 MCP 配置（`.claude/settings.json` 或 `~/.claude/settings.json`）中： ``` { "mcpServers": { "alertlogic-mcp": { "type": "http", "url": "http://localhost:8000/mcp" } } } ``` 或者通过 CLI 注册： ``` claude mcp add --transport http alertlogic-mcp http://localhost:8000/mcp ``` ## Claude Desktop 集成 (stdio 模式) 编辑 `claude_desktop_config.json`： - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%AppData%\Claude\claude_desktop_config.json` ``` { "mcpServers": { "alertlogic-mcp": { "command": "/absolute/path/to/.venv/bin/python", "args": ["/absolute/path/to/alertlogic-mcp/main.py"] } } } ``` 重启 Claude Desktop。AlertLogic 工具将出现在工具选择器中。 ## 模块概览 包含 46 个模块，约 473 个工具，按领域组织： ### 事件响应 | 模块 | 工具数 | 关键操作 | | ---------------- | :----: | ---------------------------------------------------------------------------------------- | | `incidents_mcp` | 11 | 列出、获取、友好 ID 查找、完成、重新打开、添加备注、添加反馈、列出合作伙伴事件 | | `soc` | 14 | 提交/轮询/释放 SQL 日志搜索、列出暴露情况、获取健康摘要 | | `soc_playbooks` | 6 | 内置 IR 指南、威胁狩猎工作流、MITRE 映射、工具指南（见下文） | ### 资产管理 | 模块 | 工具数 | 关键操作 | | ---------------- | :----: | ---------------------------------------------------------------------------------------- | | `assets` | 15 | 查询资产、获取拓扑、声明/批量声明/移除资产、设置属性 | | `assets_manager` | 5 | 高级资产管理和分组 | | `cloud_explorer` | 12 | 按部署浏览 AWS 云资源拓扑 | | `azure_explorer` | 13 | 按部署浏览 Azure 资源拓扑 | ### SOAR | 模块 | 工具数 | 关键操作 | | ------ | :----: | -------------------------------------------------------------------------------------------------- | | `soar` | 33 | 列出/获取 playbook 和 action、创建/获取/查询执行、管理查询和触发器 | ### 漏洞与合规 | 模块 | 工具数 | 关键操作 | | -------------------- | :----: | ------------------------------------------------------------------------- | | `vulnerability` | 10 | 按严重程度列出暴露情况、获取每个资产的暴露情况 | | `vulnerabilities_kb` | 9 | 查询漏洞知识库（CVE 详情、CVSS、修复方案） | | `compliance` | 4 | 列出修复项目、结束/处置/取消处置修复 | ### 用户与身份验证 | 模块 | 工具数 | 关键操作 | | ------------- | :----: | --------------------------------------------------------------------------------------- | | `users` | 30 | 对用户、角色、访问密钥、MFA 和密码重置进行完整的 CRUD 操作 | | `auth` | 6 | AIMS token 管理、列出受管账户、账户 ID 枚举 | | `credentials` | 10 | IAM 角色和 Azure AD 凭据 CRUD、扫描凭据、解密检索 | | `themis` | 3 | 凭据验证和确认 | ### 基础设施与部署 | 模块 | 工具数 | 关键操作 | | ------------------ | :----: | --------------------------------------------------------------------------- | | `deployments` | 5 | 列出、获取、创建、更新、删除部署 | | `environments` | 10 | 管理 AlertLogic 环境和环境配置 | | `network_controls` | 15 | 排除项 CRUD、资产检查、标签/主机白名单管理 | | `scan_scheduler` | 13 | 为每个部署创建、更新和管理扫描计划 | | `scan_result` | 4 | 检索和分析扫描结果 | ### Analytics Engine | 模块 | 工具数 | 关键操作 | | ------------ | :----: | --------------------------------------------------------------------------- | | `aecontent` | 11 | 管理 AE 内容（检测内容库） | | `aefr` | 23 | AE flat-rule 管理 | | `aerta` | 13 | AE 实时分析管理 | | `aetag` | 23 | AE 标签和关联规则管理 | | `aepublish` | 1 | 发布 AE 分析更新 | | `aemanual` | 2 | 手动 AE 分析操作 | | `kalm` | 5 | AE 知识和分析生命周期管理 | ### 工单与监控列表 | 模块 | 工具数 | 关键操作 | | ------------------ | :----: | -------------------------------------------------------- | | `tickets` | 8 | 创建、获取、更新、列出和关闭工单 | | `watchlist_module` | 7 | 管理告警监控列表（添加、移除、查询项目） | ### 运维与平台 | 模块 | 工具数 | 关键操作 | | --------------------- | :----: | ----------------------------------------------------------------------- | | `account_management` | 7 | 账户详情、按名称查找、父/子关系、拓扑 | | `policies` | 2 | 列出和检查策略 | `billing` | 12 | 列出和检查订阅、权利和计费数据 | | `common` | 22 | Herald 通知、订阅、webhook/email 连接器、endpoint | | `ingest_module` | 6 | 管理日志接入源和接入配置 | | `logging_integration` | 17 | 日志源 CRUD、源类型、收集管理 | | `otis` | 7 | 按需威胁情报搜索 | | `notify` | 2 | 通知派发 | | `search_stylist` | 2 | 日志搜索查询格式化和建议 | | `informant` | 2 | Informant 服务查询 | | `strawboss` | 10 | Strawboss 作业和计划管理 | | `tacoma` | 12 | Tacoma 服务操作 | | `album` | 10 | 证据和 artifact 管理 | | `usage_module` | 4 | 账户使用情况统计和报告 | | `bulk_ops` | 2 | 跨账户批量操作（批量部署、批量健康检查） | | `suggestions` | 10 | AI 辅助的搜索和调查建议 | | `seceng` | — | 安全工程：Cargo 计划/执行，AETuner 分析/调优 | ## SOC 快速入门 连接成功后，尝试在 Claude 中使用这些提示词： ``` Show me all open critical incidents from the last 24 hours ``` ``` Get the elaborations (raw log evidence) for incident INC-12345 ``` ``` Search logs for SSH login failures from 10.0.0.5 in the last hour using SQL ``` ``` Add a note to incident INC-12345: Confirmed malicious, escalating to customer ``` ``` List all deployments and their health status across all accounts ``` ``` Show me the top 10 critical vulnerabilities for host web-prod-01 ``` ``` Run the SOC IR playbook to walk me through incident response steps ``` ## 内置 SOC Playbook `soc_playbooks` 模块提供了六个工具，可直接在上下文中展示经过精心策划的操作指南 —— 无需查找外部文档： | 工具 | 内容 | | --------------------------- | ------------------------------------------------------------------------------------------ | | `soc_ir_start` | 端到端的事件响应工作流：分类检查清单、范围界定步骤、遏制标准、证据收集和文档要求 | | `soc_threat_hunt` | 假设驱动的威胁狩猎 playbook：基于 IOC 的狩猎、基于 TTP 的狩猎，以及针对常见攻击模式的日志查询模板 | | `soc_mitre_attack_guide` | MITRE ATT&CK 战术/技术参考，映射到 AlertLogic 检测类型和推荐的搜索查询 | | `soc_alertlogic_tool_guide` | AlertLogic MCP 工具的快速参考，按调查任务（分类、范围界定、证据、遏制）进行组织 | | `soc_log_query_templates` | 可直接运行的 SQL 日志查询模板，适用于常见的 SOC 场景：身份验证失败、横向移动、C2 信标、数据外泄等 | | `soc_summary` | 可直接面向管理层的 incident 摘要模板及字段填充指南 | 这些工具被设计为在调查开始时调用，以便在查询实时数据之前加载相关上下文。 ## 多账户 MSSP 用法 该服务器专为 MSSP 环境设计，在这种环境中，单个 API 密钥可管理多个子账户： **合作伙伴事件列表** — `incidents_list_partner` 可以通过单次调用返回所有受管账户的 incident，并附带账户所有权标签。 **按工具的账户覆盖** — 大多数工具接受一个可选的 `account_id` 参数。传入子账户的 ID 即可将任何查询范围限定在该账户内，而无需更改你的 `.env` 配置： ``` Get all open incidents for account ``` **批量操作** — `bulk_list_deployments` 会将部署查询展开到所有受管账户中，并返回汇总结果。`bulk_health_check` 对健康状态执行相同的操作。 **账户拓扑** — `aims_get_account_topology` 和 `aims_list_accounts_by_relationship` 可映射父/子账户层级结构，这对于在运行操作之前界定范围非常有用。 ## 安全注意事项 - **切勿提交 `.env` 文件。** 它已被 `.gitignore` 排除；仓库仅追踪 `.env.example`（包含占位符）。 - 像对待密码一样对待 `ALERTLOGIC_API_KEY`。如果你怀疑其被泄露（聊天日志、屏幕共享、设备丢失），请立即轮换。 - **AIMS token 处理**：服务器在首次使用时会将你的 API 密钥交换为短期的 Bearer token 并缓存在内存中。token 过期时会自动刷新。在初始的 AIMS 身份验证调用之后，原始的 `secret_key` 不会被记录或传输。 - 在 `stdio` 模式下，服务器不会开放任何网络端口。在 `streamable-http` 或 `sse` 模式下，除非你明确需要远程访问，否则请绑定到 `127.0.0.1`（默认设置），在这种情况下，请添加适当的网络控制措施。 - `base.py` 不会记录请求体、响应体或凭据材料。如果你 fork 代码并添加了日志记录功能，请务必注意排除 token 和 secret 值。 - 本仓库不附带任何类型的凭据。 ## 测试 一个独立的冒烟测试脚本可以在不通过 MCP 客户端的情况下，测试具有代表性的工具横截面： ``` python smoke_test.py ``` 这将在将服务器连接到你的 MCP 客户端之前，验证凭据有效性、网络可达性和基础配置。 ## 故障排除

“身份验证失败” / 401 错误

- 确认 `ALERTLOGIC_API_KEY` 是完整的 `access_key_id:secret_key` 字符串，包含冒号分隔符。 - 验证 `ALERTLOGIC_BASE_URL` 是否与你的数据中心匹配（美国为 `api.cloudinsight.alertlogic.com`，英国为 `api.cloudinsight.alertlogic.co.uk`）。 - 检查 AlertLogic 控制台中该访问密钥是否仍然处于活动状态 (Manage → Users → Access Keys)。 - 确认 `ALERTLOGIC_ACCOUNT_ID` 是否正确 —— 如果不匹配，可能会导致在账户范围内的 endpoint 上发生 401 错误。

工具未在 Claude Desktop 中显示

- 在 `claude_desktop_config.json` 中使用绝对路径。波浪号 (`~`) 和相对路径不会被展开。 - 将 `command` 指向虚拟环境的 Python (`.venv/bin/python`)，而不是系统 Python。 - 检查 Claude Desktop 日志中是否有来自此服务器的 stderr 输出：macOS 日志位于 `~/Library/Logs/Claude/`。 - 编辑配置文件后，请完全重启 Claude Desktop（退出并重新打开）。

"ModuleNotFoundError: mcp" 或缺少依赖项

你正在虚拟环境之外运行 `python main.py`。请先激活它 (`source .venv/bin/activate`)，或者直接调用虚拟环境的 Python (`/path/to/.venv/bin/python main.py`)。

HTTP 模式：端口 8000 上的连接被拒绝

确保在尝试连接之前使用 `MCP_TRANSPORT=streamable-http python main.py` 启动了服务器。只有在选择了非 stdio 传输方式时，服务器才会绑定端口。

结果为空或静默失败

如果所有工具调用都返回空结果或静默失败，这通常是由 SSO 或代理层阻止了出站 API 调用引起的。尝试从非代理网络或使用其他客户端运行以进行确认。同时检查 `ALERTLOGIC_BASE_URL` 和 `ALERTLOGIC_ACCOUNT_ID` 是否均适用于你的环境。

## 贡献指南 欢迎提交 PR 和 issue。 1. Fork 本仓库，创建功能分支，提交你的更改，并发起 PR。 2. 在 `modules/ 目录下匹配的模块文件中，将新的 AlertLogic endpoint 作为额外的 `@server.tool` 定义添加进去。 3. 对于新模块：创建包含 `setup(server)` 函数的 `modules/.py` 文件，然后将其添加到 `main.py` 的 `MODULES` 列表中。 4. 保持工具 docstring 的准确性和描述性 —— docstring 是 LLM 在决定是否以及如何调用该工具时所看到的内容。 5. 提交前运行 `python smoke_test.py` 以验证基本功能。 ## 相关 MCP 服务器 这三个服务器涵盖了安全栈的互补层 —— 网络/日志 (AlertLogic)、端点保护 (Sophos) 以及 EDR/威胁情报 (CrowdStrike)。将它们一起使用以实现全栈的 AI 驱动的 SOC 操作。 | 服务器 | 平台 | 亮点 | |--------|----------|------------| | [falcon-mcp](https://github.com/rijul170/falcon-mcp) | CrowdStrike Falcon | EDR 遥测、RTR、威胁情报、MSSP Flight Control，1,296 个工具 | | [sophos-central-mcp](https://github.com/rijul170/sophos-central-mcp) | Sophos Central | 端点隔离、Live Discover SQL、XDR、email/firewall/DNS，334 个工具 | | [alertlogic-mcp](https://github.com/rijul170/alertlogic-mcp) | Alert Logic MDR | 事件响应、SQL 日志搜索、SOAR、漏洞管理，473 个工具 | ## 许可证 MIT 许可证。完整文本请参见 [LICENSE](LICENSE)。

标签：MCP协议, MDR, Python, SOAR自动化, 安全运营, 库, 应急响应, 扫描框架, 无后门, 逆向工具