Island Browser

Island MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Island 的企业浏览器管理 API，支持管理员操作、浏览器／会话审计事件、受泄露凭据检测以及设备清单。

范围：4 个只读工具，每个对应一个已记录的资源组

此连接器仅实现 Island 为其 v1 管理 API 记录的 4 个资源组：Admin Actions、Audit（Island 将其自身的此端点命名为 timeline）、Compromised Credential 和 Device。Island 还记录了第五个资源 User，但此连接器有意不涵盖它（当前未提出需求；后续可添加）。

4 个资源组中的两个——Compromised Credential 和 Device——在 Island 自身的 API 上使用带请求体的 POST 操作，而不是普通的 GET。两者都不会修改任何内容：它们是带筛选条件的搜索读取操作，只是将筛选参数放在 JSON 请求体中，而不是查询字符串中。这与此网关的 UniFi 连接器已采用的 ISP 指标查询工具相同，即“用于筛选读取的 POST，而非变更操作”。此连接器中的工具不会调用任何 PATCH／PUT／DELETE 端点，也不会访问 Island 更广泛的管理控制台功能（策略 CRUD、用户／浏览器配置策略管理）——请参阅 src/client.ts，其中仅实现了这 4 个只读操作。

Island 的权威 API 参考文档（documentation.island.io/apidocs）会重定向到需要身份验证的客户门户，因此在本次构建中无法访问。 以下端点路径、Api-Key 请求头名称、请求／响应格式和默认基础 URL，均通过另一个公开可读的来源独立确认：criblpacks/cribl-island-browser-rest-io。这是已发布的第三方日志收集器集成，其代码库提供了针对 Island 在线 API 的真实、可执行 REST 收集器作业定义（default/jobs.yml），而非营销文案或文字推测。响应正文的字段名称未能从任何来源独立确认，因此会按 Island 返回的原样传递（请参阅 src/types.ts 中的 IslandApiResponse），而不会重新建模为猜测的格式。

基础 URL

以下每个端点都已确认使用同一个固定主机：https://management.island.io/api。该 URL 原样取自上述 Cribl 包中的 island_browser_api_base_url 变量，该包自身的 5 个 REST 收集器作业均引用了此变量。此连接器将其用作默认值，并允许客户通过可选的 baseUrl／ISLAND_BASE_URL 字段覆盖，以防某个租户配置在其他主机上。另一个可信度较低的来源（一份仅有文字说明、没有可执行配置的第三方 SIEM 集成文档）将主机描述为 https://api.<company>.island.io，但此连接器无法独立确认或排除这种情况。需明确说明：固定主机的说法有更充分的证据支持，也是随产品提供的默认值；提供覆盖选项，正是为了避免在该默认值不适用于某个租户时造成静默故障。

身份验证

Island 管理 API 使用静态 API 密钥进行身份验证。该密钥可在 Island 管理控制台中的 Modules > Platform Settings > System Settings > Integrations > API > + Create 下生成。此处没有 OAuth 流程——此连接器始终只持有有效的 API 密钥，并通过 Island 自己的自定义 Api-Key 请求头发送（而非 Authorization: Bearer）。在网关模式下，密钥通过每个请求的 X-Island-Api-Key 请求头传入；在本地／stdio 模式下，则从 ISLAND_API_KEY 读取一次。

凭据范围：「只读」实际限制的内容

这里有两项独立的说法，置信度刻意有所不同——不要把它们合并成一句「只读」声明：

• 已从结构上验证（直接检查，完全有把握）： 此连接器自身的代码不会执行任何修改操作。client.ts 中的每个函数都调用上述四种读取操作之一；src/ 中不存在任何 PATCH/PUT/DELETE 调用，也没有以任何名称引用策略、用户或浏览器配置管理端点。
• 厂商文档所述，未经独立验证（刻意保留余地）： Island 的 API 密钥创建对话框在「Full Admin」/「System Admin」之外还提供「Read Only」角色——显然，服务端存在某种范围控制——但 Island 对该角色实际限制内容的权威文档位于上文提到的同一客户专用登录后，无法访问，因此未能独立确认。「Read Only」是否确实会在服务端阻止访问 Island 更广泛的 Management API 接口（策略 CRUD、用户管理、浏览器配置策略——此连接器均未实现或调用），而非仅是 UI 层面的标签，尚未经过测试。不要将此连接器或本 README 理解为已经确定了底层 API 密钥在选择非「Read Only」角色时能够或不能执行哪些操作——我们只能确认，无论客户密钥是以何种角色签发的，此连接器自身的代码都不会尝试上述四种读取操作之外的任何操作。

配置

复制 .env.example，并设置以下变量。将该文件中的 CONDUIT_S2S_SECRET 留空。

