Avanan MCP

Avanan + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方项目。由社区构建的 Claude Code Skill 和 Avanan API 的 MCP 服务。 与 Check Point 无关联，也未获其认可或赞助。Avanan 和 Harmony Email & Collaboration 是 Check Point Software Technologies Ltd. 的商标。

支持 Avanan（Check Point Harmony Email and Collaboration）的所有 API 操作，还提供轮班开始时的分诊、钓鱼活动聚类、单条消息生命周期时间线、跨七种安全引擎的一次性例外查询，以及无状态 API 镜像无法通过单次调用回答的跨租户 MSP 机群汇总。可与您已在使用的 AI 配合使用——ChatGPT（Plus/Pro+，在此连接器重新发布前暂停；请参阅 mcp-install.md）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot——还可通过远程路径使用 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini。免费、开源，可在您的笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于您的 Agent

安全提示（在此连接器重新发布前）。 请勿将此连接器放在 supergateway 桥接程序或任何其他 stdio-to-HTTP 桥接程序之后， 即使在 localhost 上也不行。桥接程序不会添加密码，因此任何能访问其端口的人都可以使用 MCP 工具和您的凭据。请使用默认的 stdio 传输。如果您为远程 Agent 设置了桥接程序或隧道，请将其关闭。修复即将推出。

MSP 所有者实际使用的六种 Agent（可自行安装，现已可用）：

您的 AI Agent	如何安装 Avanan Skill
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 avanan-mcp（无需编辑 JSON）。
ChatGPT（付费套餐）	在此连接器重新发布前暂停：ChatGPT 需要 HTTPS 服务，而此版本仅支持 stdio，因此需要一个不会添加密码的 stdio-to-HTTP 桥接程序。请参阅 mcp-install.md 中的安全提示。
Codex CLI	粘贴下方的安装提示词。
Claude Code	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，在 mcp.json 的 servers 键下添加 avanan-mcp，然后选择 Agent 模式。

ChatGPT 需要远程 HTTPS 服务。此连接器仅支持 stdio，因此需要一个不会添加密码的 stdio-to-HTTP 桥接程序；在此连接器重新发布前，这种方式已暂停。请参阅 mcp-install.md 中的安全提示。

也适用于 Microsoft 和 Google 技术栈

用户群很大，但需要坦诚说明：这属于远程 / 企业路径，并非您刚刚安装的本地二进制程序。

Agent	所需条件
Microsoft 365 Copilot / Copilot Studio	在此连接器重新发布前暂停：Copilot Studio 需要 HTTPS 服务，而此版本仅支持 stdio，因此需要一个不会添加密码的 stdio-to-HTTP 桥接程序。请参阅 mcp-install.md 中的安全提示。
Google Gemini	Gemini CLI 在本地运行，与 Claude Code 相同。Gemini app 在远程运行，需要与 ChatGPT 相同的远程路径，目前已暂停。请参阅 mcp-install.md。

60 秒内完成安装

更喜欢 Claude Code 插件？添加一次市场源，然后安装：

/plugin marketplace add Servosity/msp-skills
/plugin install avanan@msp-skills

路径 A - 向你的 AI Agent 粘贴一条提示词（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork 中：

在此 Agent 工作区中安装 Servosity/msp-skills 提供的 Avanan Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），请运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh)。如果使用 Windows PowerShell，请运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex。然后按照 README 中的说明进行身份验证，并运行 avanan-cli --help 以了解相关功能。

同一条提示词也适用于任何能够运行 shell 的 Agent。

路径 B - 自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh)

安装程序会将 avanan-cli（CLI）和 avanan-mcp（MCP 服务）都放入你的用户 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现该 Skill。

验证：

avanan-cli --version

升级到最新版本

安装程序始终会获取当前版本 - 重新运行即可升级：

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.sh)

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/avanan/install.ps1 | iex

Claude Code 插件用户：/plugin update avanan@msp-skills。

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请参阅 mcp-install.md 和 docs/which-agent.md，查看各 Agent 的接入说明 - 每个 Agent 均有单独章节，其中包括 GitHub Copilot 的 servers 键，以及 Microsoft 365 Copilot / Copilot Studio 的远程接入方式。Claude Desktop 的“设置”>“扩展”面板是最简单的方式；mcp-install.md 中也记录了 MCP 配置块（适用于偏好编辑 JSON 的用户）。

为 Hermes 安装

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/avanan --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/avanan --force

