RoboShadow

RoboShadow MCP Server

适用于 AI 助手和 WYRE Conduit 网关的 MCP 服务，连接 RoboShadow 的 Rubicon Platform Data API，涵盖终端安全（防病毒、Windows Defender、防火墙）、资产／硬件清单、应用程序、用户、漏洞和修复状态。

范围：所有已记录的操作均为只读（这是有意设计，并非经过筛选的子集）

RoboShadow 的 Rubicon Platform Data API（直接获取自 https://cdn.development.roboshadow.com/publicapi/openapi.yaml）定义了 15 个标签下的 40 个 GET 路径（Antivirus、Applications、Defender、Devices、Disks、Firewall、Hardware、Identity、MFA、Remediation、Services、Updates、Users、Vulnerabilities、Vulnerability Scanner），整个规范中只有一个非 GET 操作：POST /identity/bearertoken。这个唯一的 POST 是供应商自身文档中说明的凭据刷新机制（OpenAPI 标签：Authentication）——它会将 Refresh Token 兑换为短期 Bearer Token，不会修改任何组织数据。已发布的规范中没有任何创建／更新／删除／触发修复的端点需要排除——与本次会话中的其他连接器不同，此连接器没有需要剔除的写入功能。

**此连接器实现了全部 40 个 GET 操作，每个操作对应一个工具，并在内部调用 POST /identity/bearertoken（绝不会将其作为公开工具），仅用于保持其自身的访问令牌处于最新状态。**有关该调用存在的原因以及它为何不是工具，请参阅下文的 Authentication。

身份验证

RoboShadow 的 Rubicon Platform Data API 使用 Bearer token 进行身份验证（供应商自己的规范中为 components.securitySchemes.BearerAuth，bearerFormat: JWT）。在 RoboShadow 门户的 Reports -> API Token 下生成凭据，页面会同时显示三个值：Organisation ID、Bearer Token 和 Refresh Token。

Bearer Token 本身的有效期很短——RoboShadow 自己的 BearerTokenResponse 架构说明了以秒为单位的 expiresIn（供应商示例中约为 1 小时）。粘贴到长时间运行的连接器中的令牌会在一小时内过期，因此此连接器改为存储 Refresh Token，并在每次数据调用前通过 POST /identity/bearertoken 在内部换取新的 Bearer Token，且会在进程内缓存结果，直到令牌即将过期。Organisation ID 不作为凭据存储——将其作为 organisationId 参数传递给任意工具（如果还不知道，可使用 roboshadow_list_organisations 查找），因为在 MSP/经销商账户中，一个 Refresh Token 可能对应多个组织。

以下是两个置信度刻意不同的独立声明——这是本批连接器采用的两层区分：

• 结构上已验证（直接检查，明确陈述）： 此连接器自身的代码不会对 RoboShadow 数据 API 发起任何变更调用。client.ts 中所有读取组织数据的函数都会调用已发布规范中 40 个专用 GET 操作之一；src/ 中唯一的非 GET 调用是 Bearer Token 交换，且它不会作为 MCP 工具公开。
• 供应商文档所述，未经独立验证（刻意保留限定）： RoboShadow 自己的 OpenAPI 规范中没有任何组织数据写入/变更端点——也无法申请 Bearer/Refresh Token 的限定只读版本，因为完整令牌授予的访问权限与供应商自身规范授予的权限完全相同：仅可读取。WYRE 尚未测试 RoboShadow 平台其他未公开部分（此 Organisation-Endpoints 规范之外）是否接受使用相同令牌的写入调用——目前仅能确认，此规范和此连接器均不提供此类调用。

在网关模式下，刷新令牌会通过 X-RoboShadow-Refresh-Token 标头按请求传入；如果缺少该标头，请求会被拒绝，服务器不会回退使用 ROBOSHADOW_REFRESH_TOKEN。在本地/stdio 模式下，则从环境中读取该变量。HTTP 模式还需要下文所述的 X-Gateway-S2S 签名。

配置

