Bitdefender GravityZone

Bitdefender GravityZone MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Bitdefender GravityZone 的 Control Center API，管理端点／网络清单、安全策略、账户级恶意软件哈希 Blocklist，以及计划生成／即时生成的报告。

此目录的新调用方式： GravityZone 的 API 使用 JSON-RPC 2.0，而不是 REST；其他所有 Conduit 伴随服务（Cork、CyberQP、Slide、UniFi、Cisco Duo）都调用常规 REST API。请参阅下文的身份验证和 JSON-RPC 调用格式。

身份验证

GravityZone 使用 HTTP Basic Authentication（RFC 2617）：API key 作为用户名发送，密码留空，即 Authorization: Basic base64(apiKey + ":")。这也是此目录中的一种新调用方式——此处其他所有静态密钥连接器（Cork、CyberQP、Slide、UniFi）都会发送自定义 X-Vendor-Api-Key 标头，伴随服务会将其转换为 Bearer 令牌；而 GravityZone 完全没有 Bearer 令牌的概念。

API key 可在 Control Center 的 My Account -> API keys 中生成。每个密钥在生成时都会绑定到一组 API 区域（Network、Policies、Reports、Incidents、Companies、Licensing、Accounts、Packages、Integrations、Push、Quarantine）。此连接器需要为密钥启用 Network、Policies、Reports 和 Incidents 区域；其余七个区域不会调用，无需启用。

此连接器还需要账户的 Control Center Access URL（位于同一 My Account 页面中的 Control Center API 下）。GravityZone Cloud、其欧盟区域，以及任何可自托管／本地部署的 Control Center 都有不同的 API 主机，因此与此目录中的大多数供应商不同，无法硬编码统一的基础 URL。

在网关模式下，每个请求都会通过 X-Bitdefender-Api-Key 和 X-Bitdefender-Access-Url 标头传入这两项信息；在本地／stdio 模式下，则分别从 BITDEFENDER_API_KEY 和 BITDEFENDER_ACCESS_URL 中读取一次。

JSON-RPC 调用格式

GravityZone 提供多个独立的 JSON-RPC 2.0 端点，每个产品区域对应一个，地址为 <accessUrl>/v1.0/jsonrpc/<area>（例如 /v1.0/jsonrpc/network、/v1.0/jsonrpc/policies）。对于某个区域的所有调用，无论执行什么操作，都会向同一 URL 发送 HTTP POST，且使用完全相同的信封格式：

{ "id": "<uuid>", "jsonrpc": "2.0", "method": "getEndpointsList", "params": { "parentId": "..." } }

操作完全位于请求正文中（method + params），而不在 URL 或 HTTP 方法中；与此目录中的所有 REST 伴随服务不同，这里没有可用于限定只读边界的 GET/POST/PATCH/DELETE 区分。因此，此连接器的只读范围是通过仅调用文档中列出的 getXxx／listXxx 方法名来强制实施的（请参阅下文的范围和 client.ts 中的 jsonRpcCall()），而不是通过限制 HTTP 方法。

成功调用会返回 { "id", "jsonrpc", "result": ... }。失败调用可能以两种方式返回，此连接器的 client.ts 会分别处理：

• HTTP 层失败——401（密钥错误／缺失）、403（未为密钥启用此 API 区域，见上文）、405（非 POST 请求）或 429（速率限制）。
• JSON-RPC 层失败——HTTP 200，但正文包含 error 成员（{code, message, data.details}，例如 -32602 Invalid params）。

速率限制：每个 API key 每秒 10 个请求；超过限制时，GravityZone 会返回 429。

配置

环境变量	描述
BITDEFENDER_API_KEY	在 Control Center 中生成的 API 密钥，需选中 Network/Policies/Reports/Incidents 区域。
BITDEFENDER_ACCESS_URL	账户的 Control Center 访问 URL（例如 https://cloud.gravityzone.bitdefender.com）。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，从上方两个变量读取）或 gateway（凭据通过 Conduit 网关注入的 X-Bitdefender-Api-Key / X-Bitdefender-Access-Url 标头随每个请求传入）。
CONDUIT_S2S_SECRET	设置后，HTTP 传输要求每个 /mcp 请求都携带有效的 X-Gateway-S2S 标头（Conduit sidecar 身份验证）。
LOG_LEVEL	debug | info（默认）| warn | error。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。通过 X-Gateway-S2S 检查后，若 Content-Length 超出上限，则返回包含 JSON-RPC 错误的 413；不含 Content-Length 的正文由 MCP SDK 传输层限制。未经身份验证的请求仍会先收到 401。
• tools/call 参数最多允许 10,000 个元素（包括任意深度的每个数组项和对象键）。超出限制的输入会返回 isError 工具结果，且不会被分发。

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

工具

Network - 终端/网络资产清单

