@pmoses-s1/s1-secops-mcp 1.3.2 → 1.3.3

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 1.3.3 - 2026-08-07
+
+Fixes a user-facing regression in 1.3.2 found by running the live MCP tools
+against a tenant for the first time. **Upgrade from 1.3.2 is recommended.**
+
+### Fixed
+
+- **Every successful `sdl_delete_file` reported an error in 1.3.2.** The delete
+  verification added in 1.3.2 re-reads the file to confirm removal, but the server
+  reports absence as a GraphQL error rather than a null result, so the confirming
+  read threw on exactly the success path. The delete itself always worked; only the
+  reported outcome was wrong. Verified live: three deletes across `/dashboards/`,
+  `/datatables/` and `/logParsers/` all removed their file and all three surfaced
+  as errors.
+- **`sdl_get_file` on a missing path returned a raw GraphQL error** instead of the
+  actionable "this may be udoId-addressed, list it and retry" hint. The hint branch
+  was unreachable because the library threw before returning.
+- **Absence is now detected reliably on both address forms.** The error text differs:
+  a missing name gives "Config file with name X not found.", a missing `udoId` gives
+  the generic "Something went wrong. Please try again...", which is also what a
+  version conflict returns. `configFile` normalises the explicit form and
+  disambiguates the generic one against the file listing, so a deleted dashboard
+  reads as absent while a genuine server error still propagates.
+- **An out-of-range numeric `udoId` is no longer swallowed by the absence path.**
+  Validation now runs before the lookup, so a caller bug surfaces as a caller bug.
+- **A transport error is never read as "file absent".** Absence detection now requires a
+  GraphQL-layer error, so a 404 page or WAF block whose body contains the words "not found"
+  no longer satisfies it. Without this a delete could confirm itself against a file it
+  never checked.
+- **A failing listing during absence disambiguation keeps the original error** instead of
+  replacing it with the listing failure.
+- **The duplicate guard is no longer bypassed by case.** Its namespace test was
+  case-sensitive while its name comparison was not, so `/Dashboards/AI Usage` skipped the
+  guard entirely. Both now share one normaliser.
+- **`v1Query` keeps its backoff.** Restricting status retry to idempotent methods removed it
+  from this read-only POST, which schema discovery iterates once per data source.
+
+### Python client (`sdl-api/scripts/sdl_client.py`)
+
+Brought to parity with the JS client:
+
+- Status retry is restricted to idempotent methods. The Python client was retrying POST
+  mutations, which is the mechanism that duplicates a dashboard on a re-sent write.
+- `Retry-After` is capped at 30s; an unbounded value parked the process.
+- The duplicate guard fails closed on an empty listing.
+- Absence detection, name normalisation and delete verification match the JS behaviour.
+
+### Tests
+
+- `tests/sdl-graphql.test.mjs`: 86 cases, adding the transport-error-is-not-absence case,
+  listing-failure error preservation, the case-variant guard bypass, and `v1Query` retry.
+- `sdl-api/tests/test_client.py`: new. 19 cases over a stubbed session, so the Python client
+  is no longer invisible to CI. Runs in ~0.01s with no network.
+- Live regression through the real MCP stdio protocol: handshake, 26 tools, and full
+  create/read/update/stale-reject/delete/confirm-absent cycles for `/datatables/` and
+  `/dashboards/`, plus the duplicate guard, the notFound hint, and `/automaticLookups`.
+
 ## 1.3.2 - 2026-08-07
 
 Config-file operations move from the legacy REST endpoints to GraphQL. Tool count unchanged at
@@ -38,7 +95,8 @@ Config-file operations move from the legacy REST endpoints to GraphQL. Tool coun
 
 - `udoId` is assigned by namespace, verified live: only `/dashboards/` files get one. `/lookups/`,
   `/datatables/`, `/logParsers/` and `/automaticLookups` are name-addressed with `udoId` null.
-- `expectedVersion` is honoured on `udoId`-addressed writes and ignored on name-addressed ones.
+- `expectedVersion` is enforced on both address forms. A stale value is rejected with
+  "There are conflicting changes in the file." and the stored content is left untouched.
 - A `deleteConfigFile` returning `null` with no `errors` array is success, not failure.
 - The scoped SDL keys (`SDL_CONFIG_READ_KEY` and friends) are retired; the console API token
   covers every SDL operation.
