sophos-central-mcp-server 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,13 @@
-# Sophos Central MCP Server
+# Sophos Fusion MCP Server (formerly Sophos Central)
 
-MCP (Model Context Protocol) server for interacting with Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing. **288 tools** covering 20 Sophos API namespaces. Install it as a Claude Desktop extension (`.mcpb`), run it with npx, or host it yourself over streamable HTTP.
+> **Unofficial project, not from Sophos.** This is a personal project by an individual. It is
+> not an official Sophos product and it is not built, endorsed, supported, or warranted by
+> Sophos. It calls the public Sophos APIs using credentials you supply. Use it at your own
+> risk, and raise problems as issues on this repository rather than with Sophos support.
+
+MCP (Model Context Protocol) server for the Sophos Fusion and Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing. **310 tools** covering 22 Sophos API namespaces: the Sophos Central REST APIs plus the Sophos Fusion GraphQL APIs (`sophos_fusion_*`). Install it as a Claude Desktop extension (`.mcpb`), run it with npx, or host it yourself over streamable HTTP.
+
+The npm package, the `.mcpb` bundle and the binaries keep the `sophos-central-mcp-server` name so existing installs update in place.
 
 ## Prerequisites
 
@@ -8,7 +15,7 @@ You need these before any of the install options below.
 
 ### Sophos Central API credentials
 
-Every install method needs a Client ID and Client Secret. The credential type decides what the server can see:
+Every install method needs a Client ID and Client Secret. The same credential authorises both the Sophos Central REST tools and the Sophos Fusion GraphQL tools; there is no second credential. The credential type decides what the server can see:
 
 - **Tenant-level**: In Sophos Central, go to **Settings > API Credentials Management** and create a new credential. The server operates on that one tenant.
 - **Partner-level**: In the Sophos Partner Dashboard, create API credentials under **Settings > API Credentials**. The server can query every tenant the partner manages.
