Cisco Umbrella

Cisco Umbrella MCP 服务

适用于 Cisco Umbrella NextGen REST API 的 MCP 服务，可提供部署清单、管理员、策略、报告和调查可见性，供 AI 助手和 WYRE Conduit 网关使用。

身份验证

在 Umbrella 管理控制台中创建 API Key（Admin > API Keys；在 Multi-org/MSP 控制台中则为 Console Settings > API Keys），以获取一对 API Key 和 API Secret。

该密钥仅在创建时显示一次，之后无法找回，请立即妥善保存。

此服务会通过 POST /auth/v2/token（grant_type=client_credentials，HTTP Basic 身份验证）将这对密钥换成有效期为 1 小时的 Bearer 访问令牌，并在内部处理兑换及令牌过期后的刷新。调用方只需提供下方的长期有效 API Key/Secret。

**关于 Cisco 自家文档中一处真实差异的说明：**Cisco 发布的 Postman 集合（CiscoDevNet/cloud-security，Umbrella/PostmanExamples/umbrella-external-postman-collection.json）将令牌请求编码为不带请求体的裸 GET，而 Cisco DevNet 的“Getting Started”和“Quickstart”文档均分别说明应使用 POST，并在表单请求体中包含 grant_type=client_credentials。此服务遵循说明文档（POST），因为两份独立文档内容一致，且符合 Cisco 明确命名的标准 OAuth2 client_credentials 流程；但尚未使用真实凭据对其进行验证。如果使用真实账户兑换令牌时返回 401，请先尝试不带请求体的裸 GET，再判断凭据是否有误。

配置

复制 .env.example，并设置下表中的变量。stdio 传输会读取 CISCOUMBRELLA_*，不会使用 CONDUIT_S2S_SECRET。

环境变量	说明
CISCOUMBRELLA_API_KEY	Umbrella 管理控制台中的 API Key。stdio 和 AUTH_MODE=env 必需。网关模式下不会读取。
CISCOUMBRELLA_API_SECRET	与 API Key 配对的 API Secret。创建时仅显示一次。stdio 和 AUTH_MODE=env 必需。网关模式下不会读取。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上述变量）或 gateway（Docker 镜像和 Compose 的默认值）。网关模式要求每个 /mcp 请求都包含 X-CiscoUmbrella-Api-Key 和 X-CiscoUmbrella-Api-Secret，且不会回退到 CISCOUMBRELLA_*。
CONDUIT_S2S_SECRET	HTTP 模式必需。用于校验 /mcp 上 X-Gateway-S2S 的 HMAC 密钥。使用 openssl rand -hex 32 生成。如果为空或为已知占位值，HTTP 服务会记录错误并以非零状态退出。此值绝不会被记录到日志中。
MCP_ALLOW_INSECURE_DEV	仅设置为 1 时，才会在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。服务会记录警告、不校验 X-Gateway-S2S，并且仅绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是环回地址，则拒绝启动。仍会拒绝已知的占位密钥。仅用于本地开发。
MCP_HTTP_HOST	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。配置 CONDUIT_S2S_SECRET 后会遵循此值。容器镜像会设置为 0.0.0.0。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

/health 和 /healthz 无需身份验证，也不会读取凭据。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。验证逻辑位于 src/s2s-verify.ts 中的 verifyS2sHeader：标头值的格式为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算出的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少标头或标头无效时，返回 HTTP 401，且不会读取供应商凭据。除非设置了 MCP_ALLOW_INSECURE_DEV=1，否则空密钥会导致服务拒绝启动。即使设置了该标志，已知占位符（replace-with-a-real-secret、your-s2s-secret、changeme、change-me、placeholder、secret、example、replace-me、s2s-secret，不区分大小写）仍会导致服务拒绝启动，避免复制的示例被用于伪造标头。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-CiscoUmbrella-Api-Key: $CISCOUMBRELLA_API_KEY" \
  -H "X-CiscoUmbrella-Api-Secret: $CISCOUMBRELLA_API_SECRET" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求同时提供 X-CiscoUmbrella-Api-Key 和 X-CiscoUmbrella-Api-Secret。这些标头是该请求唯一的凭据来源。缺少其中任一标头的请求都会返回 401，且不会回退到进程环境中的 CISCOUMBRELLA_*。

AUTH_MODE=env 模式仍要求有效的 X-Gateway-S2S 标头，然后使用环境中的 CISCOUMBRELLA_API_KEY 和 CISCOUMBRELLA_API_SECRET。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。通过 X-Gateway-S2S 检查后，如果 Content-Length 超出上限，则返回包含 JSON-RPC 错误的 413；没有 Content-Length 的正文由 MCP SDK 传输层限制。未经身份验证的请求仍会优先收到 401。
• tools/call 参数上限为 10,000 个元素（任意深度的每个数组项和对象键）。超出上限的输入会返回 isError 工具结果，且不会被分发。

这些限制用于应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间内存耗尽）和 GHSA-f897-62hf-6gxq（请求正文 / 批次无上限）。

工具

部署

• umbrella_list_networks - 列出已注册的公网 IP 网络标识。
• umbrella_list_internal_networks - 列出内部（RFC1918）网络标识。
• umbrella_list_sites - 列出 Umbrella 站点。
• umbrella_list_virtual_appliances - 列出虚拟设备及其状态。
• umbrella_list_roaming_computers - 列出已注册漫游客户端的计算机。
• umbrella_get_internal_domains - 获取配置为绕过 Umbrella DNS 的所有内部域名。