@@ -48,6 +106,7 @@ Config-file operations move from the legacy REST endpoints to GraphQL. Tool coun
 Hardening release from the 2026-07-31 code review. Tool count unchanged at 26.
 
 ### Fixed
+
 - **Missing `Retry-After` header no longer sleeps 0ms before retrying.** `Number(null)` is 0, so `lib/s1.js`, `lib/hec.js`, and `lib/uam-ingest.js` treated an absent header as "wait 0ms" and hammered the backend. All three now use the validated pattern from `lib/sdl.js`: honor the header only when present and parseable as a finite number of seconds (capped at 30s), otherwise fall back to the exponential delay. Numeric headers behave exactly as before.
 - **`uam_set_status` no longer reports silent success.** The `alertTriggerActions` mutation selected only `__typename`, so a skipped or failed action still returned as if it worked (observed live: status unchanged after a "successful" call). The selection now mirrors the full `actions { success failure skip }` shape and the client throws when the backend reports a failure entry, skips the action without a success, or returns an empty actions list (nothing applied, e.g. the filter matched no alert). `uam_add_note` was audited for the same pattern; it already verifies via the returned note list.
 - **LRQ polling tolerates transient poll errors.** A single 429/5xx poll response used to throw and cancel the running query. Transient statuses now keep polling (interval doubles up to 5s) until the existing 5-minute deadline; other 4xx responses remain fatal.
@@ -59,6 +118,7 @@ Hardening release from the 2026-07-31 code review. Tool count unchanged at 26.
 - **SDL `config_read` key chain reordered to least-privilege first** (config_read, config_write, console JWT), matching the Python `SDLClient` the header claims to mirror.
 
 ### Changed
+
 - **Removed dead exports `purpleAiQuery` and `purpleAiInvestigate`** from `lib/s1.js`; their MCP tools were removed 2026-05-03 (browser-session teamToken requirement) and nothing referenced the library functions. Corrected stale doc text that pointed at a nonexistent `uam_set_analyst_verdict` tool: the analyst verdict is set via a raw `alertTriggerActions` mutation with the `analystVerdictUpdate` action through `s1_api_post`.
 - **Deploy docs: credentials.json changes require `systemctl restart`.** SIGHUP reload only re-reads bearer tokens; the installer output and systemd unit comment said reload was enough. `deploy/install.sh` also sets `umask 077` so token/credential files are never world-readable at creation (the explicit `chmod 600` lines remain).
 - **Claude Desktop bridge hardening:** 120s fetch timeout (`AbortSignal.timeout`), notification responses are drained so keep-alive sockets are released, and the URL constant no longer shadows the global `URL` constructor.
@@ -66,6 +126,7 @@ Hardening release from the 2026-07-31 code review. Tool count unchanged at 26.
 - **`const status = response.error ? 200 : 200`** simplified; JSON-RPC errors still return HTTP 200 with an error envelope.
 
 ### Tests
+
 - New `tests/regressions-2026-07-31.test.mjs` (mocked fetch, no network): missing `Retry-After` uses the exponential delay, `uamSetStatus` throws on failure/skip results, inline `?isLegacy=` is honored. Both regression suites are now part of `npm test`.
 - Transport and smoke tests read the expected version from `package.json` instead of a hardcoded string.
 
@@ -74,12 +135,14 @@ Hardening release from the 2026-07-31 code review. Tool count unchanged at 26.
 Correctness release from the 2026-07-29 defect review. Fixes two bugs that produced plausible-but-wrong query results, hardens the SDL auth chain and HTTP retry paths, corrects the HEC `/event` content type, and adds a regression suite. Tool count unchanged at 26. (The Docker bundle image moved to 1.2.4 pinning `S1_MCP_VERSION=1.2.3`; the image tag stays ahead of the npm tag as it has since the split.)
 
 ### Fixed