环境变量	说明
ROBOSHADOW_REFRESH_TOKEN	RoboShadow 刷新令牌（门户中的 Reports -> API Token）。stdio 和 AUTH_MODE=env 必需。网关模式下不会读取。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上方的变量）或 gateway（凭据通过 X-RoboShadow-Refresh-Token 请求头逐请求传入，由 Conduit 网关注入）。如果缺少该请求头，网关模式会返回 401，且绝不会回退到 ROBOSHADOW_REFRESH_TOKEN。容器镜像和 Compose 默认使用 gateway。
CONDUIT_S2S_SECRET	启动 HTTP 传输必需。每次 /mcp 请求都会检查 HMAC 密钥是否与 X-Gateway-S2S 匹配。如果为空或为已知占位值（changeme、your-s2s-secret 及其他公开示例），进程会记录错误并以非零状态退出。该值绝不会被记录。未设置时，Compose 不会启动。
MCP_ALLOW_INSECURE_DEV	仅用于本地开发时，精确设为 1，即可在不设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会检查 X-Gateway-S2S，且只绑定到 127.0.0.1。更宽泛的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略。已知占位密钥仍会被拒绝。
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 无需身份验证，且不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

X-Gateway-S2S

在设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含由网关签名的 X-Gateway-S2S 请求头：

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对字面字符串 t=<unix seconds>（与请求头中出现的 t= 前缀和值相同）计算的 HMAC-SHA256，使用 CONDUIT_S2S_SECRET 作为密钥，并编码为小写十六进制。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少或无效的请求头会返回 401，且处理程序不会读取供应商凭据。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-RoboShadow-Refresh-Token。缺少该请求头或其值为空时会返回 401。服务器不会回退到进程环境中的 ROBOSHADOW_REFRESH_TOKEN。

请求限制

• 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（缺少请求正文 / 批处理上限）。

工具

40 个只读工具，与 Rubicon Platform Data API 已发布规范中的每个 GET 操作一一对应。所有读取组织范围数据的工具都需要 organisationId——使用 roboshadow_list_organisations 查找。

身份

• roboshadow_list_organisations - 列出此刷新令牌可访问的所有组织。
• roboshadow_list_organisation_users - 列出某个组织的用户（显示名称、电子邮件、权限级别）。PII - 仅限管理员。

MFA

• roboshadow_get_mfa_report - 针对关联 Microsoft 身份的组织，分页报告 MFA 状态（已注册的方法、MFA 状态、全局管理员标记）。PII/身份数据 - 仅限管理员。

漏洞扫描器

• roboshadow_list_scan_status - 所有外部漏洞扫描（VScanner）的状态，可按计划/状态筛选。
• roboshadow_get_scan_summary - 单次扫描的详细摘要（IP 和 Web 漏洞总数）。
• roboshadow_get_scan_ips_overview - 单次扫描中各目标的 CVE/端口明细。

应用程序

• roboshadow_list_application_groups - 按组织分组的应用程序，以及安装数/设备数/版本数。
• roboshadow_get_application_group - 单个应用程序组的详情。
• roboshadow_get_device_applications - 某台设备上安装的应用程序。

设备

• roboshadow_list_devices - 组织中的所有设备，包括硬件/操作系统标识、网络地址、健康评分以及 CVE/更新数量。PII（IP/MAC 地址、登录用户、序列号）- 仅限管理员访问。
• roboshadow_get_device - 单台设备的详情。PII - 仅限管理员访问。
• roboshadow_get_device_user_profiles - 单台设备上的 Windows 用户配置文件（包含 SID）。PII - 仅限管理员访问。
• roboshadow_get_device_users - 单台设备上的本地/AD 用户（电子邮件、员工 ID、管理员标记）。PII - 仅限管理员访问。

防病毒 / Defender

• roboshadow_get_device_antivirus - 单台设备的防病毒/端点防护状态。
• roboshadow_get_antivirus_report_by_device - 所有设备的防病毒状态。
• roboshadow_get_ransomware_report - 所有设备的勒索软件防护状态。
• roboshadow_get_antivirus_summary - 组织范围的防病毒摘要。
• roboshadow_get_antivirus_threats - 组织中检测到的防病毒威胁。
• roboshadow_get_windows_defender_report - 所有设备的 Windows Defender 配置状态。