环境变量	必填	说明
ISLAND_API_KEY	stdio 和 AUTH_MODE=env 模式下必填	由 Island Management Console 签发的 API 密钥，通过 Api-Key 请求头发送。
ISLAND_BASE_URL	否	可选，用于覆盖 Management API 基础 URL。默认为 https://management.island.io/api——参见上文的基础 URL。
MCP_TRANSPORT	否	stdio（默认）或 http。
AUTH_MODE	否	gateway（Docker 镜像和 Compose）或 env。gateway 模式要求每个 /mcp 请求都携带 X-Island-Api-Key（X-Island-Base-URL 可选），且不会回退使用 ISLAND_API_KEY。env 模式仅在 S2S 身份验证成功后使用该变量。未设置时默认为 env（stdio 和单租户 HTTP）。
CONDUIT_S2S_SECRET	HTTP 模式下必填	服务到服务密钥。如果该值为空或为已知占位符（changeme、secret、replace-me、replace-with-a-real-secret 及其他示例值），HTTP 服务将记录错误并以非零状态码退出。使用 openssl rand -hex 32 生成密钥。未设置此变量时，Compose 不会启动。该值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	仅用于本地开发，且必须恰好设为 1，才能在未设置 CONDUIT_S2S_SECRET 时启动 HTTP。进程会记录警告，不会强制执行 X-Gateway-S2S，并且仅绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是回环地址，则拒绝启动。已知占位符密钥仍会导致启动被拒绝。
MCP_HTTP_HOST	否	设置了有效的 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时保持为 0.0.0.0，即历史上使用的容器绑定地址。镜像和 Compose 会在容器内将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	debug | info（默认）| warn | error。

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不会使用 CONDUIT_S2S_SECRET。

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，且此时尚未读取供应商凭据。

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-Island-Api-Key: $ISLAND_API_KEY" \
  -H "X-Island-Base-URL: $ISLAND_BASE_URL" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Island-Api-Key。该请求的 API 密钥只能来自此标头。X-Island-Base-URL 可选。AUTH_MODE=env 模式仍要求提供已签名的 X-Gateway-S2S 标头，然后使用环境变量中的 ISLAND_API_KEY 和 ISLAND_BASE_URL。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。通过 X-Gateway-S2S 检查（以及在 AUTH_MODE=gateway 模式下的 X-Island-Api-Key 存在性检查）后，若 Content-Length 超过上限，则返回包含 JSON-RPC 错误的 413；没有 Content-Length 的正文由 MCP SDK 传输层限制。未通过身份验证的请求仍会优先收到 401。包含超过 10000 个数组元素和对象键的工具输入会返回固定错误，不会重复工具名称。
• tools/call 参数上限为 10000 个元素（任意深度的每个数组项和对象键）。超出上限的输入会返回 isError 工具结果，且不会被分发。

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

工具

在 Conduit 网关中，以下四种工具均标记为 isAdmin: true——此处每个资源组都涉及安全／合规敏感信息（管理员身份及其操作、浏览器审计跟踪、检测到的凭据泄露，以及受管理设备清单），尽管它们全都只是读取操作。

管理员操作

• island_list_admin_actions - 按时间范围列出 Island 管理控制台中管理员执行的操作（策略变更、用户／角色变更），采用偏移量分页。

审计

• island_list_audit_events - 按时间范围列出浏览器／会话审计事件（导航、文件传输、剪贴板、打印、策略执行事件），采用偏移量分页。Island 自身对此使用的端点名称是 timeline。

凭据泄露

• island_list_compromised_credentials - 按时间范围列出 Island 检测到的泄露凭据。在 Island 自身的 API 上使用带正文的 POST（这是筛选读取操作，而非变更操作——见上文 Scope）。至少有一家第三方集成商发布的采集器配置指出，实际使用中此端点的偏移量分页不可靠（无论偏移量如何，都会返回同一页）；因此，此处的 limit／offset 应视为尽力而为。

设备

• island_list_devices - 列出此账户下运行 Island Browser 的设备，可按设备最后上报时间不早于指定时间进行筛选，并按字段排序。在 Island 自身的 API 上使用带正文的 POST（这是筛选读取操作，而非变更操作——见上文 Scope）。

按设计排除的内容

明确排除（不在此连接器的请求范围内，而非技术限制）：

• User 资源（Island API 中的 GET /external/v1/users）——Island 将其与此处实现的四项资源一并说明；但此连接器未被要求实现。经过明确的范围决策后，可作为后续工作添加。

明确排除（写入／配置——Island 更广泛的 Management API，从未实现）：

• 策略的创建、读取、更新和删除，策略元素管理，以及浏览器配置策略管理。此连接器的四个工具仅涵盖 Admin Actions、Audit、Compromised Credential 和 Device 的只读数据端点；不实现任何创建、更新或删除策略、用户或浏览器配置的端点。

如有需求，经过明确的范围决策后，可作为后续工作添加——不会默认添加。

开发

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

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），默认使用 AUTH_MODE=gateway。请将端口发布到回环地址，并传入真实的 S2S 密钥（openssl rand -hex 32）。在网关模式下，Island 凭据会作为请求头随每个请求传入；不会从环境变量中读取。请勿传入占位符 your-s2s-secret——启动时会拒绝已知占位符。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动。网关服务会设置 AUTH_MODE=gateway，不会注入 ISLAND_API_KEY 或 ISLAND_BASE_URL，并会发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ISLAND_API_KEY="$ISLAND_API_KEY" \
  -e ISLAND_BASE_URL=https://management.island.io/api \
  -p 127.0.0.1:8080:8080 \
  island-mcp

不带密钥的本地 HTTP 仅用于开发。它会绑定到 127.0.0.1 并记录警告。若 MCP_HTTP_HOST 不是回环地址，启动将退出：

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm run start:http

许可证

Apache-2.0