+
 - **`powerquery_run` no longer collapses a caller-supplied time window.** The old code overwrote BOTH `startTime` and `endTime` with the last-`hours` default whenever either was missing, so a startTime-only call silently ran over the last 24 hours. Each bound now defaults independently. Live A/B: a startTime-only 7.4-day query returned 73,755 events on the fixed server vs 12,911 (the 24h control) on the old one.
 - **`powerquery_run` now reports `matchCount`.** It was read from the top level of the LRQ response and came back `null` on every call; it lives inside the `data` block on current engines.
 - **SDL auth chain falls through on 401/403.** `lib/sdl.js` treated an auth failure on the first configured key as fatal even when a later key (e.g. the console JWT) would work. It now advances through the chain and raises only when exhausted.
 - **HEC `/event` ingestion uses `application/json`,** so per-event `time` backdating is honored instead of the envelope being indexed as opaque text at receive time.
 
 ### Changed
+
 - **Write requests no longer auto-retry on 5xx.** Retry is restricted to idempotent methods (GET/HEAD); read-only POSTs (GraphQL queries, Purple AI launches) opt back in via `allowRetry`. HEC raw ingest no longer retries 5xx (no idempotency key); UAM ingest still retries because `metadata.uid` dedupes.
 - **`Retry-After` parsing hardened:** an HTTP-date value no longer collapses to `sleep(NaN)`; waits are validated and capped at 30s.
 - **`uam_add_note` returns the correct note** (matches by text, tiebreaks on newest `createdAt`) instead of assuming newest-last ordering.
@@ -88,15 +151,18 @@ Correctness release from the 2026-07-29 defect review. Fixes two bugs that produ
 - **`powerquery_schema_discover` escapes single quotes** in the data-source name before building the V1 filter.
 
 ### Tests
+
 - New `tests/regressions-2026-07-29.test.mjs` (mocked fetch, no network): independent time-bound defaults, `matchCount` extraction, SDL 401/403 fall-through, HEC per-endpoint content type, write-vs-read retry semantics.
 
 ## 1.2.2 - 2026-06-13
 
 ### Changed
+
 - **Renamed `ha_archive_workflow` to `ha_delete_workflow`.** The old tool hit `POST /hyper-automate/api/v1/workflows/archive`, which returns HTTP 500 on this tenant. The replacement uses the validated `DELETE /hyper-automate/api/v1/workflows/{id}` endpoint (a soft, recoverable delete equivalent to clicking Delete in the Hyperautomation UI). Scope the call with `accountIds` or `siteIds`; a 404 "Object not found" means the id is not under that scope or is already deleted. Updated `README.md`, the tools-table regenerator, and the smoke test in lockstep.
 - **`powerquery_run` description now documents the `datasource` and `savelookup` capabilities** (querying SentinelOne-managed inventory such as assets/alerts/vulnerabilities/misconfigurations, and persisting a result as a reusable lookup table), pointing at the new `powerquery/references/datasource-command.md`.
 
 ### Notes
+
 - Tool count unchanged at 26 (the Hyperautomation tool was renamed, not added or removed).
 - `SERVER_INFO.version` bumped in lockstep with `package.json` (the drift that forced the 1.2.0 -> 1.2.1 re-release).
 
@@ -105,22 +171,26 @@ Correctness release from the 2026-07-29 defect review. Fixes two bugs that produ
 Supersedes 1.2.0, which was deprecated on npm. The 1.2.0 build shipped with a stale internal `SERVER_INFO.version` of `1.1.0` despite a `1.2.0` package version, so the server announced the wrong version on `initialize`. 1.2.1 is identical in features and corrects the reported runtime version. The content below is unchanged from the 1.2.0 work.
 
 ### Added
+
 - **`hec_ingest` tool**: raw-log/event ingestion into the Singularity Data Lake via the HEC (HTTP Event Collector) endpoint (`/services/collector/raw` and `/services/collector/event`). Supports `parser` (-> `?sourcetype=`), custom `fields` (query params), **required** `scope` (S1-Scope header), gzip compression, and `isParsed` (-> `?isParsed=true`, indexes already-structured JSON with no SDL parser). Replaces the removed `sdl_upload_logs`. Validated live across the full HEC matrix (both endpoints, gzip on/off, parser field extraction, multi-line, batched, reserved-field handling, scope enforcement, isParsed). Grounded in the S-26.1 HEC docs (p.4723-4726).
 
 ### Removed
+
 - **`sdl_upload_logs` tool** plus the underlying SDL `uploadLogs`/`addEvents` library functions and `SDL_LOG_WRITE_KEY` plumbing. SDL raw-log ingestion moves to the HEC path (`hec_ingest`). The `sdl-api` skill is now query + configuration only; the `sdl-log-parser` validation loop uses HEC ingest.
 
 ### Changed