Hermes 原生支持 MCP，因此也可以直接使用 avanan-mcp 服务 - 安装路径和环境变量相同。

为 OpenClaw 安装

告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/servosity/msp-skills/tree/main/skills/avanan 安装 avanan skill。该 skill 说明了如何通过 openclaw: frontmatter 块安装其所需的 CLI（avanan-cli）。

OpenClaw 尚未普遍开放；frontmatter 接入配置已预先提供，OpenClaw 一经推出便会立即启用。

身份验证

设置 CLI 所需的应用程序凭据（Avanan 门户 > Settings > API Keys），然后为你的区域生成会话令牌：

export AVANAN_APP_ID=<your application id>
export AVANAN_CLIENT_SECRET=<your client secret>
avanan-cli auth login --region us --save
avanan-cli doctor

doctor 会确认凭据是否有效，并在你运行任何会触及数据的命令之前，打印它解析出的两种身份验证方案之一以及区域主机。即使凭据被拒绝，它也会以 0 退出，因此脚本应添加 --fail-on error。

Avanan 凭据有两点值得提前了解：

• --since 按 Avanan 的摄取时间筛选，而非邮件日期。 API 的 startDate/endDate 与 entityCreated 匹配，也就是 Avanan 扫描邮件的时间。 该时间通常与接收标头相差几秒，但也可能比它晚一小时以上。因此，某个时间 窗口可能会漏掉窗口内收到、但在窗口结束后才扫描的邮件。请扩大时间窗口， 不要仅凭邮件时间判断。
• 操作需要 SaaS 实体类型，而非通用类型。 隔离和还原需要 office365_emails_email 或 google_mail_email；remediate 会从实体本身解析类型，--entity-type 可覆盖此设置。
• 各区域之间完全隔离。 凭据按区域签发，设计上会拒绝跨区域读取，因此 USA 密钥在 EU 租户中查不到数据，并不代表密钥无效。有效区域：us、eu、ca、ap、uk、uae、in，以及 Infinity Portal 网关专用的 infinity 和 infinity-us。其他 Infinity Portal 网关没有区域代码，请使用 --base-url 或 AVANAN_BASE_URL 指定 CLI 连接到该网关。
• 一个应用程序凭据可以访问多个租户。 运行 avanan-cli scopes，准确查看你的凭据涵盖哪些 {farm}:{tenant} 范围。这也是你最有效的控制手段：绑定到单个租户的凭据会让整个租户群都无法访问。请参阅 governance.md。

先同步，再提问

大多数跨租户查询都来自本地镜像。先填充一次镜像：

avanan-cli mirror --since 7d
avanan-cli sync --resources msp

mirror 和 sync 对 Avanan API 进行只读访问，并将数据写入你自己的用户帐户下的 SQLite 文件。需要更新数据时，请重新运行这些命令。离线命令（triage、campaign、timeline、exceptions find、exceptions audit、msp fleet）仅读取镜像；如果存储尚未填充，它们会报告结果为空，而不会悄悄改为实时扇出查询。

此技能的功能

MSP 经常提出的问题	命令
自本班次开始以来，Avanan 在我的所有租户中发现了什么？	avanan-cli triage --since 24h
这四十条检测结果属于同一场网络钓鱼活动，还是四十个独立问题？	avanan-cli campaign --since 7d
用户对一封隔离邮件提出异议。那封邮件实际发生了什么？	avanan-cli timeline <entity-id>
这个域名、发件人、URL 或哈希值是否已在某处设置了例外？	avanan-cli exceptions find example.com
我们有哪些例外设置互相矛盾，或在镜像时间窗口内从未匹配到流量？	avanan-cli exceptions audit
哪个租户的席位数超限，或本周情况异常？	avanan-cli msp fleet
隔离这批邮件，并告知我每封邮件的实际处理结果	avanan-cli remediate quarantine --entity <id> --scope <farm:tenant> --wait
我的身份验证和连接是否正常工作？	avanan-cli doctor

完整命令参考：guide.md。AI Agent 操作规范（--agent、--dry-run，以及何时应在执行修改前确认）请参阅 AGENTS.md。

这有什么不同

Avanan 已经为 Cortex XSOAR、Microsoft Sentinel、n8n 和两个社区 MCP 服务提供了集成。它们无一例外都是运行在其他产品中的插件，而且全都是无状态的：提一个问题，调用一次 API，不保留历史记录。它们没有原生支持终端的工具，也没有任何工具能回答横跨两个租户或两天的问题——除非针对一个会返回 HTTP 429 且不公布配额的 API，再额外调用 N 次。

