omichelbraga/esentire-atlas-mcp

# eSentire Atlas MCP Server 一个 MCP server，将 eSentire **Atlas API**（Findings、Ticketing、MVS）和 **Threat Intelligence** 数据源（IP Watch、Advanced/STIX）作为工具公开。 专为 HTTP 传输构建，因此它可以作为容器在反向代理后运行，并供远程 MCP 客户端调用。 ## 凭据 Atlas 颁发**四种不同的凭据类型**，且它们**不可互换** —— 提供错误的类型将返回 `402`/`403`： | Atlas 凭据类型 | 环境变量 | 涵盖范围 | |---|---|---| | `Atlas` | `ATLAS_API_TOKEN` | `/finding`, `/tickets`, `/mvs` — 读取**和**写入 | | `Atlas Readonly` | `ATLAS_API_TOKEN` | 相同路径，仅限读取 | | `Threat Intelligence` | `ESENTIRE_TI_TOKEN` | `/ti/ipwatch`, `/ti/indicators` | | `GenAI` | — | 未实现（未公开的端点） | 在 **Atlas → Settings → New API Credentials** 中创建它们。选择 **Authentication: Token** —— 静态 token 流程是 Atlas API 参考指南中所记录的流程。可选地，为您的 Docker 主机的出口地址添加 IP 限制。 ## 配置 | 变量 | 默认值 | 用途 | |---|---|---| | `ATLAS_API_TOKEN` | — | Atlas 凭据（Findings / Ticketing / MVS） | | `ESENTIRE_TI_TOKEN` | — | Threat Intelligence 凭据 | | `ESENTIRE_API_BASE` | `https://api.esentire.com` | API 根路径 | | `ESENTIRE_CUSTOMER_CODE` | — | 默认租户代码，以便调用方可以省略它 | | `ESENTIRE_ENABLED_SURFACES` | `findings,tickets,ti,mvs` | 逗号分隔列表；如果未授权请移除 `mvs` | | `ESENTIRE_READ_ONLY` | `false` | `1` 将直接拒绝所有修改性调用 | | `MCP_TRANSPORT` | `http` | `http` 或 `stdio` | | `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `3000` | 绑定地址 | | `MCP_PUBLIC_URL` | — | 外部 URL；OAuth 所必需 | | `MCP_AUTH` | `none` | `none` \| `bearer` \| `oauth`/`azure` \| `github` | | `MCP_BEARER_TOKEN` | — | 当 `MCP_AUTH=bearer` 时的共享密钥 | | `AZURE_TENANT_ID` / `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` | — | 用于 `MCP_AUTH=oauth` 的 Entra 应用 | | `TI_CACHE_TTL` | `3600` | 秒。与数据源的小时刷新率相匹配 | | `MAX_RESPONSE_CHARS` | `40000` | 单个工具响应上限 | | `LOG_LEVEL` | `info` | | `MCP_AUTH` 是**前门** —— MCP 客户端如何对此服务器进行身份验证。 它与 eSentire token 无关，后者用于此服务器向上游进行身份验证。 ## 工具 **Findings** — `findings_search`, `findings_search_advanced`, `finding_update` **Ticketing** — `tickets_case_type_configs`, `tickets_list_cases`, `tickets_get_case`, `tickets_create_case`, `tickets_update_case`, `tickets_list_comments`, `tickets_list_emails`, `tickets_list_attachments`, `tickets_get_attachment_link`, `tickets_upload_attachment`, `tickets_delete_attachment`, `tickets_list_contacts`, `tickets_list_locations` **Threat Intelligence** — `ti_ipwatch`, `ti_check_ip`, `ti_indicators`, `ti_indicators_paged`, `ti_indicators_misp` **MVS** — `mvs_list_assets`, `mvs_get_asset`, `mvs_asset_details`, `mvs_get_asset_vulnerability`, `mvs_list_vulnerabilities`, `mvs_get_vulnerability`, `mvs_list_missing_patches`, `mvs_assets_affected_by` ### 设计说明 - **Filter 是原生对象。** Atlas 需要为 `query`、`sorts` 和 `filters` 提供 URL 编码的 JSON。 请传入真实的列表/字典；编码会在内部处理。 - **`assignee_email` 意味着 `use_v2`。** 除非 V2 查询引擎处于活动状态，否则 Atlas 会默默忽略 assignee filter，因此 `findings_search` 会自动为您启用它，而不是悄悄返回错误的结果。 - **STIX 默认会被展平。** `ti_indicators` 会将 bundle 精简为简洁的 indicator/observable 列表。传入 `summarize=False` 可获取原始的 STIX 2.1。 - **当编码后的 filter payload 长到可能突破 query-string 限制时，MVS 会自动切换 GET → POST**。 - **MVS 需要单独授权。** 它的工具默认会被注册，但如果您的账户未开通该服务，它们会返回“token 类型错误/未授权”的消息。从 `ESENTIRE_ENABLED_SURFACES` 中移除 `mvs` 即可隐藏它们。 - **`page` 和 `per_page` 在 `/finding/findings` 中是必需的。** 这在 Atlas 指南中未记录，但如果缺少它们，Atlas 将返回 `400 Missing required query parameter`，因此 `findings_search` 总是会发送这两个参数（默认值为 1 / 50）。 - **Findings 和 MVS 使用不同的封装结构。** Findings 返回 `{count, items, total_count}`；MVS 返回 `{data, paging}`。 - **`401` 的响应体会被原样展示。** `" is not authorized"` 意味着 token 有效但未订阅该服务；而简单的 `"Unauthorized"` 则意味着 token 本身被拒绝了。这两者的解决方法截然不同。 - **尾部斜杠会被去除。** 如果 URL 以 `/` 结尾，Atlas 会返回 `404`。 - **Token 以原始形式发送**，在 `Authorization` 头中 —— 没有 `Bearer` 前缀。 - **`/health` 不会调用上游。** token 过期或 eSentire 服务中断绝不能导致 Docker 陷入重启循环，从而影响一个原本健康的容器。 ## 本地开发 ``` uv venv --python 3.12 uv pip install -e . MCP_TRANSPORT=stdio ATLAS_API_TOKEN=... uv run python -m esentire_mcp ``` ## 部署 作为 Portainer stack 部署，直接在 Docker 主机上构建此代码库 —— 参见 `docker-compose.yml`。不需要本地 Docker 或镜像仓库。 ## 安全 `tickets_create_case` 会向 **eSentire 的 SOC 提交真实的支持工单**。在调用它之前请先与人工确认。冒烟测试请使用 `case_type: "Atlas API Test"`。已关闭的工单永远无法重新打开；已解决的工单则可以 —— 优先选择“解决”。设置 `ESENTIRE_READ_ONLY=1` 可禁用所有修改操作。

标签：API集成, MCP服务, 可观测性, 威胁情报, 安全运营, 工单管理, 开发者工具, 扫描框架, 请求拦截, 逆向工具