Proofpoint Essentials

Proofpoint Essentials MCP 服务

这是一个面向 Proofpoint Essentials API 的 Model Context Protocol (MCP) 服务。 可让 AI 助手管理 MSP 多租户电子邮件安全：组织、域名、用户、许可证、功能、订阅套餐和邮件流报告。

这是与 Proofpoint TAP 不同的产品/API（有关 TAP 威胁情报、隔离和 URL 防御，请参阅 proofpoint-mcp）——Essentials 是 Proofpoint 面向 SMB/MSP 的电子邮件安全产品， 拥有自己的基础 URL、身份验证模型和组织管理界面。

属于 WYRE AI MCP 服务集群的一部分——这是一个不断壮大的面向 MSP 技术栈的 AI 集成套件。

安装

npm install @wyre-ai/proofpoint-essentials-mcp

配置

复制 .env.example，并设置以下变量。

变量	必需	说明
PROOFPOINT_ESSENTIALS_USERNAME	stdio 和 AUTH_MODE=env 时必需	组织管理员用户名（作为 X-User 标头发送）
PROOFPOINT_ESSENTIALS_PASSWORD	stdio 和 AUTH_MODE=env 时必需	组织管理员密码（作为 X-Password 标头发送）
PROOFPOINT_ESSENTIALS_REGION	否	区域子域名，例如 us1 或 eu1（默认为 us1）
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。Gateway 模式要求每个 /mcp 请求都包含 X-Proofpoint-Essentials-Username 和 X-Proofpoint-Essentials-Password（X-Proofpoint-Essentials-Region 为可选项），且绝不会回退到 PROOFPOINT_ESSENTIALS_*。只有在 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 模式下必需	服务间密钥。此值为空或为已知占位符（changeme、secret、placeholder、your-s2s-secret、replace-with-a-real-secret，以及 src/index.ts 中的相同列表）时，HTTP 服务会记录错误并以非零状态码退出。未设置时，Compose 不会启动。切勿提交真实值。进程绝不会记录此密钥。
MCP_ALLOW_INSECURE_DEV	否	仅限本地开发时设为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、跳过 X-Gateway-S2S，且仅监听 127.0.0.1。更宽泛的 MCP_HTTP_HOST 设置会被覆盖。已知占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。配置了 CONDUIT_S2S_SECRET 时会遵循此值，包括 0.0.0.0。容器镜像将其设为 0.0.0.0。未设置密钥时，仅监听 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

只有组织管理员帐户可以通过此 API 进行身份验证；终端用户帐户不可以。

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

HTTP 身份验证

设置了 CONDUIT_S2S_SECRET 且 MCP_TRANSPORT=http 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。缺少或无效的标头会导致请求返回 401，且不会读取任何供应商凭据。

此标头是 HMAC 证明，而非密钥副本：

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

<hex hmac-sha256> 是以 CONDUIT_S2S_SECRET 为密钥，对 ASCII 字符串 t=<unix seconds>（相同的 t= 前缀和相同的十进制时间戳）计算 HMAC-SHA256 后，再编码为小写十六进制所得。时间戳与服务器时钟的偏差必须在 300 秒以内。

import { createHmac } from "node:crypto";

const secret = process.env.CONDUIT_S2S_SECRET;
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", secret).update(`t=${t}`).digest("hex");
const xGatewayS2s = `t=${t},v1=${v1}`;

在 AUTH_MODE=gateway 模式下，/mcp 还要求包含 X-Proofpoint-Essentials-Username 和 X-Proofpoint-Essentials-Password。这些标头是该请求唯一的凭据来源。

await fetch("http://127.0.0.1:8080/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    "x-gateway-s2s": xGatewayS2s,
    "x-proofpoint-essentials-username": "[email protected]",
    "x-proofpoint-essentials-password": "org-admin-password",
    "x-proofpoint-essentials-region": "us1",
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
});

使用

使用 Claude Desktop 运行

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "proofpoint-essentials-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/proofpoint-essentials-mcp"],
      "env": {
        "PROOFPOINT_ESSENTIALS_USERNAME": "your-username",
        "PROOFPOINT_ESSENTIALS_PASSWORD": "your-password"
      }
    }
  }
}

使用 Claude Code (CLI) 运行

claude mcp add proofpoint-essentials-mcp \
  -e PROOFPOINT_ESSENTIALS_USERNAME=your-value \
  -e PROOFPOINT_ESSENTIALS_PASSWORD=your-value \
  -- npx -y @wyre-ai/proofpoint-essentials-mcp

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到回环地址并传入 S2S 密钥。在网关模式下，Proofpoint Essentials 凭据会在每个请求中作为 X-Proofpoint-Essentials-* 标头传入；镜像不会从环境变量中读取这些凭据。