这个技能会将事件、实体、例外和 MSP 对象同步到本地 SQLite 镜像，这样一来，这些问题只需在本地执行一次联接查询即可解决。它能将「这里有 400 条检测结果」转化为「这里有三个活动，其中一个仍有 40% 尚未修复」。

它覆盖的 API 范围也比已发布的规范更广。SwaggerHub 规范遗漏了身份验证端点、完整的逐个 sectool 例外接口，以及 SOAR 和下载辅助功能——大约 15 个操作，这些操作已在供应商参考网站上记录，并且已在正式发布的 XSOAR 和 Sentinel 代码中得到验证。这里都包含了。

它还正确实现了请求签名。旧版握手会签名 reqId + appId + date + requestString + secret，而每个非身份验证调用都需要包含 requestString，已发布的文档却没有提到这一项——因此，如果客户端生成的查询字符串与签名时的字符串不同，就会收到 401 错误，看起来和凭据错误完全一样。这个 CLI 通过同一条代码路径完成签名和发送。

它解决的痛点

• 事件端点会返回检测结果，却从不对其分类，因此每次轮班开始时，都得重新滚动查看一小时前已经运行过的查询。avanan-cli triage 会按威胁类型、严重性和状态生成摘要，并列出造成大量结果的发件人域名。
• 没有工具会对检测结果分组，因此要想分辨一次网络钓鱼行动和四十个互不相关的问题，只能按发件人和主题对导出结果排序。avanan-cli campaign 会对其进行聚类，并显示收件人分布和修复状态。
• 对有争议的隔离邮件，需要通过三个端点进行五次查询，而且任务记录会过期。avanan-cli timeline 会根据镜像中的数据和此 CLI 提交的内容，按顺序重建单封邮件的历史记录。
• 例外分散在七个引擎和九张表中，各自的路径结构、ID 方案和删除语义都不相同，而且没有工具能回答「这项内容是否已经设置了例外」。avanan-cli exceptions find 会一次性查询所有引擎；avanan-cli exceptions audit 会找出镜像时间范围内的矛盾、重复项，以及没有匹配到流量的条目。
• 操作是异步的，且只能针对单一范围：端点会返回任务 ID，并以普通 HTTP 400 拒绝多租户凭据。avanan-cli remediate 会等待任务完成，报告实际的逐项结果，并将该 400 错误转换为明确指出可操作范围的错误。

更详细的说明请参阅 pain-point.md。

常见问题

这能与 ChatGPT 配合使用吗？

当前版本不行。ChatGPT（Plus、Pro、Team、Business、Enterprise 和 Education 计划；Free 目前尚未开放 Developer Mode）只能通过 HTTPS 连接到远程 MCP 服务。Avanan MCP 服务仅支持 stdio，因此需要在其前面架设 stdio-to-HTTP 桥接服务，而这个桥接服务不会增加任何密码保护。请勿在连接器重新发布之前进行设置，也不要将其置于隧道后；mcp-install.md 中的安全说明解释了原因。在此之前，请使用 Claude Desktop、Claude Code 或 Codex。

这能与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 配合使用吗？

可以——它们都支持 MCP。跨工具安装命令请见上方的矩阵，以及 docs/which-agent.md 中的深入说明。

我需要会编程吗？

不需要。推荐的安装方式是在 Claude Code 或 Codex 中粘贴一句话——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是每种操作系统各用一条安装命令（bash 或 PowerShell）。这两种方式都不需要编写代码。你只需输入一次 Avanan 应用 ID 和客户端密钥。

我的 Avanan 数据安全吗？

你的数据会保留在自己的机器上。CLI 和 MCP 服务都是本地二进制程序，MCP 服务仅使用 stdio 通信，不会打开网络监听端口。SQLite 镜像存放在你用户账户下的一个目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始批量数据。只有在你明确指定某条消息时，才会获取邮件正文和原始 .eml 文件。凭据从你的环境或 Agent 配置中读取；MSP Skills 绝不会将其打包到此仓库中，也不会将其传输到任何地方。

这会触发 Avanan API 速率限制吗？

基本不会。此技能只需将数据镜像到本地 SQLite 一次，之后便从本地数据中提供答案，因此离线命令不会消耗 API 配额。Avanan 没有公布配额数值，但会返回 HTTP 429，因此客户端会自动退避；镜像填充完成后，六个离线命令不会产生任何费用。

我需要 MSP 账户吗？还是可以用于单个租户？