• bitdefender_list_endpoints - 列出受管/非受管终端（名称、FQDN、IP、MAC 地址、组、Agent 标志），可选择限定范围和筛选条件。
• bitdefender_get_endpoint - 获取单个受管终端的完整详情（Agent 版本、许可证状态、扫描/更新状态）。
• bitdefender_list_custom_groups - 列出 Network Inventory 组下的子组。
• bitdefender_list_network_inventory - 列出资产清单项（组、计算机、VM、EC2 实例），并支持按类型筛选。
• bitdefender_list_scan_tasks - 列出之前创建的按需扫描任务及其状态。

Policies

• bitdefender_list_policies - 列出账户可用的安全策略。
• bitdefender_get_policy - 获取单个安全策略的完整设置。

Incidents

• bitdefender_list_blocklist_items - 列出账户 Blocklist 中的文件哈希值。

Reports

• bitdefender_list_reports - 列出账户中配置的计划/即时报告。
• bitdefender_get_report_download_links - 检查报告是否可下载，并获取报告的下载 URL。

范围

这是一个有意收窄、只读的 v1 接口：仅包含 GravityZone 的 getXxx/listXxx 方法，共 10 个，涵盖 Network、Policies、Incidents 和 Reports API。 在 Conduit 网关中，所有工具都被标记为 isAdmin: true——GravityZone 是一款终端防护产品，因此此连接器暴露的所有读取内容（终端 IP/MAC/主机名清单、安全策略设置、恶意软件哈希黑名单条目、安全态势报告）从设计上都与安全/PII 密切相关。这里没有实现任何变更方法（create/update/delete/move/set/add/remove），这是有意为之，并非疏忽：

明确排除（Network API）——永不实现：

• createCustomGroup、deleteCustomGroup、moveCustomGroup——组的配置/变更。
• moveEndpoints、deleteEndpoint——终端变更/移除。
• createScanTask——向真实的受管终端下发真正的按需扫描任务。读取方法 bitdefender_list_scan_tasks 保留；此方法不实现。
• setEndpointLabel——终端变更。

明确排除（Incidents API）——永不实现：

• addToBlocklist、removeFromBlocklist——黑名单变更。读取方法 bitdefender_list_blocklist_items 保留；这两个方法不实现。
• createIsolateEndpointTask、createRestoreEndpointFromIsolationTask——真正的远程响应操作，可将真实的受管终端与网络隔离或恢复其网络连接。

明确排除（Reports API）——永不实现：

• createReport——创建新的定时/即时报告定义。
• deleteReport——删除报告定义。

完全不在范围内（未请求，也未实现）： Companies、Licensing、Accounts、Packages、Integrations、Push 和 Quarantine API。特别是 Quarantine（getQuarantineItemsList 及其写入方法 createRemove/Restore*QuarantineItemTask）虽出现在 Bitdefender 自己的 API 分类中，但不属于此连接器的请求范围（终端/网络清单、策略、事件、报告）；如有需求，可经过明确决策后作为后续功能添加，而非默认提供。

如有需求，可经过明确的范围决策后作为后续功能添加，而非默认提供。

凭据范围

两级置信度划分，遵循本目录对凭据可访问和不可访问内容的声明惯例：

• 已通过结构验证——此连接器自身的代码绝不会调用变更型 JSON-RPC 方法：已对照 client.ts/tools/*.ts 确认，只会发送 Tools 中列出的 10 个文档化 getXxx/listXxx 方法；src/ 中不存在任何透传/任意方法调用。此连接器从设计上就是只读的。
• 厂商文档明确说明，但结论恰恰相反——GravityZone 自己的 API 密钥生成界面（Control Center -> My Account -> API keys）只按 API 区域（Network/Policies/Reports/Incidents/...）控制访问权限；这一点已通过 Bitdefender 官方 API Guide（Getting Started 第 1.3 节“API Keys”）确认：“Each API key allows the application to call methods exposed by one or several APIs. The allowed APIs are selected at the time the API key is generated”。**没有记录任何按方法或读/写权限设置的标志。**启用了 Network 区域的密钥既能调用 getEndpointsList（读取），也能调用 moveEndpoints/deleteEndpoint/createScanTask（写入）——它们属于同一区域，使用同一个权限复选框；Bitdefender 端不存在更细粒度的范围控制。此连接器的只读状态完全由其自身代码强制执行，而非由 GravityZone 本身提供的更窄凭据范围强制执行——本目录中的其他安全产品连接器（Cork、CyberQP、Cisco Duo）也已针对其管理员级别分类说明了同样的情况；这里专门针对凭据范围问题说明一次。

开发

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

Docker

docker build -t bitdefender-mcp .
docker run -p 8080:8080 -e BITDEFENDER_API_KEY=... -e BITDEFENDER_ACCESS_URL=... bitdefender-mcp