管理

• umbrella_list_roles - 列出管理角色。
• umbrella_list_users - 列出管理控制台用户。
• umbrella_get_user - 获取指定的管理控制台用户。
• umbrella_list_api_keys - 列出已配置的 API 密钥。

策略

• umbrella_list_destination_lists - 列出目标（允许 / 阻止）列表。
• umbrella_list_destinations - 列出指定目标列表中的目标。

报告

• umbrella_top_destinations - 列出请求最多的目标，可按流量类型（dns/proxy/firewall）筛选。
• umbrella_total_requests - 获取请求总数，可按流量类型筛选。
• umbrella_top_categories - 列出请求最多的内容 / 安全类别。
• umbrella_activity - 获取原始活动日志，可按流量类型筛选。
• umbrella_identities - 列出身份（漫游 / 网络 / 移动 / AD 用户）及其流量摘要。
• umbrella_appdiscovery_applications - 列出发现的云应用。
• umbrella_appdiscovery_app_identities - 列出观察到正在使用某个已发现应用的身份。
• umbrella_appdiscovery_app_risk - 获取已发现应用的风险详情。
• umbrella_api_usage_summary / umbrella_api_usage_requests / umbrella_api_usage_responses / umbrella_api_usage_keys - API 使用情况报告。

调查

• umbrella_domain_categorization - 域名的内容/安全分类。
• umbrella_domain_risk_score - Cisco 对域名的风险评分。
• umbrella_domain_security_score - 域名的详细安全评分信号。
• umbrella_top_most_seen_domains - 全球最热门的前 100 万个域名。
• umbrella_get_samples - 域名、IP 或 URL 的恶意软件/文件样本。
• umbrella_domain_volume - 域名随时间变化的 DNS 查询量。
• umbrella_domain_resource_records - 域名的被动 DNS 资源记录。

对于 Cisco 文档未完整列出筛选条件集的 Reports/Investigate/Deployments/Admin/Policies 列表工具，均接受一个可选的 additionalParams 对象，并将其原样作为额外的查询字符串参数传递（例如 Reports 端点上的 categories、identityids、verdict、domains）——这些是 Cisco 文档中提及、但此客户端未建模为一等参数的筛选条件。

范围

这是 v1 的只读接口：此服务仅实现 Deployments、Admin、Policies、Reports 和 Investigate 中的 GET 端点。以下功能明确延期；它们均列在 Cisco 自己的 Postman 集合中，但目前不在范围内：

• 添加/移除内部域名（POST/DELETE /deployments/v2/internaldomains）
• 添加/移除隧道（POST/DELETE /deployments/v2/tunnels）
• 添加标签以及为设备添加/移除标签（POST /deployments/v2/tags*）
• 创建/删除用户（POST/DELETE /admin/v2/users）
• 创建 API 密钥（POST /admin/v2/apiKeys）
• 在目标列表中添加/移除目标（POST/DELETE /policies/v2/destinationlists/{id}/destinations）
• 更新 App Discovery 应用的标签（PATCH /reports/v2/appDiscovery/applications/{id}）

这些是配置/变更操作，不属于只读监控连接器的范围——与本轮其他连接器（Printix、WatchGuard Cloud）推迟以配置为主的写入操作一致。如果将来需要支持写入的 v2 版本，可在后续添加。

以下内容也明确不在范围内：Legacy Umbrella Reporting v1/v2 API（身份验证方式和主机不同——investigate.api.umbrella.com / management.api.umbrella.com），以及通过 X-Umbrella-OrgId 标头切换 Multi-org/MSP 子组织。后者是 Cisco 实际提供且有文档说明的行为，但缺少足够具体的请求/响应细节（该标头适用于令牌请求、每个后续请求，还是两者都适用），且没有可用于验证的有效凭据对，因此无法有把握地实现。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。启动时仍要求提供有效的 CONDUIT_S2S_SECRET，否则会拒绝运行。请将端口发布到回环地址。在 gateway 模式下，Umbrella 凭据会随每个请求以标头形式传入；服务不会从环境变量中读取这些凭据。

docker build -t cisco-umbrella-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  cisco-umbrella-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它默认将 AUTH_MODE 设为 gateway，发布 127.0.0.1:8080:8080，并且不会设置 CISCOUMBRELLA_API_KEY、CISCOUMBRELLA_API_SECRET 或 env_file：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求提供 S2S 密钥，然后使用 CISCOUMBRELLA_API_KEY 和 CISCOUMBRELLA_API_SECRET。它与上文的 gateway Compose 服务相互独立。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CISCOUMBRELLA_API_KEY=... \
  -e CISCOUMBRELLA_API_SECRET=... \
  -p 127.0.0.1:8080:8080 \
  cisco-umbrella-mcp

不提供密钥的本地 HTTP 仅供开发使用。它会绑定到 127.0.0.1（包括 MCP_HTTP_HOST 为 localhost 或 ::1 的情况），并记录一条警告。若 MCP_HTTP_HOST 不是回环地址，启动将退出。容器镜像将 MCP_HTTP_HOST 设为 0.0.0.0，因此在 Docker 中绕过密钥检查时，还需要添加 -e MCP_HTTP_HOST=127.0.0.1。请勿将该端口发布到回环地址之外。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http