CyberQP

CyberQP MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，适用于 CyberQP（原 QuickPass Cybersecurity）的特权访问管理（PAM）API，可查看客户／账户元数据、租户事件日志，以及 JIT（即时）账户状态／策略。

身份验证

CyberQP 使用 OAuth2 authorization_code 流程（offline_access 作用域，基于 refresh_token），而非 client_credentials。此连接器本身不会执行 OAuth 授权流程：WYRE Conduit 网关负责授权、交换和刷新环节；此服务只会接收有效的 bearer 访问令牌，并通过 Authorization: Bearer <token> 将其发送到 CyberQP API。在网关模式下，令牌会通过 X-CyberQP-Access-Token 标头随每个请求传入；在本地／stdio 模式下，令牌会从 CYBERQP_ACCESS_TOKEN 读取一次。

配置

复制 .env.example，并设置以下变量。stdio 传输会读取 CYBERQP_ACCESS_TOKEN，不会使用 CONDUIT_S2S_SECRET。

Env var	描述
CYBERQP_ACCESS_TOKEN	CyberQP 签发的 OAuth2 访问令牌。stdio 模式和 AUTH_MODE=env 时的 HTTP 模式必填。网关模式不会读取此变量。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上述变量）或 gateway（凭据由 Conduit 网关注入，通过 X-CyberQP-Access-Token 标头随每个请求传入）。容器镜像和 Compose 默认使用 gateway。
CONDUIT_S2S_SECRET	HTTP 模式必填。用于对每个 /mcp 请求中的 X-Gateway-S2S 进行校验的 HMAC 密钥。若此变量为空或为已知占位值（changeme、placeholder、secret、example 等公开示例值），进程会记录错误并以非零状态码退出。未设置时，Compose 不会启动。切勿提交真实密钥。可使用 openssl rand -hex 32 生成。此值绝不会写入日志。
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）。未设置密钥时，不安全开发模式绕过选项会强制绑定到 127.0.0.1。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

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

HTTP 身份验证

当设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是 ASCII 消息 t=<unix seconds> 的小写十六进制 HMAC-SHA256 值，密钥为 CONDUIT_S2S_SECRET。时间戳与服务器时钟的偏差必须在 300 秒以内。若标头缺失或无效，将在读取任何供应商凭据之前返回 401。密钥绝不会写入日志或错误正文。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-CyberQP-Access-Token。该标头是此请求唯一的凭据来源。令牌缺失时返回 401。服务不会回退到进程环境中的 CYBERQP_ACCESS_TOKEN。

X-Gateway-S2S: t=1710000000,v1=<hmac-sha256 of "t=1710000000">
X-CyberQP-Access-Token: <live bearer token>

单租户 HTTP 模式（AUTH_MODE=env）仍要求有效的 X-Gateway-S2S 标头。访问令牌则来自 CYBERQP_ACCESS_TOKEN。

请求限制

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

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

工具

客户

• cyberqp_list_customers - 列出经过身份验证的技术人员可见的客户，可按目录类型和名称筛选。
• cyberqp_get_customer_accounts - 列出客户的账户元数据（ID、用户名、类型、状态）。
• cyberqp_get_customer_accounts_count - 获取客户各账户类型的数量。

事件

• cyberqp_get_events - 获取租户的事件日志，可按客户、账户、事件类型、状态和日期范围筛选。
• cyberqp_get_event_types - 获取完整的事件类型值集合。

租户

• cyberqp_get_tenant_company_data - 获取经过身份验证的租户自身的公司资料。

JIT（Just-In-Time）- 仅提供状态和策略

• cyberqp_get_jit_policies - 获取客户 + 账户类型对应的已配置 JIT 策略（审批要求、最长持续时间）。
• cyberqp_get_customer_jit_status - 获取指定客户的 JIT 账户状态。
• cyberqp_check_jit_account_exists - 检查客户 + 目录类型对应的 JIT 账户是否存在。
• cyberqp_get_tenant_jit_status - 获取整个租户范围内的 JIT 账户状态。

范围

这是一个刻意限定范围、只读且不会暴露凭据的 v1 接口。 CyberQP 是一款 PAM 产品——其多个真实端点会返回实时明文密码和 OTP 代码，或修改／配置特权访问。出于设计考虑（并非疏忽），这里均未实现这些端点：

明确排除（暴露凭据）——绝不实现：

• GET /api/v1/account/{accountId}/password (AccountController_getAccountPassword_v1)
• GET /api/v1/jit/customer/{customerId}/account/{accountId}/password (JitController_getJitAccountPassword_v1)
• GET /api/v1/jit/customer/{customerId}/account/{accountId}/otp (JitController_getJitAccountOTP_v1)
• POST /api/v1/jit/customer/{customerId}/account/{accountId}/otp (JitController_saveJitAccountOtpSecret_v1)
• DELETE /api/v1/jit/customer/{customerId}/account/{accountId}/otp (JitController_deleteJitAccountOtpSecret_v1)

明确排除（配置／修改）——绝不实现：

• PATCH /api/v1/jit/customer/{customerId}/account/{accountId}/enable (JitController_enableJitAccount_v1)
• PATCH /api/v1/jit/customer/{customerId}/account/{accountId}/disable (JitController_disableJitAccount_v1)
• DELETE /api/v1/jit/customer/{customerId}/account/{accountId} (JitController_deleteJitAccount_v1)
• POST /api/v1/jit/customer/{customerId}/account (JitController_createJitAccount_v1)

不在 v1 范围内（不涉及凭据或配置，仅不属于此连接器的元数据可见性范围——之后可作为有意规划的后续工作添加）：

• GET /api/v1/customers/installer (CustomerController_downloadAgent_v1) - 返回二进制安装程序，而非结构化数据。
• GET /api/v1/tenants/install-token (TenantController_getInstallToken_v1) - 返回安装令牌。
• GET /api/v1/auth/login、GET /api/v1/auth/status、POST /api/v1/auth/refresh-token、POST /api/v1/auth/revoke-token、POST /api/v1/auth/notification-engine-token - 这些是网关已负责的 OAuth／会话机制，不适合封装为工具。
• POST /api/v1/event (EventController_processGenericEvent_v1) - 写操作。
• POST /api/v1/identity-verification/self-serve-notification (IdentityVerificationController_triggerSelfServePushIdentityVerification_v1) - 写操作／通知触发器。

如有需求，可在审慎决定范围后作为后续工作添加——不会默认添加。

开发

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

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请将端口发布到环回地址，并传入 S2S 密钥。在网关模式下，每个请求都会通过 X-CyberQP-Access-Token 传入访问令牌；不会从环境变量中读取该令牌。

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

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

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CYBERQP_ACCESS_TOKEN="$CYBERQP_ACCESS_TOKEN" \
  -p 127.0.0.1:8080:8080 \
  cyberqp-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