docker build --platform linux/amd64 --build-arg GITHUB_TOKEN=$(gh auth token) -t proofpoint-essentials-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  proofpoint-essentials-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，且不会传入任何 PROOFPOINT_ESSENTIALS_* 变量：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e PROOFPOINT_ESSENTIALS_USERNAME=your-value \
  -e PROOFPOINT_ESSENTIALS_PASSWORD=your-value \
  -e PROOFPOINT_ESSENTIALS_REGION=us1 \
  -p 127.0.0.1:8080:8080 \
  proofpoint-essentials-mcp

不使用密钥的本地 HTTP 仅用于开发。它会绑定到 127.0.0.1 并记录警告。非回环地址的 MCP_HTTP_HOST 会被覆盖为 127.0.0.1：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

可用工具

Proofpoint Essentials 是一个 MSP 多租户 API——每个组织、域名或用户范围的工具 都需要将目标客户组织的域名作为每次调用的参数（凭据不限定于单个组织）。

组织

• proofpoint_essentials_org_get — 获取组织数据及其域名
• proofpoint_essentials_org_set_active — 激活或停用组织 ⚠ 影响重大
• proofpoint_essentials_org_delete — 删除组织 ⚠ 具有破坏性且不可逆

域名

• proofpoint_essentials_domains_list
• proofpoint_essentials_domains_create — 参数：orgDomain、非空的 domains: string[]。每个名称都会作为 Domain 对象 {name} 发送；返回 { summary: { requested, returned, succeeded, failed, unconfirmed }, results }。仅当所有已返回项均成功且没有未确认项（包括缺失项）时，才会返回原始的逐项结果。requested 为提交的数量（仅在返回数量超出时才会增加到返回数量）；缺失的响应项计为未确认。任何项目失败都会设置 isError。只要有任何失败或未确认项，results 就会变为经过清理的逐项列表 { index, outcome, status, code, message }，并省略其他字段；已成功的项目已创建，不得重试。
• proofpoint_essentials_domains_update ⚠ 影响重大
• proofpoint_essentials_domains_delete ⚠ 具有破坏性且不可逆

用户

• proofpoint_essentials_users_list
• proofpoint_essentials_users_get
• proofpoint_essentials_users_create — 参数：orgDomain、非空的 users[]，其中 primary_email 为必填项，firstname、surname、type、is_active、send_welcome_email、alias_emails 为可选项。用户会以不带包装的 User 对象数组形式发送给 Proofpoint；返回 { summary: { requested, returned, succeeded, failed, unconfirmed }, results }。仅当所有已返回项均成功且没有未确认项（包括缺失项）时，才会返回原始的逐项结果。requested 为提交的数量（仅在返回数量超出时才会增加到返回数量）；缺失的响应项计为未确认。任何项目失败都会设置 isError。只要有任何失败或未确认项，results 就会变为经过清理的逐项列表 { index, outcome, status, code, message }，并省略其他字段；已成功的项目已创建，不得重试。创建时会忽略仅在响应中出现的字段（uid、password、creation_date、last_update、last_login）。
• proofpoint_essentials_users_update ⚠ 影响重大
• proofpoint_essentials_users_delete ⚠ 具有破坏性且不可逆

创建序列化和结果规范化修复要求 @wyre-ai/node-proofpoint-essentials >= 1.0.2，本软件包依赖此版本。

端点发现

• proofpoint_essentials_endpoint_discover — 确定客户域名所在的区域

功能 / 许可 / 套餐

• proofpoint_essentials_features_get / proofpoint_essentials_features_update ⚠ 高影响
• proofpoint_essentials_licensing_get / proofpoint_essentials_licensing_update ⚠ 高影响
• proofpoint_essentials_package_update ⚠ 高影响

报告

• proofpoint_essentials_reporting_get — 入站 / 出站电子邮件流量指标

令牌

• proofpoint_essentials_token_create — 创建基于 Odin 的 SSO 令牌

破坏性工具需要明确确认。交互式 MCP 客户端会通过 elicitation 提示确认；非交互式调用方（例如 WYRE 网关）必须传入 confirm_destructive_action: true，否则将被阻止。

开发

git clone https://github.com/WYRE-AI/proofpoint-essentials-mcp.git
cd proofpoint-essentials-mcp
npm install
npm run build
npm test
npm run smoke   # requires a prior `npm run build`

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，或提交 issue 讨论变更。

错误信息脱敏

错误文本和清理后的批处理结果消息会对电子邮件地址进行脱敏，包括支持的编码 @ 格式（%40、%2540、@、@、@、字面形式 \u0040，以及全角 ＠）、带空格的 @ 格式和带引号的本地部分。域名工具错误和清理后的域名创建消息也会对裸主机名进行脱敏。供应商错误正文会缩减为 statusCode 和标量 code 元数据；其他供应商字段将被省略。脱敏后，每条错误文本或清理后的单项消息最多保留 300 个 Unicode 码点（汇总批处理 JSON 不设上限）。确认全部成功的结果会保留原始数据；这是有针对性的脱敏，并非一般性的 PII 移除。

许可证

本项目采用 Apache License 2.0 版授权。详情请参阅 LICENSE。