@@ -32,13 +39,15 @@ Pick one:
 
 The `.mcpb` file is an [MCP Bundle](https://github.com/modelcontextprotocol/mcpb): a zip containing the built server, its production dependencies, and a manifest that tells Claude Desktop how to run it and which settings to ask for. No terminal and no config file edits.
 
-1. Download `sophos-central-mcp-server-<version>.mcpb` from the [latest GitHub release](https://github.com/Aaronjacobs000/sophos-central-mcp/releases/latest).
+1. Download `sophos-central-mcp-server-<version>.mcpb` from the [latest GitHub release](https://github.com/Aaronjacobs000/sophos-mcp/releases/latest).
 2. Open the file with Claude Desktop. Double-clicking it works on macOS and Windows. You can also go to **Settings > Extensions > Advanced settings**, find the **Extension Developer** section, click **Install Extension...** and pick the file.
 3. Claude Desktop shows the extension details and asks for your **Sophos Central Client ID** and **Client Secret**. Both fields are marked sensitive in the manifest, so Claude Desktop keeps them in the operating system's secure storage instead of a config file.
 4. Click **Install**, make sure the extension is enabled, then start a new chat. The `sophos_*` tools are available straight away.
 
 To update, download the newer `.mcpb` and install it the same way. To remove it, open **Settings > Extensions** and uninstall the extension.
 
+To change the credentials later, open **Settings > Extensions** and click this extension. The **Sophos Central Client ID** and **Client Secret** fields are editable there. They are stored in the operating system's secure storage and show masked, so you replace a value rather than read the old one back. The server reads them at startup, so toggle the extension off and on, or restart Claude Desktop, if a change does not take effect.
+
 The bundle runs the server in stdio mode and sets `TRANSPORT=stdio` for you. Which tools you get depends on the credential type, exactly as with the other install options: partner and organisation credentials unlock the cross-tenant tools, tenant credentials do not.
 
 ### Option 2: Claude Code
@@ -78,8 +87,8 @@ npm install -g sophos-central-mcp-server
 **Or from source:**
 
 ```bash
-git clone https://github.com/Aaronjacobs000/sophos-central-mcp.git
-cd sophos-central-mcp
+git clone https://github.com/Aaronjacobs000/sophos-mcp.git
+cd sophos-mcp
 npm install
 npm run build
 ```
@@ -100,7 +109,7 @@ sophos-central-mcp      # global npm install
 npm start               # from a source checkout
 ```
 
-With `TRANSPORT=http` (the default) the server listens on `http://127.0.0.1:3100/mcp` and answers `GET /health` with `{"status":"ok"}`. The MCP endpoint is stateless: every request gets a fresh transport. Point any streamable HTTP client at it, for example Claude Code:
+With `TRANSPORT=http` (the default) the server listens on `http://127.0.0.1:3100/mcp` (`MCP_HTTP_HOST` and `PORT` change that) and answers `GET /health` with `{"status":"ok","server":"sophos-central-mcp-server"}`. The MCP endpoint is stateless: every request gets a fresh server and transport, so concurrent tool calls work. Point any streamable HTTP client at it, for example Claude Code:
 
 ```bash
 claude mcp add --transport http sophos-central http://127.0.0.1:3100/mcp
@@ -108,7 +117,31 @@ claude mcp add --transport http sophos-central http://127.0.0.1:3100/mcp
 
 With `TRANSPORT=stdio` the server speaks MCP over stdin/stdout and is meant to be spawned by the client, which is what Options 1 and 2 do for you.
 
-The HTTP server binds to `127.0.0.1` only and has no authentication of its own. If it needs to be reachable from another host, put it behind something that adds TLS and auth (an SSH tunnel or an authenticating reverse proxy) rather than changing the bind address.
+By default the HTTP server binds to `127.0.0.1` and has no authentication. It refuses any request with a browser `Origin` other than `localhost`, `127.0.0.1`, `[::1]` or one listed in `MCP_ALLOWED_ORIGINS`, so a web page cannot drive it by cross-site POST or DNS rebinding. MCP clients that are not browsers send no `Origin`, so this does not affect them, on this machine or another.
+
+### Using it from other machines
+
+To let agents on other machines use the server:
+
+1. Make a token, for example `openssl rand -hex 32`.
+2. Start the server listening on the network, with the token:
+
+   ```bash
+   MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_TOKEN=<token> TRANSPORT=http npm start
+   ```
+
+   `0.0.0.0` listens on every interface. To listen on one only, use that interface's address, such as a LAN or Tailscale IP.
+3. Point each client at `http://<server>:3100/mcp` and have it send `Authorization: Bearer <token>`. In Claude Code:
+
+   ```bash
+   claude mcp add --transport http sophos-central http://<server>:3100/mcp --header "Authorization: Bearer <token>"
+   ```
+
+Every `/mcp` request without the right token gets a 401. `/health` stays open. Without a token, anyone who can reach the port can use every tool with your Sophos credentials, and the server prints a warning at startup saying so.
+
+Plain HTTP sends the token and tool results in clear text. On any network you don't fully trust, encrypt it: TLS through a reverse proxy (Caddy or nginx, say), or reach the server over Tailscale.
+
+A browser based MCP client on another machine sends an `Origin` and is refused until you add that origin to `MCP_ALLOWED_ORIGINS`. Agents and CLI clients need nothing there.
 
 ### Build the .mcpb yourself (maintainers)
 
@@ -129,6 +162,26 @@ The script:
 
 `build/` and `release/` are git-ignored. To inspect a bundle without installing it, `npx mcpb info release/<file>.mcpb` prints its size and signature state, and `npx mcpb unpack release/<file>.mcpb <dir>` extracts it. Signing is optional; `npx mcpb sign --self-signed release/<file>.mcpb` adds a self-signed signature if you want one.
 
+### Tests (maintainers)
+
+```bash
+npm test
+```
+
+Builds, then runs the `node:test` suites in `test/` with `fetch` stubbed: the Fusion GraphQL transport (including the HTTP 200 with `errors` case), the QL builder, the reference-data cache, and the path-keyed retry for the intermittent case-write fault, the migration guard, a registration check that lists all 310 tools over an in-memory transport and checks the descriptions for the measured warnings, the `SOPHOS_FUSION_GRAPHQL_URL` check, and the HTTP transport (Origin guard, bearer token, listen address, concurrent calls) run against an in-memory Sophos. Nothing in `npm test` reaches Sophos.
+
+To exercise the Fusion tools against a live tenant, put credentials in `.env` (or export them) and run:
+
+```bash
+node scripts/fusion-smoke.mjs                  # read-only, tenant credential
+node scripts/fusion-smoke.mjs <tenant-id>      # read-only, partner or organisation credential
+node scripts/fusion-smoke.mjs --write          # plus the Fusion write tools on one new case
+node scripts/fusion-smoke.mjs --write-classic  # plus the Classic case tools on one new case
+node scripts/fusion-smoke.mjs --all            # everything
+```
+
+It spawns the built server over stdio and calls the tools through an MCP client, so what runs is what a host runs. Read-only mode covers the reference data, the case list with filter and cursor variants, the newest case by short ID, its evidence, summary, comments and files, the detection search, the not-found and legacy-ID refusals, and the Classic side: on a migrated tenant the migration refusal, otherwise the six Classic read tools. `--write` creates one case titled `MCP smoke test <timestamp>` (managed_by CUSTOMER), exercises comment add, edit and delete with the mention read-back, link create, update and delete, tag merge and replace, evidence add and remove_all, file upload, list and soft delete, the verdict clear on reopen, the one way door on new and the closed-case freeze, then closes it with a verdict and archives it (Fusion has no delete). `--write-classic` creates, updates and deletes one Classic case; the Cases API requires an assignee and a detection that still exists, so set `SMOKE_CLASSIC_ASSIGNEE` (a tenant admin email) and, if needed, `SMOKE_CLASSIC_DETECTION_ID` (a recent detection ID). Every write is listed at the end. Existing cases are never modified.
+
 **Cutting a release:** bump `version` in `package.json`, run `npm run build:mcpb`, commit `package.json`, `package-lock.json`, and `manifest.json`, tag, and attach the `.mcpb` from `release/` to the GitHub release. Publish to npm as before so the Claude Code and self-hosted options pick up the same version.
 
 ## Features
@@ -141,7 +194,9 @@ The script:
 - **Rate limit handling**: Retry with backoff on 429 responses
 - **Dual transport**: stdio (Claude Desktop, Claude Code, and the `.mcpb` bundle) or streamable HTTP (self-hosted)
 - **One-click install**: Ships as a Claude Desktop extension (`.mcpb`) with credentials held in the OS secure store
-- **Full API coverage**: 288 tools across endpoints, alerts, policies, firewalls, web filtering, licensing, audit events, email, mobile, XDR, cases, SIEM, and more
+- **Two API generations**: the Sophos Central REST APIs and the Sophos Fusion GraphQL APIs on one credential, with `sophos_fusion_*` tools for the GraphQL side
+- **Migration aware**: the Classic case and detection tools refuse a tenant that has moved to Sophos Fusion and name the `sophos_fusion_*` tool to use instead
+- **Full API coverage**: 310 tools across endpoints, alerts, policies, firewalls, web filtering, licensing, audit events, email, mobile, XDR, cases, SIEM, and more
 
 ## Screenshots
 
@@ -174,10 +229,26 @@ TRANSPORT=http
 | `SOPHOS_CLIENT_SECRET` | Yes | - | OAuth2 client secret |
 | `PORT` | No | 3100 | HTTP server port |
 | `TRANSPORT` | No | http | `http` for streamable HTTP, `stdio` for subprocess mode |
+| `MCP_HTTP_HOST` | No | 127.0.0.1 | Address the HTTP server binds to. `0.0.0.0` for every interface, or one interface's IP. See [Using it from other machines](#using-it-from-other-machines) |
+| `MCP_HTTP_TOKEN` | No | - | When set, every `/mcp` request needs `Authorization: Bearer <token>`. `/health` stays open. Set it whenever `MCP_HTTP_HOST` is not loopback |
+| `MCP_ALLOWED_ORIGINS` | No | - | Comma separated browser origins (`https://host:port`) allowed besides localhost ones. Only browser based clients need this |
 | `CHARACTER_LIMIT` | No | 50000 | Maximum characters per tool response before truncation (minimum 10000) |
+| `SOPHOS_FUSION_GRAPHQL_URL` | No | `https://api.taegis.sophos.com/graphql` | Sophos Fusion GraphQL endpoint. Override when the Fusion branded hostnames ship. Must be `https` on a `sophos.com` host, since the bearer token goes to it; the server refuses to start otherwise |
+| `SOPHOS_CLASSIC_MIGRATION_CHECK` | No | on | `off` skips the migration check on the Classic case and detection tools (they then run for every tenant) |
 
 ## Tools
 
+### Two API generations
+
+The server speaks to two Sophos API generations on one credential:
+
+- **Sophos Central REST APIs** (retained). Every tool without the `fusion` prefix. Regional hosts, discovered from `/whoami/v1`.
+- **Sophos Fusion GraphQL APIs** (new, 18/09/2026). The `sophos_fusion_*` tools. One endpoint, `https://api.taegis.sophos.com/graphql`, same token, same `X-Tenant-ID` header. Filters are written in Fusion Query Language (QL). Case types, statuses and verdicts are tenant reference data resolved to IDs at runtime, case severity is an integer (2 to 10), and assignees are Subject IDs, not email addresses. A GraphQL failure arrives as HTTP 200 with an `errors` array; the client treats that as an error, and a partial response (data plus errors) is returned with a `warnings` list rather than as a clean result.
+
+Sophos is moving tenants to Fusion over the coming months (the [upgrade centre](https://community.sophos.com/sophos-xdr/sophos-xdr-mdr-expansion/upgrade-center) announces each account's slot). This is a point in time change, not a fallback: once a tenant has moved, the Classic Cases and Detections REST APIs reference the pre-migration Sophos Central objects, so their answers are wrong rather than stale. The Classic tools therefore check which world a tenant is in before every call, using the Fusion case reference data (a tenant that has not moved gets an empty case type list), and refuse a migrated tenant with a message naming the `sophos_fusion_*` tool to use. For a tenant that has not moved they stay correct and carry no deprecation label. Fusion holds a separate case set (a UUID plus a `CSE#####` short ID) and neither ID form resolves in the other API. Live Discover and XDR Query are unaffected. Data Lake search over GraphQL has not shipped (Sophos says October 2026), so `sophos_run_xdr_query` stays on the SQL XDR Query API. Fusion tools for events, threat timeline and live endpoint search are planned.
+
+Two Fusion case writes, `createCase` and `addEvidenceToCase`, fail 74% of the time with `not allowed` on `partnerPreferences` from `investigations-v2`. It is an intermittent downstream fault, not authorisation: the identical call succeeds on retry, and `updateCase` does not carry the fault at all. Measured on a live tenant 22/09/2026: 111 faults in 150 calls, drifting from 60% to 85% across four samples six minutes apart. The client retries a call whose first error path is `partnerPreferences`, and only that, up to 20 times with a short backoff, which leaves about 1 call in 410 failing at the measured rate and about 1 in 26 at the worst rate observed; an error naming the operation in its path is a real input or permission error and surfaces at once.
+
 ### Partner & Organisation (18 tools)
 
 > These tools are only available with **partner or organisation-level** credentials. They operate across all managed tenants.
@@ -369,11 +440,13 @@ TRANSPORT=http
 
 ### Cases (9 tools)
 
+Sophos Central Cases REST API. Correct for a tenant that has not moved to Fusion, and the only way to read its legacy cases (IDs like `1-598868`). Refused for a tenant that has moved, with a pointer to the `sophos_fusion_*` tool to use (see "Two API generations").
+
 | Tool | Description |
 |------|-------------|
 | `sophos_list_cases` | List investigation cases |
 | `sophos_get_case` | Get full case details |
-| `sophos_create_case` | Create a new investigation case |
+| `sophos_create_case` | Create a new investigation case (the API requires an assignee and a detection that still exists) |
 | `sophos_update_case` | Update case status, severity, assignee |
 | `sophos_delete_case` | Delete a case |
 | `sophos_list_case_detections` | List detections linked to a case |
@@ -381,9 +454,47 @@ TRANSPORT=http
 | `sophos_list_case_impacted_entities` | List impacted entities for a case |
 | `sophos_get_case_mitre_summary` | Get MITRE ATT&CK breakdown for a case |
 
+### Fusion Cases (21 tools)
+
+Sophos Fusion Cases GraphQL API v2. Case IDs are UUIDs; short IDs (`CSE00001`) are accepted and resolved. Severity is 2 informational, 4 low, 6 medium, 8 high, 10 critical. Detection severity inside the case summary is a 0 to 1 float, a different scale from both the case severity and the Classic REST 0 to 10 detection severity; none of them convert. There is no delete: close the case (with a verdict when its type needs one), then archive it.
+
+`managed_by` is required on create and decides who works the case: `PROVIDER` hands it to Sophos MDR, `CUSTOMER` keeps it self managed. It cannot be changed afterwards, and a case created without it is unclaimed, so the tool never omits it. Detection and event IDs on the evidence tools are six section resource names (`alert://priv:event-filter:123456:1789526908712:<uuid>`), which `sophos_fusion_search_detections` returns. Evidence writes are queued jobs that land category by category (an add showed after about 5 seconds, a three category removal took about 25 seconds), so read the evidence back with a poll; adding a detection also attaches its linked asset and events, and removing it does not retract them (`remove_all` does). Comment @mentions (`@authorized_contacts`, `@customer`, `@sophos`) fire wherever they appear, including in prose, and an unrecognised token is dropped silently, so the comment tools read the stored mentions back. Tags are merged on update unless `replace_tags` is set. File deletion is soft. Split and merge are irreversible and need a confirmation argument.
+
+| Tool | Description |
+|------|-------------|
+| `sophos_fusion_list_cases` | List cases with QL filters (type, status, verdict resolved to IDs), offset or cursor pagination |
+| `sophos_fusion_get_case` | Full case detail including key findings, verdict, links and processing status |
+| `sophos_fusion_get_case_evidence` | Detection, event, asset and saved-search source IDs attached to a case |
+| `sophos_fusion_get_case_summary` | Case plus its detections resolved in one batched call and a MITRE ATT&CK roll-up |
+| `sophos_fusion_list_case_reference_data` | The tenant's case types, primary statuses and verdicts (15 minute cache) |
+| `sophos_fusion_create_case` | Create a case: required managed_by, type and status by name or ID, integer severity, Markdown key findings, genesis evidence |
+| `sophos_fusion_update_case` | Update fields, merge or replace tags, close with a verdict, reopen (verdict cleared), archive or unarchive; refuses frozen fields on a closed case rather than reopening it |
+| `sophos_fusion_split_case` | Move named evidence into a new case (irreversible, confirm_split) |
+| `sophos_fusion_merge_cases` | Merge source cases into a target and close them (asynchronous, irreversible, confirm_merge) |
+| `sophos_fusion_list_case_comments` | List comments (raw author IDs, resolved mentions, read state) |
+| `sophos_fusion_add_case_comment` | Add a comment and report which @mentions actually fired |
+| `sophos_fusion_update_case_comment` | Edit a comment or mark it read |
+| `sophos_fusion_delete_case_comment` | Delete a comment |
+| `sophos_fusion_add_case_evidence` | Attach detections, events, hosts or saved searches (asynchronous, RNs checked) |
+| `sophos_fusion_remove_case_evidence` | Detach evidence by source ID, or everything with remove_all (asynchronous) |
+| `sophos_fusion_list_case_files` | List a case's files (deleted hidden by default, download URLs on request) |
+| `sophos_fusion_upload_case_file` | Attach a file: register, PUT to the presigned URL, poll to UPLOADED |
+| `sophos_fusion_delete_case_file` | Soft delete a file |
+| `sophos_fusion_create_case_link` | Attach an external link (ServiceNow ticket, report) |
+| `sophos_fusion_update_case_link` | Change a link's URL, title, type or reference |
+| `sophos_fusion_delete_case_link` | Remove a link |
+
+### Fusion Detections (1 tool)
+
+Sophos Fusion Detections GraphQL API v2. One QL search replaces the Classic run, poll, results triple. Source keyword `alert`; working example `from alert severity >= 0.1 EARLIEST=-90d`. Severity is a 0 to 1 float.
+
+| Tool | Description |
+|------|-------------|
+| `sophos_fusion_search_detections` | Search detections with QL; returns the resource-name IDs the case evidence tools take |
+
 ### Detections (6 tools)
 
-Async API — start a query, poll for completion, then fetch results.
+Sophos Central Detections REST API, async: start a query, poll for completion, then fetch results. Refused for a tenant that has moved to Fusion, with a pointer to `sophos_fusion_search_detections`.
 
 | Tool | Description |
 |------|-------------|
@@ -403,7 +514,7 @@ Async API — start a query, poll for completion, then fetch results.
 
 ### XDR Data Lake (9 tools)
 
-Async API — submit SQL queries against historical telemetry.
+Async API: submit SQL queries against historical telemetry.
 
 | Tool | Description |
 |------|-------------|
@@ -419,7 +530,7 @@ Async API — submit SQL queries against historical telemetry.
 
 ### Live Discover (4 tools)
 
-Async API — run OSquery SQL on live endpoints. Rate limited to 10 runs/minute, 500/day.
+Async API: run OSquery SQL on live endpoints. Rate limited to 10 runs/minute, 500/day.
 
 | Tool | Description |
 |------|-------------|
@@ -652,27 +763,40 @@ Register tools based on identity type
     |
     v
 Per tool call: resolve tenant -> regional API host -> execute request
+Per sophos_fusion_* call: resolve tenant -> POST api.taegis.sophos.com/graphql -> inspect data and errors
 ```
 
 ### Key decisions
 
 - **Dynamic tool registration**: Only tools valid for the caller type are exposed to the LLM
 - **Explicit tenant context**: Partner/org callers must specify `tenant_id` to prevent cross-tenant accidents
-- **Stateless HTTP**: Each MCP request creates a fresh transport instance (no session affinity)
-- **Localhost binding**: HTTP server binds to `127.0.0.1` only
+- **Stateless HTTP**: Each MCP request creates a fresh server and transport instance (no session affinity)
+- **Localhost by default**: HTTP server binds to `127.0.0.1` unless `MCP_HTTP_HOST` says otherwise
 
 ## Project Structure
 
 ```
 src/
 ├── index.ts                     # Entry point, server bootstrap
+├── http-guard.ts                # HTTP transport: refuse foreign browser Origins, optional bearer token
 ├── config/config.ts             # Environment config
 ├── auth/token-manager.ts        # OAuth2 token lifecycle
 ├── client/
-│   ├── sophos-client.ts         # HTTP client with region routing
+│   ├── sophos-client.ts         # REST client with region routing (Sophos Central)
+│   ├── fusion-client.ts         # GraphQL client (Sophos Fusion), 200-with-errors handling, path-keyed retry
 │   └── tenant-resolver.ts       # Whoami + tenant cache
+├── fusion/
+│   ├── queries/cases.ts         # Cases v2 GraphQL documents
+│   ├── queries/detections.ts    # Detections v2 documents: the case summary lookup and the QL search
+│   ├── case-reference-data.ts   # Per-tenant cache of case types, statuses, verdicts
+│   ├── cases-ql.ts              # QL builder for the cases search
+│   ├── format.ts                # Severity scales, timestamps, ID checks, mentions, tags, detection rows
+│   ├── migration.ts             # Has this tenant moved to Fusion? Gates the Classic case and detection tools
+│   └── types.ts                 # Fusion response types
 ├── tools/
 │   ├── helpers.ts               # Shared response formatting
+│   ├── fusion-cases.ts          # Sophos Fusion cases (GraphQL)
+│   ├── fusion-detections.ts     # Sophos Fusion detection search (GraphQL)
 │   ├── tenants.ts               # Tenant listing (partner/org only)
 │   ├── partner.ts               # Partner admin, roles, billing (partner/org only)
 │   ├── alerts.ts                # Alert list, get, acknowledge, search
@@ -700,15 +824,16 @@ src/
 └── types/sophos.ts              # Sophos API response types
 ```
 
-Packaging files at the repo root: `manifest.json` (MCPB manifest, regenerated by the build), `scripts/build-mcpb.mjs` (bundle builder), and `.mcpbignore` (extra exclusions applied when packing).
+Packaging files at the repo root: `manifest.json` (MCPB manifest, regenerated by the build), `scripts/build-mcpb.mjs` (bundle builder), and `.mcpbignore` (extra exclusions applied when packing). `schemas/fusion/` holds the five Fusion GraphQL schemas as downloaded from `https://developer.sophos.com/assets/graphql/<api>.graphql` on 21/09/2026, unmodified, for reference and for diffing when Sophos changes them. `test/` holds the `node:test` suites and `scripts/fusion-smoke.mjs` the live check.
 
 ## Security
 
 - Credentials are read from environment variables only, never logged
 - JWT tokens are held in memory with automatic refresh
-- HTTP server binds to `127.0.0.1` (localhost only)
+- HTTP server binds to `127.0.0.1` by default and refuses requests from a browser `Origin` that is not localhost or listed in `MCP_ALLOWED_ORIGINS`. If `MCP_HTTP_HOST` opens it to the network, set `MCP_HTTP_TOKEN` and put TLS in front (a reverse proxy or Tailscale)
 - Write actions have `destructiveHint` annotations so clients can warn users
 - Partner/org callers require explicit `tenant_id` on every call
+- The REST client refuses a request path where an ID argument carries a `.` or `..` segment (encoded too), `?`, `#`, a backslash, an encoded `/` or a control character, so a crafted ID cannot redirect a call to another resource
 - With the `.mcpb` install, Claude Desktop holds the credentials in the OS secure store (they are `sensitive` in `manifest.json`) and hands them to the server as environment variables when it starts the process
 
 ## License

package/dist/client/fusion-client.d.ts

@@ -0,0 +1,132 @@
+/**
+ * GraphQL client for the Sophos Fusion APIs (Cases v2, Detections v2, Threat
+ * Timeline v2, Events v1, Live Endpoint Search v1). Sits beside SophosClient,
+ * which keeps serving the Sophos Central REST APIs.
+ *
+ * One endpoint for every tenant, no regional host lookup. Auth is unchanged:
+ * the same bearer token from TokenManager and the same X-Tenant-ID header the
+ * REST client sends.
+ *
+ * The rule that shapes this file: a GraphQL-layer failure comes back as HTTP
+ * 200 with an `errors` array beside `data`. A 200 is not success until the
+ * body has been read. Transport failures (expired token, 429, 5xx) use the
+ * usual non-2xx status and the standard Sophos error object, and those are
+ * retried the same way SophosClient retries them. GraphQL-layer errors are
+ * not retried, with one measured exception: the intermittent
+ * partnerPreferences fault on the case write path, which is keyed on the
+ * error path and bounded (see FusionGraphQLError.isTransientPartnerPreferences).
+ */
+import type { TokenManager } from "../auth/token-manager.js";
+/** One entry of a GraphQL response `errors` array. */
+export interface GraphQLErrorEntry {
+    message: string;
+    path?: Array<string | number>;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    extensions?: Record<string, unknown>;
+}
+interface GraphQLResponseBody<T> {
+    data?: T | null;
+    errors?: GraphQLErrorEntry[];
+}
+export interface FusionQueryResult<T> {
+    /** The response `data` object. Never null: a response with no usable data throws. */
+    data: T;
+    /**
+     * GraphQL errors that arrived beside usable data (a partial response, for
+     * example a federated field that could not be resolved). Empty on a clean
+     * response. Tools must surface these; they are not silently dropped.
+     */
+    warnings: string[];
+}
+export interface FusionClientOptions {
+    /** GraphQL endpoint. Defaults to SOPHOS_FUSION_GRAPHQL_URL. */
+    url?: string;
+    /** Per-attempt timeout. Default 30 s, matching SophosClient. */
+    timeoutMs?: number;
+    /** Retries after the first attempt for 429, 5xx and network errors. Default 2. */
+    retries?: number;
+    /** Base for the full-jitter exponential backoff. Default 1000 ms. */
+    backoffBaseMs?: number;
+    /**
+     * Total attempts for a call that hits the transient partnerPreferences
+     * fault, which affects createCase and addEvidenceToCase. Measured on a live
+     * tenant 22/09/2026: 111 faults in 150 calls, so 74%, and it drifts, with
+     * four samples over six minutes running 60%, 85%, 72.5% and 80%. Default 20:
+     * about 1 call in 410 fails at the measured 74%, and about 1 in 26 at the
+     * worst rate observed. updateCase does not carry the fault at all, 0 in 30
+     * in the same minute addEvidenceToCase was 24 in 30, so the defect is in the
+     * two resolvers that read partner preferences.
+     */
+    transientAttempts?: number;
+    /** Base for the short full-jitter backoff between those attempts. Default 300 ms, capped at 2 s. */
+    transientBackoffMs?: number;
+}
+/** Thrown when the GraphQL layer returns errors and no usable data. */
+export declare class FusionGraphQLError extends Error {
+    readonly errors: GraphQLErrorEntry[];
+    constructor(message: string, errors: GraphQLErrorEntry[]);
+    /**
+     * True when every error says the record does not exist. Fusion reports an
+     * unknown case ID this way, as HTTP 200 with "record not found" beside a
+     * null root field, rather than as a bare null (live tenant, 21/09/2026).
+     */
+    get notFound(): boolean;
+    /**
+     * True for the intermittent investigations-v2 fault on the case write
+     * path: `errors[0].path[0]` is "partnerPreferences" ("not allowed",
+     * DOWNSTREAM_SERVICE_ERROR). It is not an authorisation failure: the
+     * identical call with identical input succeeds on retry. Keyed on the path
+     * and nothing else, because `extensions.code` is DOWNSTREAM_SERVICE_ERROR
+     * for transient faults, not found and malformed queries alike, while a
+     * genuine input or permission error carries the operation name in the path
+     * (createCase, addEvidenceToCase, tdrusers) with a specific message.
+     */
+    get isTransientPartnerPreferences(): boolean;
+}
+export declare class FusionClient {
+    private tokenManager;
+    private readonly url;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly backoffBaseMs;
+    private readonly transientAttempts;
+    private readonly transientBackoffMs;
+    constructor(tokenManager: TokenManager, options?: FusionClientOptions);
+    /** The endpoint this client posts to. */
+    get endpoint(): string;
+    /**
+     * Run a GraphQL query or mutation for a tenant.
+     *
+     * Returns the `data` object plus any partial-response warnings. Throws
+     * FusionGraphQLError when the response carries errors and no usable data,
+     * and a plain Error for transport failures. The transient partnerPreferences
+     * fault is retried up to transientAttempts times; every other GraphQL-layer
+     * error surfaces at once.
+     */
+    query<T extends object>(tenantId: string, document: string, variables?: Record<string, unknown>): Promise<FusionQueryResult<T>>;
+    /**
+     * PUT raw bytes to a presigned upload URL (case files). The signature lives
+     * in the URL, so no bearer token is sent, and the Content-Type must match
+     * what startCaseFileUpload was told. One attempt, no retry.
+     */
+    putPresigned(url: string, body: Uint8Array, contentType: string): Promise<void>;
+    private executeWithRetry;
+    private sleep;
+}
+/**
+ * Decide what a 200 response actually means.
+ *
+ * - errors present, no usable data: throw with every message joined.
+ * - errors present beside usable data: return the data with the errors as warnings.
+ * - no errors, data present: clean result. A root field that is null with no
+ *   error (for example `case` for an unknown ID) is legitimate and passes
+ *   through for the tool to report.
+ * - no errors, no data: malformed, throw.
+ */
+export declare function interpretGraphQLBody<T extends object>(body: GraphQLResponseBody<T> | null | undefined): FusionQueryResult<T>;
+export declare function formatGraphQLError(error: GraphQLErrorEntry): string;
+export {};
+//# sourceMappingURL=fusion-client.d.ts.map

package/dist/client/fusion-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion-client.d.ts","sourceRoot":"","sources":["../../src/client/fusion-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,mBAAmB,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,qFAAqF;IACrF,IAAI,EAAE,CAAC,CAAC;IACR;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,uEAAuE;AACvE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,EAAE;gBADpC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,iBAAiB,EAAE;IAMtC;;;;OAIG;IACH,IAAI,QAAQ,IAAI,OAAO,CAKtB;IAED;;;;;;;;;OASG;IACH,IAAI,6BAA6B,IAAI,OAAO,CAE3C;CACF;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,YAAY;IARtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAGlC,YAAY,EAAE,YAAY,EAClC,OAAO,GAAE,mBAAwB;IAUnC,yCAAyC;IACzC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;OAQG;IACG,KAAK,CAAC,CAAC,SAAS,MAAM,EAC1B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAsChC;;;;OAIG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA2BvE,gBAAgB;IAqF9B,OAAO,CAAC,KAAK;CAGd;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACnD,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC9C,iBAAiB,CAAC,CAAC,CAAC,CAqBtB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAUnE"}