+
 - Tool count unchanged at 26 (removed `sdl_upload_logs`, added `hec_ingest`).
 - Skill docs corrected: scheduled detection rules bind the Target Asset via `entityMappings` ("Entity column mapping"); the full scheduled-rule option set (UI <-> API) is catalogued in `powerquery/references/detection-rules.md`.
 
-
 ## 1.1.0 - 2026-05-28 (rebuilt 2026-05-31)
 
 ### Fixed (rebuild)
+
 - **`s1_api_get` now auto-injects `isLegacy=false` for `/cloud-detection/rules` listings.** Without `isLegacy=false` the S1 API silently omits `queryType="scheduled"` PowerQuery rules from the response; no error, no warning, the response just lies by omission. The handler now guards against this when the caller forgets, and the tool description loudly flags the requirement. This eliminates the "I see zero scheduled detections" failure mode that was producing wrong verdicts when listing Custom Detection rules. Same `1.1.0` version per the rebuild request.
 
 ### Added
+
 - **Streamable HTTP transport.** New `--transport http` mode (default stays `stdio`). Single-endpoint POST `/mcp` per the MCP 2024-11-05 spec, plus `/healthz` for load balancer probes. Implementation is pure `node:http`, no new dependencies.
 - **Per-user bearer token auth.** New `MCP_BEARER_TOKENS_FILE` env var pointing at a `{ "<name>": "<token>" }` JSON file gives each team member a stable name in audit logs and supports rotation. SIGHUP reloads tokens without dropping connections. `MCP_BEARER_TOKENS` env var (comma-separated raw tokens) is a fallback for small or quick-test setups.
 - **Audit logging.** Every authenticated HTTP request emits `[audit] <ts> | <name> | <method> | <param-summary> | <status>` to stderr; systemd captures it via journald.
@@ -137,12 +207,14 @@ Supersedes 1.2.0, which was deprecated on npm. The 1.2.0 build shipped with a st
 - **README auto-regenerator** at `scripts/regen-readme-tools-table.mjs`. `npm run regen:readme` keeps the README table in sync with `ALL_TOOLS`. `npm run regen:readme -- --check` fails when stale (suitable for CI).
 
 ### Fixed
+
 - **README tool table.** Previous count was 19; actual is 26. Auto-generated now.
 - **Header comment in `index.js`.** Previously said 21; updated to 26.
 - **`purple_ai_query`** removed from the documentation. The tool itself was removed 2026-05-03 because the underlying API requires a browser-session `teamToken` that service-account API tokens never obtain. The README, `index.js`, and `docs/mcp-tools.md` no longer reference it.
 - **`uam_set_status` documentation.** Doc previously said valid status values include `CLOSED`. The source enum is `NEW`, `IN_PROGRESS`, `RESOLVED`; doc now matches.
 
 ### Changed
+
 - **Refactored** dispatch out of `index.js` into `lib/server-core.js` so both transports use one code path. `lib/stdio-transport.js` is the extracted stdio loop; `lib/http-transport.js` is new.
 - **package.json**:
   - `version` 1.0.0 → 1.1.0
@@ -150,6 +222,7 @@ Supersedes 1.2.0, which was deprecated on npm. The 1.2.0 build shipped with a st
   - new files included in the npm tarball: `deploy/`, `scripts/`, `CHANGELOG.md`
 
 ### Compatibility
+
 - Default invocation is unchanged: `npx -y @pmoses-s1/s1-secops-mcp` still produces a stdio MCP server with identical behaviour to 1.0.0.
 - Existing `claude_desktop_config.json` and `.mcp.json` configs work without modification.
 - The 26 tools, 2 resources, and 2 prompts are unchanged from the late-1.0.0 line; only the documentation now matches reality.
@@ -157,6 +230,7 @@ Supersedes 1.2.0, which was deprecated on npm. The 1.2.0 build shipped with a st
 ## 1.0.0 - 2026-05-07
 
 Initial public release.
+
 - 19 tools across PowerQuery, S1 Mgmt REST, UAM, SDL API, Hyperautomation.
 - stdio transport only.
 - Credentials via env vars or auto-discovered `credentials.json`.

