alertlogic-mcp

**面向事件响应人员：**通过 Claude 查询 Alert Logic MDR 事件、深入分析原始日志证据、启动 SOAR 工作流并使用 SQL 搜索日志。专为 MSSP 规模的多账户运营打造。

---

目录

• 概述
• 功能
• 架构
• 前提条件
• 安装
• 配置
• Claude Code 集成
• Claude Desktop 集成
• 模块概览
• SOC 快速入门
• 内置 SOC 工作流
• MSSP 多账户使用
• 安全说明
• 测试
• 故障排查
• 参与贡献
• 许可证

---

概述

此 MCP 服务封装了 Alert Logic MDR 平台 API，并将其作为 473 多个结构化工具提供，任何兼容 MCP 的 AI 客户端都可以直接调用。它涵盖完整的 Alert Logic API 功能，包括事件响应、基于 SQL 的日志搜索、SOAR 工作流自动化、资产管理、漏洞分析、用户和凭证管理、账单等，并划分为 46 个领域模块。身份验证、重试、分页、令牌管理和 JSON 整理由服务端处理；您的 AI 客户端只需按名称调用工具即可。

---

功能

• 事件响应 — 列出、获取、详述（原始日志证据）、完成和重新打开事件，为事件添加备注和反馈。支持按友好 ID 查找。
• SQL 日志搜索 — 以 SQL 提交 Alert Logic 日志搜索查询、轮询状态、获取结果并释放会话。
• SOAR 剧本自动化 — 列出、获取、执行和监控 SOAR 剧本；管理调查、触发器和执行状态。
• 资产拓扑 — 查询完整资产清单、声明和移除资产、设置属性，以及获取任意部署的拓扑图。
• 漏洞管理 — 按严重程度列出暴露项、获取各资产的漏洞、搜索漏洞知识库，以及管理修复项。
• 用户和访问密钥管理 — 跨账户对用户、角色、访问密钥、MFA 设置和密码重置执行完整的增删改查操作。
• 多账户 MSSP 支持 — 支持为每个工具覆盖 account_id，并执行跨账户批量操作（批量部署、批量运行状况检查、合作伙伴事件）。
• 内置 SOC 剧本 — 提供六种工具，可在当前上下文中直接展示预先编写的 IR 指南、威胁搜寻工作流、MITRE ATT&CK 映射和工具参考指南。
• 工单和观察列表 — 创建、更新和关闭工单；管理告警观察列表。
• 云和 Azure 浏览器 — 浏览 AWS 和 Azure 环境中的云资源拓扑。
• 分析引擎 — 跨多个 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   |
                                                              +-----------------------------+

传输：服务支持三种 MCP 传输方式，可通过 MCP_TRANSPORT 选择：

• stdio（默认）— 由 MCP 客户端按需启动；不会开放网络端口。
• streamable-http — 持久 HTTP 服务；适用于 Claude Code 和远程客户端。
• sse — 面向支持 SSE 的客户端的服务器发送事件传输方式。

身份验证：Alert Logic 使用 AIMS Bearer 令牌身份验证。服务首次使用时，会将你的 access_key_id:secret_key API 密钥交换为短期 Bearer 令牌并缓存该令牌；令牌过期后会自动重新进行身份验证，无需手动轮换令牌。

base.py 集中处理 HTTP 方法辅助函数（_get、_post、_put、_delete）、按服务划分的 URL 路由（Account-Topology 服务、全局服务、带 _at 前缀的路由）、错误转换和 AIMS 令牌缓存。

---

前提条件

• Python 3.10 或更高版本
• uv（推荐）或 pip
• 已启用 API 访问权限的 Alert Logic 账户
• Alert Logic API 密钥（访问密钥 ID + 密钥；创建方法请参阅配置）

---

安装

# 1. Clone the repository
git clone https://github.com/rijul170/alertlogic-mcp.git
cd alertlogic-mcp

# 2. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Or with uv (faster):
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	你的 Alert Logic 账户 ID（可在控制台 URL 和账户设置中查看）

