Avanan MSP (Legacy SmartAPI)

avanan-legacy-mcp

适用于 smart-api-production-*.avanan.net 上旧版 Avanan SmartAPI 的 MCP 服务： MSP 租户管理，以及各租户的安全功能（事件、实体、例外和修复）。 与面向 Check Point Infinity Portal HEC API 的 avanan-mcp 不同。

实现了 Avanan MSP SmartAPI Reference Guide（2026 年 7 月 22 日） 和 Avanan SmartAPI Reference Guide（2024 年 2 月）：

分组	工具
诊断	avanan_test_connection（身份验证握手、密钥范围、MSP 访问探测；请先运行此工具）、avanan_list_scopes
安全事件	avanan_query_events、avanan_get_event
受保护实体	avanan_search_emails、avanan_get_email
例外	avanan_list_exceptions、avanan_get_exception、avanan_add_exception、avanan_update_exception、avanan_delete_exception
修复	avanan_quarantine_events、avanan_restore_events、avanan_quarantine_emails、avanan_restore_emails、avanan_get_task_status
子级 MSP	avanan_list_msp_partners、avanan_create_msp_partner、avanan_delete_msp_partner
MSP 用户	avanan_list_msp_users、avanan_get_msp_user、avanan_create_msp_user、avanan_update_msp_user、avanan_delete_msp_user
客户租户	avanan_list_tenants、avanan_get_tenant、avanan_create_tenant、avanan_delete_tenant
许可证	avanan_list_licenses、avanan_list_addons、avanan_assign_license
用量	avanan_get_monthly_usage、avanan_get_daily_usage

功能

• 交互式租户卡片（MCP Apps，SEP-1865）：在 MCP Apps 宿主（Claude Desktop/web）中，avanan_get_tenant 会渲染为交互式卡片，显示域名、状态、部署模式、许可证套餐、受保护用户、PoC 日期和附加组件。卡片默认为中性样式且只读，可通过注入 window.__BRAND__ 或 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制。在其他宿主中，纯 JSON 行为保持不变。编辑 ui/ 后，请运行 npm run build:ui 重新构建嵌入式卡片 HTML。

配置

环境变量	必填	描述
AVANAN_CLIENT_ID	stdio 和 AUTH_MODE=env 时必填	SmartAPI 客户端 ID（作为 x-av-app-id 发送）。MSP 或客户租户密钥；见下文。
AVANAN_CLIENT_SECRET	stdio 和 AUTH_MODE=env 时必填	SmartAPI 客户端密钥。仅用于签署请求；绝不会通过网络发送。
AVANAN_REGION	否	us（默认）| eu | ca | ap | euw2 | aps1。Avanan 每个区域都会签发一个密钥。不是凭据。
MCP_TRANSPORT	否	stdio（默认）或 http。
AUTH_MODE	否	env（默认）或 gateway。容器镜像和 Compose 设置为 gateway。Gateway 模式要求每个请求都携带 X-Avanan-Client-Id 和 X-Avanan-Client-Secret，且绝不会回退使用 AVANAN_*。
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（默认 info）。
CONDUIT_S2S_SECRET	HTTP 必填	服务间密钥。如果此变量为空或为已知占位值（changeme、secret、your-s2s-secret 及其他示例值），HTTP 会记录错误并以非零状态码退出。未设置时，Compose 不会启动。切勿提交真实值。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为恰好 1，以便在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且仅监听 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略。占位密钥仍会被拒绝。

复制 .env.example。将其中的 CONDUIT_S2S_SECRET 留空。

/health 无需身份验证，也不会读取凭据。stdio 传输不会使用 CONDUIT_S2S_SECRET 或 X-Gateway-S2S。

HTTP 身份验证

当 MCP_TRANSPORT=http 且设置了真实的 CONDUIT_S2S_SECRET 时，除 /health 外，每个请求都必须包含 X-Gateway-S2S：

t=<unix seconds>,v1=<hex>

