Telivy

Telivy MCP Server

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Telivy 面向 MSP 的安全评估 API，提供外部（攻击面）扫描、深度扫描风险评估、设备清单、M365/Google Workspace 用户暴露情况、PII 摘要以及发现项级别的详细信息。

Authentication

Telivy 使用一个静态 API 密钥进行身份验证，该密钥可在 Telivy Portal（Account > Integrations）中生成。此外还支持 OAuth2/Auth0 隐式流程，但 API 密钥方式更简单，也是 MSP 集成所使用的方式，因此本连接器采用此方式。密钥通过 x-api-key HTTP 标头发送。

Configuration

复制 .env.example，并设置以下变量。在示例中将 CONDUIT_S2S_SECRET 留空；使用 openssl rand -hex 32 生成实际值。

Env var	Description
TELIVY_API_KEY	Telivy 签发的 API 密钥。stdio 和 AUTH_MODE=env 时的 HTTP 模式都需要此密钥。网关模式不会读取该密钥。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（Docker 外部的默认值；读取 TELIVY_API_KEY）或 gateway（每个请求通过 X-Telivy-Api-Key 传入凭据）。镜像和 Compose 文件的默认值为 gateway。缺少该标头时，网关模式会返回 401，且不会回退到 TELIVY_API_KEY。
CONDUIT_S2S_SECRET	HTTP 模式必需。用于验证 /mcp 上的 X-Gateway-S2S 的 HMAC 密钥。如果该值为空或是已知占位符（changeme、secret、your-s2s-secret 以及 src/http.ts 中的其他示例值），进程会记录错误并以非零状态退出。该值不会被记录。未设置时，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。配置了密钥时，此值会继续生效，包括 0.0.0.0。容器镜像会设置为 0.0.0.0。未配置密钥时，不安全开发模式绕过设置会强制绑定到 127.0.0.1。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

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

HTTP authentication

当设置了 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，且发生在读取 Telivy API 密钥之前。

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-Telivy-Api-Key: $TELIVY_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Telivy-Api-Key。该标头是此请求唯一的凭据来源。AUTH_MODE=env 仍要求提供有效的 X-Gateway-S2S 标头，然后使用环境变量中的 TELIVY_API_KEY。

Tools

External scans

• telivy_list_external_scans - 列出外部（攻击面）扫描，支持搜索、排序和分页。
• telivy_get_external_scan - 按评估 ID 获取单个外部扫描。
• telivy_list_external_scan_findings - 列出外部扫描的发现项。
• telivy_get_external_scan_finding - 按 slug 获取单个外部扫描发现项的详细信息。
• telivy_get_breach_data - 获取外部扫描所涉及域名的泄露记录。

风险评估

• telivy_list_risk_assessments - 列出深度扫描风险评估，支持搜索、排序、分页和状态筛选。
• telivy_get_risk_assessment - 根据 ID 获取单个风险评估。
• telivy_list_risk_assessment_devices - 列出某个风险评估的所有深度扫描设备。
• telivy_get_risk_assessment_device - 根据 ID 获取单个深度扫描设备。
• telivy_get_risk_assessment_scan_status - 获取所有设备的扫描完成状态。
• telivy_list_m365_users - 获取 Microsoft 365 用户账户及其登录状态和 MFA 信息。
• telivy_list_gws_users - 获取 Google Workspace 用户账户及其登录和 2SV 状态。
• telivy_get_pii_summary - 获取所有设备的 PII 暴露情况摘要。

发现项、Agent 版本和风险进度

• telivy_get_agent_versions - 获取最新的深度扫描 Agent 版本（Windows/Mac）。
• telivy_get_finding - 根据 slug 获取顶层发现项的详细信息（例如 TYPO_SQUATTING、PERSONAL_EMAILS）。
• telivy_get_risk_progress - 对比两组扫描时间戳，获取进度报告（新增/已解决/复发/未关闭的发现项）。

范围

这是一个 v1 版本、只读的 MSP 设备群/安全可见性接口，符合本轮将连接器范围限定为监控/可见性、暂不纳入配置类写入操作的惯例。目前明确不在范围内的内容：

• 所有写入端点：创建或更新外部扫描和风险评估、rescan-all、uninstall-all、重新扫描单台设备、convert-to-risk-assessment，以及更新监控设置。这些属于配置或破坏性操作，而非只读可见性功能。
• 二进制报告下载端点（GET .../external-scans/{id}/report、GET .../risk-assessments/{id}/report）——它们返回文件，而不是此连接器的工具所处理的结构化 JSON。
• GET /api/v1/security/risk-assessments/{id}/domain-change-preview ——用于预览正在进行的域名变更写入操作的端点。由于其预览的写入操作不在范围内，因此该端点也不在范围内。

如有需求，可在后续添加。

开发

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

在设置 CONDUIT_S2S_SECRET 之前，HTTP 服务不会启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

如果未设置服务间密钥，本地 HTTP 服务只会绑定到 127.0.0.1，并记录警告日志。镜像将 MCP_HTTP_HOST=0.0.0.0 设为默认值，因此要绕过此限制，还必须将该变量设为回环地址（或取消设置）。如果主机不是回环地址，启动将退出：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

镜像在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入有效的 S2S 密钥。在网关模式下，每个请求都会通过 X-Telivy-Api-Key 传入 Telivy API 密钥；该密钥不会从环境变量读取。

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

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

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

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