可选变量

变量	默认值	描述
MCP_TRANSPORT	stdio	传输方式：stdio、sse 或 streamable-http
MCP_HOST	127.0.0.1	绑定主机（仅限 HTTP 传输方式）
MCP_PORT	8000	绑定端口（仅限 HTTP 传输方式）
ALERTLOGIC_MCP_READONLY	(关闭)	设置为 true 时，仅注册读取工具 — 写入和破坏性工具绝不会暴露给 AI 客户端
ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE	(关闭)	默认禁用破坏性工具（删除、执行 SOAR playbook、启动扫描等）。设置为 true 可启用所有此类工具，或使用逗号分隔的工具名称列表选择性启用

可选服务 URL 覆盖项

默认使用 Alert Logic 的标准端点。仅在使用自定义部署时覆盖：

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. 登录 Alert Logic 控制台。
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 不会展开波浪号（~）。将 command 指向虚拟环境中的 Python，而不是系统 Python。

重启 Claude Desktop。Alert Logic 工具将显示在工具选择器中。

---

模块概览

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 和操作，创建／获取／查询执行记录，管理调查和触发器

漏洞与合规

模块	工具数	关键操作
vulnerability	10	按严重程度列出暴露项，获取每项资产的暴露情况
vulnerabilities_kb	9	查询漏洞知识库（CVE 详情、CVSS、修复措施）
compliance	4	列出修复项，确认、处置或撤销处置修复项

用户与身份验证

模块	工具数	关键操作
users	30	对用户、角色、访问密钥、MFA 和密码重置执行完整的 CRUD 操作
auth	6	管理 AIMS 令牌、列出受管理的账户、枚举账户 ID
credentials	10	对 IAM 角色和 Azure AD 凭据执行 CRUD 操作，扫描凭据并检索解密后的凭据
themis	3	凭据验证与核验

基础设施与部署

模块	工具数	关键操作
deployments	5	列出、获取、创建、更新和删除部署
environments	10	管理 Alert Logic 环境及环境配置
network_controls	15	排除项 CRUD、资产检查、标签和主机白名单管理
scan_scheduler	13	创建、更新和管理每个部署的扫描计划
scan_result	4	检索和分析扫描结果

分析引擎

模块	工具数	关键操作
aecontent	11	管理 AE 内容（检测内容库）
aefr	23	管理 AE 平面规则
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/电子邮件连接器、端点
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	证据和工件管理
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 操作手册

soc_playbooks 模块提供六种工具，用于呈现经过整理、可在上下文中使用的运维指南——无需查阅外部文档：

工具	内容
soc_ir_start	端到端事件响应工作流：分诊清单、范围界定步骤、遏制标准、证据收集和文档要求
soc_threat_hunt	基于假设的威胁狩猎操作手册：基于 IOC 和 TTP 的狩猎，以及适用于常见攻击模式的日志查询模板
soc_mitre_attack_guide	MITRE ATT&CK 战术/技术参考，与 Alert Logic 检测类型及推荐搜索查询相对应
soc_alertlogic_tool_guide	Alert Logic MCP 工具快速参考，按调查任务（分诊、范围界定、证据、遏制）分类
soc_log_query_templates	可直接运行的 SQL 日志查询模板，适用于常见 SOC 场景：身份验证失败、横向移动、C2 信标通信、数据窃取等
soc_summary	面向高管的事件摘要模板及字段填写指南

这些工具适合在调查开始时调用，以便在查询实时数据前加载相关上下文。

---

多账户 MSSP 用法

此服务专为 MSSP 环境设计，其中单个 API 密钥可管理多个子账户：

合作伙伴事件列表 — incidents_list_partner 可通过一次调用返回所有受管账户的事件，并标注账户归属。

按工具覆盖账户 — 大多数工具都接受可选的 account_id 参数。传入子账户的 ID，即可将任何查询限定到该账户，无需更改 .env 配置：