v1 是对 ASCII 字符串 t=<unix seconds>（与标头开头的 t= 前缀相同）计算的 HMAC-SHA256，以 CONDUIT_S2S_SECRET 为密钥，并编码为 64 个小写十六进制字符。时间戳与服务器时钟的偏差不得超过 300 秒。比较采用时序安全方式。缺少标头或标头无效时，会返回 401，且不会访问 Avanan 凭据。密钥绝不会记录到日志中。

在 AUTH_MODE=gateway 模式下，请求还必须包含 X-Avanan-Client-Id 和 X-Avanan-Client-Secret（X-Avanan-Region 为可选项）。这些标头是唯一的凭据来源。请求缺少其中任一标头时，会返回 401，且不会回退使用 AVANAN_CLIENT_ID / AVANAN_CLIENT_SECRET。

在 AUTH_MODE=env 模式下，/mcp 仍要求有效的 X-Gateway-S2S 标头。如果请求未同时携带客户端标头，供应商凭据将从环境变量中获取。

Docker

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并设置 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，Avanan 凭据会作为请求头随每个请求传入；服务不会从环境变量中读取这些凭据。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway、发布 127.0.0.1:8080:8080，并且不会将 AVANAN_CLIENT_ID 或 AVANAN_CLIENT_SECRET 放入服务环境变量中：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 AVANAN_CLIENT_ID 和 AVANAN_CLIENT_SECRET。这与网关 Compose 服务相互独立。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e AVANAN_CLIENT_ID=your-client-id \
  -e AVANAN_CLIENT_SECRET=your-client-secret \
  -e AVANAN_REGION=us \
  -p 127.0.0.1:8080:8080 \
  avanan-legacy-mcp

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

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

使用 openssl rand -hex 32 生成密钥。不要在 CONDUIT_S2S_SECRET 中保留占位符；启动时会将这些值视为未设置，并退出。

服务端会自行完成令牌握手：调用 GET /v1.0/auth，按客户端 ID 缓存有效期为一小时的 JWT，并在到期前一分钟刷新。

重要

MSP 管理工具需要 MSP API 密钥。这类密钥不能自行申请：Check Point/Avanan 支持团队会按需签发；如果通过渠道购买 Avanan，请联系分销商申请；每个区域需要一把密钥。在客户租户内生成的密钥虽然可以成功通过身份验证，但之后每个 /msp/* 端点都会返回 403 MSP endpoint, access denied。安全工具（事件、实体、例外、修复）可使用任一类型的密钥。avanan_test_connection 会报告你持有的密钥类型。

使用 MSP 密钥时，安全工具涵盖所有托管客户；传入 avanan_list_scopes 返回的值作为 scopes（查询和搜索）或 scope（操作），即可指定目标客户。

父级 MSP 可以使用可选的 MSPId 参数将列表和创建调用限定到子级 MSP（用法工具中为 msp_ids），与 Check Point 的参考客户端一致。

身份验证详情

线路格式已根据 2026 年 9 月的 US 实时端点进行验证，并由 tests/client.test.ts 固定。以下两点与参考指南不同：

• x-av-date 末尾不能带 Z（2026-09-09T16:49:12.123）。文档中所示的 .000Z 格式会导致 API 返回 HTTP 500。
• x-av-sig 的格式为 sha256(base64(reqId + clientId + date + path?query + secret))，结果以十六进制表示。仅在 /auth 调用中省略路径，且 /auth 响应正文是原始 JWT，而不是 JSON。

这两点均与 Check Point 的参考 client.py 一致。

构建

npm install
npm run build
npm start

区域端点

区域	基础 URL
us	https://smart-api-production-1-us.avanan.net
eu	https://smart-api-production-1-eu.avanan.net
ca	https://smart-api-production-1-ca.avanan.net
ap	https://smart-api-production-5-ap.avanan.net
euw2（英国）	https://smart-api-production-1-euw2.avanan.net
aps1（印度）	https://smart-api-production-1-aps1.avanan.net

所有端点均位于 /v1.0/msp/... 下。