防火墙

• roboshadow_get_firewall_report - 所有设备的 Windows 防火墙状态（按配置文件）。

磁盘

• roboshadow_get_device_disks - 单台设备上的磁盘。
• roboshadow_get_disk_shares - 单个磁盘上公开的网络共享。
• roboshadow_get_disk_report - 组织范围的磁盘使用情况，按磁盘分组。
• roboshadow_get_disk_report_by_device - 按设备分组的磁盘信息。
• roboshadow_get_disk_summary - 组织范围的磁盘使用情况摘要（空间不足的设备、未加密的驱动器、共享、USB 磁盘）。

硬件

• roboshadow_get_hardware_report_by_device - 按设备分组的硬件清单。
• roboshadow_get_hardware_summary - 组织范围的硬件摘要。

服务

• roboshadow_get_device_services - 单台设备上的 Windows 服务，包括未加引号的服务路径漏洞标记。

更新

• roboshadow_get_device_updates - 单台设备缺少的 Windows 更新。
• roboshadow_get_updates_report_by_device - 按设备分组的分页缺失更新报告。
• roboshadow_get_updates_summary - 组织范围的更新摘要以及最需要关注的设备。

漏洞

• roboshadow_get_device_vulnerability_summary - 单台设备按应用程序列出的 CVE 详情和严重性汇总。
• roboshadow_get_vulnerable_applications - 组织中存在已知漏洞的应用程序。
• roboshadow_get_cpe_vulnerabilities - 组织范围的 CPE 漏洞发现结果。
• roboshadow_get_cve_vulnerabilities - 影响组织的 CVE（CVSS/EPSS、已知遭利用标记）。
• roboshadow_get_cve_fixes - 某个 CVE 可用的修复/补丁。
• roboshadow_get_vulnerable_devices - 存在已知漏洞的设备。
• roboshadow_get_vulnerabilities_summary - 组织范围的漏洞摘要以及排名前 5 的严重应用程序/CVE/设备。

修复

• roboshadow_get_remediation_report - 组织范围的漏洞修复尝试（操作、目标、结果）。
• roboshadow_get_remediation_attempt_cves - 某次修复尝试处理的 CVE。

敏感性

RoboShadow 是一个端点安全和漏洞管理平台——即使只是读取数据，该连接器的 40 个工具中，大多数也会暴露 PII（设备用户的 SID、员工 ID 和电子邮件地址；设备的已登录用户、IP/MAC 地址和序列号）、身份/MFA 状态或安全评估数据（漏洞、威胁、修复结果、外部扫描结果）。根据本次会话对这类供应商的约定（与本轮中的 Cork、CyberQP、Cisco Duo 和 Slide 采用相同的处理方式），无论操作动词是什么，此连接器中的每个工具在 Conduit 配置中都设置为 isAdmin: true——这是有意为之、适用于整个供应商的设计决策，已在 vendor-config.ts 的 roboshadow 条目中统一记录，并非针对每个工具单独提升敏感读取权限。

开发

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 不是真实密钥，启动仍会被拒绝。请将端口发布到回环地址。在网关模式下，每个请求都会通过 X-RoboShadow-Refresh-Token 传入刷新令牌；不会从环境变量中读取该令牌。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；默认将 AUTH_MODE 设为 gateway，发布 127.0.0.1:8080:8080，且不会设置 ROBOSHADOW_REFRESH_TOKEN：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 ROBOSHADOW_REFRESH_TOKEN：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ROBOSHADOW_REFRESH_TOKEN="$ROBOSHADOW_REFRESH_TOKEN" \
  -p 127.0.0.1:8080:8080 \
  roboshadow-mcp

不使用密钥的本地 HTTP 仅用于开发。即使 MCP_HTTP_HOST 为 0.0.0.0，它也会绑定到 127.0.0.1，并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

许可证

Apache-2.0