Bitdefender GravityZone MCP Server
# Bitdefender GravityZone MCP Server
MCP server for [Bitdefender GravityZone](https://www.bitdefender.com/business/)'s Control Center API - endpoint/network inventory, security policies, the account-wide malware-hash Blocklist, and scheduled/instant reports - for AI assistants and the WYRE Conduit gateway.
> **New call shape for this catalog:** GravityZone's API is **JSON-RPC 2.0**, not REST - every other Conduit sidecar (Cork, CyberQP, Slide, UniFi, Cisco Duo) calls a conventional REST API. See [Authentication](#authentication) and [JSON-RPC shape](#json-rpc-shape) below.
## Authentication
GravityZone authenticates with **HTTP Basic Authentication** (RFC 2617): the API key is sent as the **username**, with an **empty password** - `Authorization: Basic base64(apiKey + ":")`. This is also a new shape for this catalog - every other static-key connector here (Cork, CyberQP, Slide, UniFi) sends a custom `X-Vendor-Api-Key` header that the sidecar turns into a Bearer token; GravityZone has no bearer-token concept at all.
API keys are generated in Control Center under **My Account -> API keys**, and each key is scoped, **at generation time**, to a checklist of API *areas* (Network, Policies, Reports, Incidents, Companies, Licensing, Accounts, Packages, Integrations, Push, Quarantine). This connector's key needs the **Network**, **Policies**, **Reports**, **Incidents**, and **Quarantine** areas selected - the other six are never called and do not need to be enabled. If the current key was generated without Quarantine, the quarantine tool returns HTTP 403 until a key with it is in place. `bitdefender_list_incidents` / `bitdefender_get_incident` also need a GravityZone license that includes incidents (EDR/XDR) - without one they return a JSON-RPC error.
This connector also needs the account's **Control Center Access URL** (shown on that same My Account page, under **Control Center API**) - GravityZone Cloud, its EU region, and any self-hosted/on-premise Control Center each have a different API host, so unlike most vendors in this catalog there is no single fixed base URL to hardcode.
In gateway mode, both arrive per-request via the `X-Bitdefender-Api-Key` and `X-Bitdefender-Access-Url` headers; in local/stdio mode they're read once from `BITDEFENDER_API_KEY` and `BITDEFENDER_ACCESS_URL`.
### JSON-RPC shape
GravityZone exposes several **separate** JSON-RPC 2.0 endpoints, one per product area, at `<accessUrl>/<version>/jsonrpc/<area>` (e.g. `/v1.0/jsonrpc/network`, `/v1.0/jsonrpc/policies`). Most methods are under `v1.0`; the incident-retrieval methods are only under `v1.2` (`/v1.2/jsonrpc/incidents`), and quarantine has a service suffix (`/v1.0/jsonrpc/quarantine/computers`). Every call to a given area - whatever it does - is an HTTP `POST` to that same URL with an identical envelope:
```json
{ "id": "<uuid>", "jsonrpc": "2.0", "method": "getEndpointsList", "params": { "parentId": "..." } }
```
The operation lives entirely **inside the body** (`method` + `params`), never in the URL or HTTP verb - there is no GET/POST/PATCH/DELETE distinction to key a read-only boundary off of, unlike every REST sidecar in this catalog. This connector's read-only scope is therefore enforced by only ever calling documented `getXxx`/`listXxx` **method names** (see [Scope](#scope) below and `client.ts`'s `jsonRpcCall()`), not by restricting HTTP verbs.
A successful call returns `{ "id", "jsonrpc", "result": ... }`. A failed call can come back two ways, and this connector's `client.ts` distinguishes both:
- **HTTP-layer failure** - `401` (bad/missing key), `403` (the key doesn't have this API area enabled - see above), `405` (non-POST), or `429` (rate limit).
- **JSON-RPC-layer failure** - HTTP `200` with a body `error` member (`{code, message, data.details}`, e.g. `-32602 Invalid params`).
Rate limit: **10 requests/second per API key**; GravityZone returns `429` above that.
## Configuration
| Env var | Description |
|---|---|
| `BITDEFENDER_API_KEY` | API key generated in Control Center, with the Network/Policies/Reports/Incidents/Quarantine areas selected. |
| `BITDEFENDER_ACCESS_URL` | The account's Control Center Access URL (e.g. `https://cloud.gravityzone.bitdefender.com`). |
| `MCP_TRANSPORT` | `stdio` (default) or `http`. |
| `AUTH_MODE` | `env` (default, reads the two vars above) or `gateway` (credentials arrive per-request via the `X-Bitdefender-Api-Key` / `X-Bitdefender-Access-Url` headers, injected by the Conduit gateway). |
| `CONDUIT_S2S_SECRET` | When set, the HTTP transport requires a valid `X-Gateway-S2S` header (Conduit sidecar auth) on every `/mcp` request. |
| `LOG_LEVEL` | `debug` \| `info` (default) \| `warn` \| `error`. |
### Request limits
- `BITDEFENDER_MAX_UPSTREAM_BYTES` caps each GravityZone response at 16 MiB (16777216 bytes) by default, enforced while streaming before JSON parsing. Positive values are capped at 128 MiB (134217728 bytes); missing, blank, invalid, or non-positive values fall back to the default.
- HTTP request bodies are capped at 256 KiB (262144 bytes). After the `X-Gateway-S2S` check passes, a `Content-Length` above the cap returns 413 with a JSON-RPC error; bodies without `Content-Length` are capped by the MCP SDK transport. Unauthenticated requests still get 401 first.
- `tools/call` arguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return an `isError` tool result and are never dispatched.
These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).
## Tools
### Network - endpoint/network inventory
- `bitdefender_list_endpoints` - list managed/unmanaged endpoints (name, FQDN, IP, MACs, group, agent flags), optionally scoped and filtered.
- `bitdefender_get_endpoint` - full detail for one managed endpoint (agent version, license status, scan/update status).
- `bitdefender_list_custom_groups` - list the child groups under a Network Inventory group.
- `bitdefender_list_network_inventory` - list inventory items (groups, computers, VMs, EC2 instances) with per-type filtering.
- `bitdefender_list_scan_tasks` - list previously created on-demand scan tasks and their status.
### Policies
- `bitdefender_list_policies` - list security policies available to the account.
- `bitdefender_get_policy` - get full settings for one security policy.
### Incidents
- `bitdefender_list_blocklist_items` - list file hashes present in the account's Blocklist.
- `bitdefender_list_incidents` - list EDR/XDR incidents (status, priority, main action, timestamps), filterable by endpoint, status, priority, type and date. Calls `getIncidentsList` on **Incidents API v1.2** (`<accessUrl>/v1.2/jsonrpc/incidents`); needs a license that includes incidents.
- `bitdefender_get_incident` - full detail for one incident (severity, attack types, affected computer, nodes, alerts, MITRE tags). Calls `getIncident` on Incidents API v1.2.
### Quarantine
- `bitdefender_list_quarantine_items` - files quarantined on computers and VMs (threat name, path, SHA256, endpoint, date), for one endpoint or the whole network. Calls `getQuarantineItemsList` on `<accessUrl>/v1.0/jsonrpc/quarantine/computers`. The Exchange quarantine service is not called.
### Reports
- `bitdefender_list_reports` - list scheduled/instant reports configured on the account.
- `bitdefender_get_report_download_links` - check download readiness and get a report's download URL(s).
## Scope
**This is a deliberately narrow, read-only surface: exactly 13 of GravityZone's `getXxx`/`listXxx` methods across the Network, Policies, Incidents, Quarantine, and Reports APIs.** Every tool is classified `isAdmin: true` in the Conduit gateway - GravityZone is an endpoint-protection product, so every read this connector exposes (endpoint IP/MAC/hostname inventory, security policy settings, malware-hash blocklist entries, security posture reports) is security/PII-adjacent by construction. No mutating (`create`/`update`/`delete`/`move`/`set`/`add`/`remove`) method is implemented, by design, not by oversight:
**Hard-excluded (Network API) - never implemented:**
- `createCustomGroup`, `deleteCustomGroup`, `moveCustomGroup` - group provisioning/mutation.
- `moveEndpoints`, `deleteEndpoint` - endpoint mutation/removal.
- `createScanTask` - dispatches a real on-demand scan to a real managed endpoint. `bitdefender_list_scan_tasks` (read) stays; this does not.
- `setEndpointLabel` - endpoint mutation.
**Hard-excluded (Incidents API) - never implemented:**
- `addToBlocklist`, `removeFromBlocklist` - Blocklist mutation. `bitdefender_list_blocklist_items` (read) stays; these do not.
- `createIsolateEndpointTask`, `createRestoreEndpointFromIsolationTask` - genuine remote-response actions that isolate/restore a real managed endpoint from the network.
- `changeIncidentStatus`, `changeIncidentPriority`, `assignIncident`, `updateIncidentNote` - incident triage mutation. `bitdefender_list_incidents` / `bitdefender_get_incident` (read) stay; these do not.
- `createResponseAction`, `startYaraScan`, `createCustomRule`, `updateCustomRule`, `deleteCustomRule` - response actions and detection-rule changes.
**Hard-excluded (Quarantine API) - never implemented:**
- `createRemoveQuarantineItemTask`, `createRestoreQuarantineItemTask` (and their Exchange equivalents), `createEmptyQuarantineTask`, `createAddFileToQuarantineTask`, and `createReleaseQuarantineExchangeItemTask` - write methods that empty quarantine, add, delete, or release a quarantined file on a real endpoint. `bitdefender_list_quarantine_items` (read) stays; these do not.
**Hard-excluded (Reports API) - never implemented:**
- `createReport` - creates a new scheduled/instant report definition.
- `deleteReport` - deletes a report definition.
**Out of scope entirely (not requested, not implemented):** the Companies, Licensing, Accounts, Packages, Integrations, and Push APIs. Push (`setPushEventSettings`) would stream events to a receiver, but configuring it is itself a write, so detections are read here by pulling incidents and quarantine instead.
They can be added as a follow-up if there's demand, after a deliberate scope decision - not by default.
### Credential scope
**Two-tier confidence split**, per this catalog's convention for a claim about what a credential can and cannot reach:
- **STRUCTURALLY VERIFIED** - this connector's own code never calls a mutating JSON-RPC method: confirmed against `client.ts`/`tools/*.ts`, only the 13 documented `getXxx`/`listXxx` methods listed under [Tools](#tools) are ever sent, no passthrough/arbitrary-method call exists anywhere in `src/`. This connector is read-only **by construction**.
- **VENDOR-DOCUMENTED, AND THE FINDING RUNS THE OTHER WAY** - GravityZone's own API-key generation UI (Control Center -> My Account -> API keys) only gates access **per API area** (Network/Policies/Reports/Incidents/...), confirmed against Bitdefender's official API Guide (Getting Started section 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"*). There is **no documented per-method or read/write permission flag**. A key with the Network area enabled can call `getEndpointsList` (read) **and** `moveEndpoints`/`deleteEndpoint`/`createScanTask` (write) - the same area, the same permission checkbox, no finer-grained scoping exists on Bitdefender's side. **This connector's read-only posture is enforced entirely by its own code, not by any narrower credential scope GravityZone itself offers** - the same posture this catalog's other security-product connectors (Cork, CyberQP, Cisco Duo) already document for their own admin-tier classification, stated once here for the credential-scope question specifically.
## Development
```bash
npm install
npm run build
npm test
npm run lint # tsc --noEmit
```
## Docker
```bash
docker build -t bitdefender-mcp .
docker run -p 8080:8080 -e BITDEFENDER_API_KEY=... -e BITDEFENDER_ACCESS_URL=... bitdefender-mcp
```
TDQS
Scored across 13 tools
Each tool has a clear resource+action target, and the list/get pairs (incidents, policies, endpoints) are unambiguous. The only mild overlap is the endpoints / network_inventory / custom_groups triangle, but the descriptions explicitly state the difference (network_inventory returns group nodes and supports type filtering, custom_groups returns a plain array).
All 13 tools follow a uniform bitdefender_<verb>_<noun> snake_case pattern, with verbs consistently drawn from list/get. No camelCase mixing, no vague verbs, and the server prefix is applied uniformly.
13 tools sits squarely in the well-scoped range for a security-console API surface. Each tool maps to a distinct GravityZone resource or report artifact, and no tool looks redundant.
The read-only scope is explicit, so the absence of create/update/delete is by design rather than a gap, and the main resources all have list+get coverage. Minor gaps remain: quarantine items, blocklist items and scan tasks have list but no detail-retrieval counterpart, and there is no account/license summary tool.