Get all open incidents for account <child-account-id>

批量操作 — bulk_list_deployments 会向所有受管账户分别发起部署查询，并返回汇总结果。bulk_health_check 会以相同方式查询运行状况。

账户拓扑 — aims_get_account_topology 和 aims_list_accounts_by_relationship 可映射父账户与子账户的层级关系，有助于在执行操作前确定范围。

租户隔离：跨多个账户操作时，执行写入操作（隔离、添加备注、创建工单）前，务必确认目标账户。除了 Alert Logic API 提供的保护机制外，此服务不会强制执行跨租户保护。

---

安全说明

• 只读模式：设置 ALERTLOGIC_MCP_READONLY=true，即可在启动时仅注册只读工具。无论 AI 客户端提出什么请求，都不会向其公开写入和破坏性工具。

• 破坏性操作控制：即使已启用写入，破坏性工具（删除用户／资产、执行 SOAR playbook、启动扫描、撤销密钥等）默认也会被禁用。通过 ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE 显式启用；建议使用逗号分隔的特定工具名称列表，而不是设置为 true：

  # Enable only incident completion workflow deletes
  ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE=user_delete,playbook_execute
  

• 每个工具都带有 MCP readOnlyHint／destructiveHint 注解，以便遵循规范的客户端应用自身的确认策略。

• 切勿提交 .env。 该文件已列入 .gitignore 排除范围；只有 .env.example（包含占位符）会被纳入版本控制。

• 请将 ALERTLOGIC_API_KEY 视同密码。如果怀疑密钥已泄露（聊天记录、屏幕共享、设备丢失），请立即轮换。

• AIMS 令牌处理：服务首次使用时会将 API 密钥交换为短期有效的 Bearer 令牌，并将其缓存在内存中。令牌过期后会自动刷新。首次 AIMS 身份验证调用后，不会记录或传输原始 secret_key。

• 在 stdio 模式下，服务不会开放网络端口。在 streamable-http 或 sse 模式下，除非确实需要远程访问（此时应添加适当的网络控制），否则请绑定到 127.0.0.1（默认值）。

• base.py 不会记录请求正文、响应正文或凭据材料。如果你派生了此项目并添加日志记录，请注意排除令牌和密钥值。

• 此代码库不包含任何凭据。

---

测试

独立的冒烟测试脚本会抽样测试多种工具，无需通过 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）。
• 检查访问密钥在 Alert Logic 控制台中是否仍处于有效状态（Manage → Users → Access Keys）。
• 确认 ALERTLOGIC_ACCOUNT_ID 正确；不匹配可能导致账户范围的端点返回 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 和问题反馈。

1. Fork 此代码库，创建功能分支，提交更改，然后发起 PR。
2. 在 modules/ 下对应的模块文件中，添加新的 @server.tool 定义，以加入新的 Alert Logic 端点。
3. 若要新增模块：创建包含 setup(server) 函数的 modules/<name>.py，然后将其添加到 main.py 中的 MODULES 列表。
4. 确保工具文档字符串准确且描述清晰——大模型 会依据文档字符串来判断是否以及如何调用工具。
5. 提交前运行 python smoke_test.py，以验证基本功能。

---

相关 MCP 服务

以下三个服务覆盖安全技术栈中互为补充的层面——网络／日志（Alert Logic）、端点防护（Sophos）以及 EDR／威胁情报（CrowdStrike）。搭配使用它们，可实现全栈 AI 赋能的 SOC 运营。

服务	平台	亮点
falcon-mcp	CrowdStrike Falcon	EDR 遥测、RTR、威胁情报、MSSP Flight Control、1,296 个工具
sophos-central-mcp	Sophos Central	端点隔离、Live Discover SQL、XDR、电子邮件／防火墙／DNS、334 个工具
alertlogic-mcp	Alert Logic MDR	事件响应、SQL 日志搜索、SOAR、漏洞管理、473 个工具

许可证

MIT 许可证。完整文本请参阅 LICENSE。