两种情况都可以。msp 命令和租户群组汇总需要绑定多个租户的应用凭据，但分类处理、活动、时间线、例外查询、搜索和修复功能都可以正常用于单租户凭据。

为什么我的 Avanan 凭据无法用于其他区域？

Avanan 各区域之间严格隔离，且凭据按区域签发，因此 USA 密钥无法读取 EU 数据，这是设计如此。使用 avanan-cli auth login --region <us|eu|ca|ap|uk|uae|in|infinity|infinity-us> --save 设置一次区域即可。位于其他网关上的 Infinity Portal 租户没有区域代码，应改用 avanan-cli auth login --base-url https://<your-infinity-gateway> --save。avanan-cli doctor 会显示解析出的主机。

为什么隔离和恢复操作需要指定范围？

Avanan 的操作端点只接受一个范围，并会以一条看似密钥错误的 HTTP 400 响应拒绝多租户凭据——这是此 API 最常见的集成陷阱。remediate 会将其转换为错误，并列出你的凭据实际覆盖的范围，确保影响邮箱的写入操作不会落到你未指定的租户上。

它支持 Check Point 防火墙或终端产品吗？

不支持。它仅支持 Avanan / Harmony Email and Collaboration：电子邮件和 SaaS 协作安全。Check Point 系统和审计日志位于独立的 Infinity Portal API 中，不属于此工具的范围。

它会取代 Avanan 门户吗？

不会，它是对门户的补充。安全策略规则和引擎配置只能在门户中操作——API 提供的是例外，而非策略。此技能可以回答问题，并完成门户中操作缓慢的批量工作。

费用是多少？

免费。采用 Apache-2.0 许可。你只需为所使用的 AI Agent（Claude、ChatGPT、Codex 等）付费；费用由你的 AI 提供商收取，而非我们收取。

安全模型

层级	示例	建议的 Agent 策略
读取	triage、campaign、timeline、exceptions find、exceptions audit、msp fleet、event query、scopes、search、mirror、sync、export，以及下文各层级未列出的 list / get 命令	允许
消息内容外发	download、download-large-email、avanan-search get-saas-entity（目前在所有已测试的租户上，soar get-entity 都会返回 404）	仅限开放调查中的指定消息；绝不进行全面扫描
写入（常规）	exceptions create、exceptions update、sectool-exceptions create、sectools create-ctp-item、report	使用 --dry-run 预览，然后经审核后写入
批量写入（import）	import（从 JSONL 批量 POST；import action 会触达实际邮件，import soar 会通知最终用户，import msp 会修改租户）	仅限人工批准。其权限等级取决于目标资源，而它可接受的资源会触达下方影响邮箱和需人工介入的端点。请先使用 --dry-run 预览。
影响邮箱	remediate quarantine、remediate restore、action post-entity、action post-event	必须经人工批准，且始终显式指定 --scope
联系最终用户	soar post-notify	仅限人工介入
租户和账单生命周期	msp create-tenants、msp create-users、msp update-or-create-tenant-license	仅限人工介入
破坏性操作	msp delete-tenants、msp delete-users、exceptions delete、sectool-exceptions delete、sectools delete-ctp-lists	仅限人工介入，并须明确确认

有两类操作会触及仪表板之外的对象。remediate 和 action 命令会隔离并恢复客户 Microsoft 365 或 Google Workspace 中的实际邮件，而 soar post-notify 会代表你向真实用户发送邮件。对这两类操作，应采用你处理用户邮箱时已有的审批流程。msp delete-tenants 会删除整个客户租户，且此处没有其他操作能与之匹敌，造成如此大的影响范围。

最有力的控制措施是应用凭证的作用范围——它绑定到一个区域和一组特定租户，CLI 只能访问其涵盖的内容。完整详情（包括如何限制其权限）请参阅 governance.md。

状态

已在实际环境中验证。@geekbrownbear（Bearium Networks，MSP）已在其生产租户上确认（验证记录）。更多 MSP 正在我们的每周 Build Sessions 中实际运行。请在 compoundingteams.com/build-sessions 报名参加。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；适用于 40 多种 Agent）。兼容 MCP——可与任何支持 MCP 的 Agent 配合使用，包括 Hermes。已为 OpenClaw 做好准备（frontmatter 已预先配置，等待 OpenClaw 发布）。

由 Servosity 维护。采用 Apache-2.0 许可证。使用 CLI Printing Press 构建。最后更新：2026-08-15。