package/README.md

@@ -43,10 +43,12 @@ See **[deploy/README.md](./deploy/README.md)** for the full deployment walkthrou
 <!-- END AUTO-GENERATED TOOLS TABLE -->
 
 **2 resources:**
+
 - `sentinelone://soc-context`: `CLAUDE.md`, the Principal SOC Analyst operating instructions.
 - `sentinelone://credentials-status`: which credentials are configured and which API surfaces are available.
 
 **2 prompts:**
+
 - `soc_analyst`: embeds `CLAUDE.md` as a system prompt; call at session start.
 - `session_init`: structured init: enumerate sources + triage alerts in parallel.
 
@@ -65,7 +67,7 @@ Add this to `claude_desktop_config.json` (or `.mcp.json` for Claude Code):
   "mcpServers": {
     "s1-secops-mcp": {
       "command": "npx",
-      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.2"],
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.3"],
       "env": {
         "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
         "S1_CONSOLE_API_TOKEN": "eyJ...",
@@ -204,7 +206,7 @@ If neither env var is set, HTTP transport runs **without** authentication and th
 
 Every authenticated HTTP request emits a structured stderr line that systemd captures via journald:
 
-```
+```json
 [audit] 2026-05-28T15:01:22.413Z | alice | tools/call | name=powerquery_run | 200 ok
 [audit] 2026-05-28T15:01:34.221Z | bob   | tools/list | -                  | 200 ok
 [audit] 2026-05-28T17:03:11.221Z | -     | -          | -                  | 401 unauthorized
@@ -434,7 +436,7 @@ The `maxRows` (`powerquery_run`) and `first` (`uam_list_alerts`) parameters are
 
 ## CLI reference
 
-```
+```text
 s1-secops-mcp [options]
 
 OPTIONS
@@ -448,7 +450,7 @@ OPTIONS
 
 ## Architecture
 
-```
+```text
 s1-secops-mcp/
   index.js                    Entry: flag parsing + transport selection
   lib/
@@ -485,7 +487,7 @@ s1-secops-mcp/
 | Purple AI GraphQL | `Authorization: ApiToken <jwt>` | `S1_CONSOLE_API_TOKEN` |
 | UAM GraphQL | `Authorization: ApiToken <jwt>` | `S1_CONSOLE_API_TOKEN` |
 | UAM HEC ingest | `Authorization: Bearer <jwt>` | `S1_CONSOLE_API_TOKEN` |
-| SDL config files (`POST /sdl/v2/graphql`) | `Authorization: Bearer <jwt>`, do not send `s1-scope` (returns 403) | `S1_CONSOLE_API_TOKEN` |
+| SDL config files (`POST /sdl/v2/graphql`) | `Authorization: Bearer <jwt>`, an `s1-scope` header is ignored, not rejected | `S1_CONSOLE_API_TOKEN` |
 
 ## Testing
 

package/deploy/README.md

@@ -21,6 +21,7 @@ bash /tmp/s1-mcp-install.sh --user
 ```
 
 That runs `install.sh --user`, which:
+
 1. Confirms Node 18+ is present (errors out with install hints if not).
 2. Sets up a per-user npm prefix at `~/.npm-global` if one isn't configured.
 3. Installs `@pmoses-s1/s1-secops-mcp` globally for your user.
@@ -56,7 +57,7 @@ Or, equivalently, by package name without the install:
   "mcpServers": {
     "s1-secops-mcp": {
       "command": "npx",
-      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.2"]
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.3"]
     }
   }
 }
@@ -117,11 +118,13 @@ Team members connect from their Claude clients with their own bearer token. Audi
 1. **Provision the VM.** Anything that runs systemd is fine: Ubuntu 22.04 LTS, Debian 12, Rocky/Alma 9, etc.
 
 2. **Install Node 18+.** Pick one:
+
    ```bash
    # Ubuntu / Debian
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs
    ```
+
    ```bash
    # Rocky / Alma
    curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
@@ -129,12 +132,15 @@ Team members connect from their Claude clients with their own bearer token. Audi
    ```
 
 3. **Run the installer in server mode:**
+
    ```bash
    curl -fsSL https://raw.githubusercontent.com/pmoses-s1/claude-skills/main/s1-secops-mcp/deploy/install.sh | sudo bash -s -- --server
    ```
+
    It creates the `mcp` user, drops `/etc/s1-secops-mcp/credentials.json` (placeholder) and `/etc/s1-secops-mcp/bearer-tokens.json` (one freshly-generated admin token, printed once to stdout), installs the systemd unit, and starts the service.
 
 4. **Fill in real SentinelOne credentials:**
+
    ```bash
    sudo vim /etc/s1-secops-mcp/credentials.json
    sudo systemctl reload s1-secops-mcp
@@ -142,15 +148,18 @@ Team members connect from their Claude clients with their own bearer token. Audi
    ```
 
 5. **Put TLS in front with Caddy** (the recommended option):
+
    ```bash
    sudo apt install -y caddy
    sudo cp /usr/lib/node_modules/@pmoses-s1/s1-secops-mcp/deploy/caddy/Caddyfile.example /etc/caddy/Caddyfile
    sudo vim /etc/caddy/Caddyfile   # change mcp.s1.internal to your DNS name
    sudo systemctl reload caddy
    ```
+
    Default Caddyfile uses `tls internal` which signs with Caddy's own CA. Distribute `/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt` to your team for trust, or use `tls <your-email>` with a publicly resolvable hostname for Let's Encrypt.
 
 6. **Add team members.** Generate a token per person and append to the file:
+
    ```bash
    sudo bash -c 'cat > /etc/s1-secops-mcp/bearer-tokens.json' <<EOF
    {
@@ -164,9 +173,11 @@ Team members connect from their Claude clients with their own bearer token. Audi
    sudo chown mcp:mcp /etc/s1-secops-mcp/bearer-tokens.json
    sudo systemctl reload s1-secops-mcp   # SIGHUP, no downtime
    ```
+
    Hand each person their token over a secure channel (1Password, Signal, etc.).
 
 7. **Connect from a Claude client.** Each user adds the server to their config with their personal token:
+
    ```json
    {
      "mcpServers": {
@@ -182,6 +193,7 @@ Team members connect from their Claude clients with their own bearer token. Audi
    ```
 
 8. **Verify end-to-end.** From a team member's machine:
+
    ```bash
    curl -s -X POST https://mcp.s1.internal/mcp \
      -H "Authorization: Bearer $TOKEN" \
@@ -191,6 +203,7 @@ Team members connect from their Claude clients with their own bearer token. Audi
    ```
 
 9. **Watch the audit log.** Every authenticated request is logged with the bearer name, method, and param summary:
+
    ```bash
    sudo journalctl -u s1-secops-mcp -f | grep '\[audit\]'
    # [audit] 2026-05-28T15:01:22.413Z | alice | tools/call | name=powerquery_run | 200 ok
@@ -231,7 +244,7 @@ sudo systemctl restart s1-secops-mcp
 
 The structured audit lines look like:
 
-```
+```json
 [audit] 2026-05-28T15:01:22.413Z | alice | tools/call | name=powerquery_run | 200 ok
 [audit] 2026-05-28T16:42:55.108Z | bob   | tools/list | -                  | 200 ok
 [audit] 2026-05-28T17:03:11.221Z | -     | -          | -                  | 401 unauthorized
@@ -296,7 +309,7 @@ The instance's `*.compute.internal` DNS name (e.g. `ip-172-31-7-227.ap-southeast
 
 If you try to issue a cert for the EC2 public DNS, LE returns:
 
-```
+```text
 HTTP 400 urn:ietf:params:acme:error:rejectedIdentifier
 The ACME server refuses to issue a certificate for this domain name, because it is forbidden by policy
 ```
@@ -363,7 +376,7 @@ Both block the W+X memory mappings V8 needs to JIT JavaScript. Adding them cause
 
 These are supported but not first-class:
 
-- **Docker / docker-compose.** Not shipped in this version. The single-file Node binary doesn't need it. If you want a container, the install is `FROM node:20-alpine` + `RUN npm install -g @pmoses-s1/s1-secops-mcp@1.3.2` + `CMD ["s1-secops-mcp", "--transport", "http", "--host", "0.0.0.0"]`. Mount creds at `/etc/s1-secops-mcp/credentials.json` and tokens at `/etc/s1-secops-mcp/bearer-tokens.json`.
+- **Docker / docker-compose.** Not shipped in this version. The single-file Node binary doesn't need it. If you want a container, the install is `FROM node:20-alpine` + `RUN npm install -g @pmoses-s1/s1-secops-mcp@1.3.3` + `CMD ["s1-secops-mcp", "--transport", "http", "--host", "0.0.0.0"]`. Mount creds at `/etc/s1-secops-mcp/credentials.json` and tokens at `/etc/s1-secops-mcp/bearer-tokens.json`.
 
 - **External bridge (`supergateway`, `mcp-proxy`).** Pre-1.1.0 deployments used these to wrap the stdio-only server. They still work; this server's native HTTP mode is functionally equivalent and removes the extra process. Prefer native unless you have a specific reason.
 

package/deploy/bridge/README.md

@@ -76,7 +76,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
 
 ## How it works
 
-```
+```text
 +----------------+          stdio JSON-RPC          +--------+        HTTPS POST /mcp        +------+
 | Claude Desktop | <------------------------------> | bridge | <---------------------------> | VM   |
 +----------------+                                  +--------+   Bearer auth, JSON in/out    +------+

package/lib/sdl.js

@@ -133,6 +133,17 @@ async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null,
 // dashboard by udoId. Skipping that rule is how one tenant accumulated 152
 // copies of `/dashboards/AI Usage`.
 
+/** Marks an error as originating from the GraphQL layer rather than the
+ *  transport. Absence detection keys off this: a 404 page whose body contains
+ *  "not found" must never be read as "the file does not exist". */
+class SdlGraphqlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SdlGraphqlError';
+    this.graphql = true;
+  }
+}
+
 /**
  * POST /sdl/v2/graphql. Returns `data`; throws on the GraphQL `errors` array.
  *
@@ -170,10 +181,10 @@ async function sdlGraphql(opname, query, variables, { readOnly = false } = {}) {
     const errs = Array.isArray(payload.errors) ? payload.errors : [payload.errors];
     const correlationId = payload.extensions?.correlationId ?? errs[0]?.extensions?.correlationId;
     const msg = errs[0]?.message || 'unknown GraphQL error';
-    throw new Error(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
+    throw new SdlGraphqlError(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
   }
   if (!('data' in payload)) {
-    throw new Error(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
+    throw new SdlGraphqlError(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
   }
   return payload.data;
 }
@@ -191,6 +202,15 @@ function assertSafeUdoId(udoId) {
 
 const CONFIG_FIELDS = 'udoId name readOnly version';
 
+/** SDL config names are case-insensitive and tolerate stray whitespace, so the
+ *  absence check and the duplicate guard must normalise identically. */
+function normaliseName(n) {
+  return String(n ?? '').trim().toLowerCase();
+}
+function matchesName(file, name) {
+  return normaliseName(file?.name) === normaliseName(name);
+}
+
 /** Every config file on the tenant, including udoId-addressed dashboards. */
 export async function configFiles() {
   const data = await sdlGraphql(
@@ -202,13 +222,58 @@ export async function configFiles() {
   return data?.configFiles ?? [];
 }
 
-/** Read one config file by name (plain files) or udoId (dashboards). */
+/**
+ * Read one config file by name (plain files) or udoId (dashboards).
+ * Returns null when the file does not exist.
+ *
+ * Absence is a normal outcome of a lookup, but the server reports it as a
+ * GraphQL error, and the message differs by address form (verified live):
+ *
+ *   by name : "Config file with name /x/y not found."   <- explicit
+ *   by udoId: "Something went wrong. Please try again..." <- generic, and the
+ *             SAME text a version conflict returns, so it cannot be trusted
+ *             on message alone.
+ *
+ * So the explicit form is normalised directly, and the ambiguous one is
+ * disambiguated against the file listing: absent from configFiles means the
+ * file is genuinely gone, otherwise the error was real and is rethrown. The
+ * extra listing only happens on the error path.
+ */
 export async function configFile({ name, udoId }) {
   if (!name && !udoId) throw new Error('configFile requires either name or udoId');
-  const data = udoId
-    ? await sdlGraphql('configFile', `query f($udoId: ID!) { configFile(udoId: $udoId) { ${CONFIG_FIELDS} content } }`, { udoId: assertSafeUdoId(udoId) }, { readOnly: true })
-    : await sdlGraphql('configFile', `query f($id: ID!) { configFile(id: $id) { ${CONFIG_FIELDS} content } }`, { id: name }, { readOnly: true });
-  return data?.configFile ?? null;
+  // Validate before the try: an invalid udoId is a caller bug, not a signal
+  // that the file is absent, and must never be swallowed by the absence path.
+  const safeUdoId = udoId ? assertSafeUdoId(udoId) : null;
+  try {
+    const data = safeUdoId
+      ? await sdlGraphql('configFile', `query f($udoId: ID!) { configFile(udoId: $udoId) { ${CONFIG_FIELDS} content } }`, { udoId: safeUdoId }, { readOnly: true })
+      : await sdlGraphql('configFile', `query f($id: ID!) { configFile(id: $id) { ${CONFIG_FIELDS} content } }`, { id: name }, { readOnly: true });
+    return data?.configFile ?? null;
+  } catch (err) {
+    // Only a GraphQL-layer error can mean "absent". A transport failure whose
+    // body happens to contain the words "not found" (a 404 page, a WAF block)
+    // must never be read as absence: that is how a delete gets confirmed
+    // against a file that was never checked.
+    if (!err.graphql) throw err;
+    if (/config file with (name|id) .* not found/i.test(err.message)) return null;
+
+    // The udoId form returns a generic message that a version conflict also
+    // returns, so settle it against the listing. If the listing itself fails,
+    // surface the ORIGINAL error with the listing failure attached rather than
+    // replacing it.
+    let all;
+    try {
+      all = await configFiles();
+    } catch (listErr) {
+      err.message += ` (absence check failed: ${listErr.message})`;
+      throw err;
+    }
+    const present = udoId
+      ? all.some(f => String(f.udoId) === String(udoId))
+      : all.some(f => matchesName(f, name));
+    if (!present) return null;
+    throw err;
+  }
 }
 
 /**
@@ -222,7 +287,7 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
   // Creating a dashboard must go by name (no udoId exists yet); only an
   // *existing* dashboard is at risk of being duplicated by a name-addressed
   // write. So refuse only when a file of that name already exists.
-  if (!udoId && String(name).startsWith('/dashboards/')) {
+  if (!udoId && normaliseName(name).startsWith('/dashboards/')) {
     const all = await configFiles();
     // An empty listing means the check could not run, not that the name is
     // free. Failing open here would silently disable the guard.
@@ -232,8 +297,7 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
         'duplicate check could not run. Retry, or pass an explicit udoId.'
       );
     }
-    const key = String(name).trim().toLowerCase();
-    const existing = all.filter(f => String(f.name || '').trim().toLowerCase() === key);
+    const existing = all.filter(f => matchesName(f, name));
     if (existing.length) {
       const ids = existing.map(f => f.udoId).filter(Boolean).join(', ');
       throw new Error(
@@ -307,5 +371,7 @@ export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime
     startTime,
   };
   if (endTime) body.endTime = endTime;
-  return sdlFetch('POST', '/api/query', { body });
+  // Read-only POST: opt back into status retry. Schema discovery iterates this
+  // once per data source, which is the workload that trips the SDL QPS cap.
+  return sdlFetch('POST', '/api/query', { body, allowRetry: true });
 }

package/lib/server-core.js

@@ -94,7 +94,7 @@ const PROMPTS = [
 
 export const SERVER_INFO = {
   name: 's1-secops-mcp-server',
-  version: '1.3.2',
+  version: '1.3.3',
 };
 
 export const PROTOCOL_VERSION = '2024-11-05';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmoses-s1/s1-secops-mcp",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "MCP server orchestrating SentinelOne skills, APIs, and SOC analyst context. Stdio or Streamable HTTP transport with per-user bearer auth for team deployments.",
   "type": "module",
   "main": "index.js",

package/tools/sdl-api.js

@@ -97,7 +97,7 @@ export const tools = [
         },
         expectedVersion: {
           type: 'number',
-          description: 'Current file version from sdl_get_file, for optimistic locking. Honoured on udoId-addressed writes. Omit when creating a new file.',
+          description: 'Current file version from sdl_get_file, for optimistic locking. Enforced on BOTH address forms, path and udoId: a stale value is rejected and nothing is written. Omit only when creating a new file.',
         },
       },
       required: ['content'],