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

package/CHANGELOG.md

@@ -1,10 +1,112 @@
 # 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
+26, and all four tool names are unchanged, so no caller needs to change.
+
+### Fixed
+
+- **`sdl_list_files` no longer returns an incomplete listing.** The REST `/sdl/api/listFiles`
+  endpoint omits every udoId-addressed dashboard. Measured live on `usea1-purple`: REST returned
+  1,914 paths against `configFiles`' 2,264, a 350-file gap consisting entirely of `/dashboards/`
+  files that carry a `udoId`. REST `getFile` on any of them returns `success/noSuchFile`. The
+  practical impact was a false negative: a dashboard that existed in the console was reported as
+  not found. All four config-file tools now run on `POST /sdl/v2/graphql`.
+- **`sdl_list_files` description no longer claims to return "all" files.** It did not, and the
+  claim was load-bearing: an agent reading it had no reason to look further after an empty result.
+- **`sdl_get_file` / `sdl_put_file` / `sdl_delete_file` can now address dashboards.** New `udoId`
+  parameter. The console's Configuration Files grid displays a dashboard as
+  `/dashboards/id/<udoId>/<name>`; that string is not a path, and reading it as one returns
+  `no file exists at path`.
+
+### Added
+
+- **`lib/sdl.js`: `configFiles`, `configFile`, `putConfigFile`, `deleteConfigFile`** over
+  `POST /sdl/v2/graphql`. GraphQL reports failure as HTTP 200 with an `errors` array, so the
+  wrapper raises on that array rather than trusting the status code.
+- **Duplicate guardrail on dashboard writes.** `addConfigFile(name:)` updates in place for a
+  name-addressed file but creates a duplicate for a dashboard (both verified live). `sdl_put_file`
+  now refuses a name-addressed write to an *existing* dashboard and names the `udoId`s already
+  holding it, while still allowing the initial create, which has no `udoId` yet. The tenant this
+  was found on already carries 256 surplus dashboard copies from this behaviour, including 152 of
+  `/dashboards/AI Usage`.
+- **`pathPrefix` filter on `sdl_list_files`**, so callers can scope to `/dashboards/` or
+  `/logParsers/` without pulling the full listing into context.
+
+### Notes
+
+- `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 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.
+
 ## 1.2.4 - 2026-07-31
 
 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.
@@ -16,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.
@@ -23,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.
 
@@ -31,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.
@@ -45,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).
 
@@ -62,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.
@@ -94,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
@@ -107,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.
@@ -114,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.1"],
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.3"],
       "env": {
         "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
         "S1_CONSOLE_API_TOKEN": "eyJ...",
@@ -126,16 +128,16 @@ Cmd+Q and reopen Claude Desktop. SentinelOne credentials live on the VM in `/etc
 
 Credential keys, where to get each one, and the two token types are documented canonically in **[docs/credentials.md](../docs/credentials.md)**. This section adds the MCP-server-specific detail: which tools each key gates, and the server's full credential-resolution order.
 
-`S1_CONSOLE_URL` and `S1_CONSOLE_API_TOKEN` are sufficient for the PowerQuery, Mgmt Console REST, Purple AI summary, and UAM tools (16 of the 26).
+`S1_CONSOLE_URL` and `S1_CONSOLE_API_TOKEN` are sufficient for the PowerQuery, Mgmt Console REST, Purple AI summary, UAM, Hyperautomation, and SDL config-file tools (22 of the 26).
 
-`S1_HEC_INGEST_URL` is **required** for the three UAM Ingest tools (`uam_ingest_alert`, `uam_post_indicators`, `uam_post_alert`) and for `hec_ingest`. Without it those tools error at call time; the rest still work.
+`S1_HEC_INGEST_URL` is **required** for the three UAM Ingest tools (`uam_ingest_alert`, `uam_post_indicators`, `uam_post_alert`) and for `hec_ingest`, the only four tools that need it. Without it those tools error at call time; the rest still work.
 
-`SDL_*` keys gate the SDL tools as follows:
+The SDL config-file tools (`sdl_list_files`, `sdl_get_file`, `sdl_put_file`, `sdl_delete_file`) are authorised by `S1_CONSOLE_API_TOKEN` against `POST <console>/sdl/v2/graphql`. The scoped SDL keys (`SDL_CONFIG_READ_KEY`, `SDL_CONFIG_WRITE_KEY`, `SDL_LOG_READ_KEY`, `SDL_LOG_WRITE_KEY`, `SDL_XDR_URL`) are retired and are no longer read.
 
 | Variable | Description | Required for |
 |----------|-------------|--------------|
-| `S1_CONSOLE_URL` | Console URL, e.g. `https://usea1-acme.sentinelone.net` | All Mgmt + PowerQuery tools |
-| `S1_CONSOLE_API_TOKEN` | Mgmt Console API token (Settings → Users → Service Users) | All Mgmt + PowerQuery + UAM tools |
+| `S1_CONSOLE_URL` | Console URL, e.g. `https://usea1-acme.sentinelone.net` | All Mgmt + PowerQuery + SDL tools |
+| `S1_CONSOLE_API_TOKEN` | Mgmt Console API token (Settings → Users → Service Users) | All Mgmt + PowerQuery + UAM + SDL config-file tools |
 | `S1_HEC_INGEST_URL` | HEC ingest host, e.g. `https://ingest.us1.sentinelone.net` | `uam_ingest_alert`, `uam_post_indicators`, `uam_post_alert`, `hec_ingest` |
 
 ### Credential resolution order (highest priority wins)
@@ -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,6 +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>`, 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.1"]
+      "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.1` + `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/credentials.js

@@ -106,7 +106,6 @@ export function getCreds() {
     S1_CONSOLE_URL:       e('S1_CONSOLE_URL'),
     S1_CONSOLE_API_TOKEN: e('S1_CONSOLE_API_TOKEN') || e('S1_API_TOKEN'),
     S1_HEC_INGEST_URL:    e('S1_HEC_INGEST_URL'),
-    VT_API_KEY:           e('VT_API_KEY'),
   };
 }
 

package/lib/sdl.js

@@ -37,14 +37,44 @@ function retryAfterMs(res, fallback) {
   return fallback;
 }
 
-async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null, contentType = 'application/json' } = {}, retries = 3) {
-  const url = `${sdlBase()}${path}`;
+/**
+ * Origin-pin the SDL request path, mirroring safeUrl() in lib/s1.js.
+ *
+ * Every current caller passes a literal, so this is defence in depth: the next
+ * caller to thread a tool-supplied path through sdlFetch would otherwise be
+ * able to rewrite the authority ("//evil.example/x", "@evil.example/x") and
+ * send the tenant bearer token to an attacker-chosen origin.
+ */
+function safeSdlUrl(path) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//')) {
+    throw new Error(
+      `SDL API path must be a string starting with a single "/" (got: ${JSON.stringify(path)?.slice(0, 80)})`
+    );
+  }
+  const origin = new URL(sdlBase()).origin;
+  const u = new URL(sdlBase() + path, origin);
+  if (u.origin !== origin) {
+    throw new Error(`SDL API path may not change the request origin (resolved to ${u.origin})`);
+  }
+  return u.toString();
+}
+
+async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null, contentType = 'application/json', allowRetry = null } = {}, retries = 3) {
+  const url = safeSdlUrl(path);
   const headers = {
     Authorization: `Bearer ${sdlToken()}`,
     'Content-Type': contentType,
     ...extraHeaders,
   };
 
+  // Status-based retry is restricted to idempotent methods, mirroring lib/s1.js.
+  // A 5xx received *after* the server committed a write would otherwise be
+  // re-sent, and a re-sent addConfigFile(name:) against /dashboards/ creates a
+  // duplicate. Callers opt in with allowRetry:true for read-only POSTs
+  // (GraphQL queries). Network-layer rejections are still always retried:
+  // those mean the request may never have reached the server at all.
+  const methodRetryable = allowRetry !== null ? allowRetry : (method === 'GET' || method === 'HEAD');
+
   let delay = 500;
   for (let attempt = 0; attempt <= retries; attempt++) {
     let res;
@@ -61,7 +91,7 @@ async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null,
       continue;
     }
 
-    if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+    if (methodRetryable && (res.status === 429 || res.status >= 500) && attempt < retries) {
       await sleep(retryAfterMs(res, delay));
       delay = Math.min(delay * 2, 8000);
       continue;
@@ -80,38 +110,253 @@ async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null,
   throw new Error(`SDL API ${method} ${path}: request failed after retries`);
 }
 
-// ─── Config file operations ───────────────────────────────────────────────────
+// ─── Config file operations (GraphQL, canonical) ──────────────────────────────
+//
+// `POST /sdl/v2/graphql` is the canonical config-file surface. It is a strict
+// superset of the legacy REST `/api/*File` endpoints:
+//
+//   * REST listFiles omits every udoId-addressed dashboard. Measured on a live
+//     tenant: REST returned 1,914 paths, GraphQL configFiles returned 2,264.
+//     The 350-file gap is entirely /dashboards/ files that carry a udoId, and
+//     REST getFile on any of them returns `success/noSuchFile`.
+//   * The console's Configuration Files grid renders a udoId dashboard as the
+//     display string `/dashboards/id/<udoId>/<name>`. That is NOT a path. Reading
+//     it as one returns "no file exists at path". Address it by udoId; its real
+//     name is `/dashboards/<name>`.
+//
+// udoId assignment is by namespace, verified live: only `/dashboards/` files get
+// a udoId. `/lookups/`, `/datatables/`, `/logParsers/` and `/automaticLookups`
+// all come back with udoId `null` and are addressed by name.
+//
+// Write rule, verified live: addConfigFile(name:) UPDATES IN PLACE for a
+// name-addressed file, but CREATES A DUPLICATE for a dashboard. Always write a
+// dashboard by udoId. Skipping that rule is how one tenant accumulated 152
+// copies of `/dashboards/AI Usage`.
 
-/** POST /api/listFiles: list every configuration file path on the SDL tenant. */
-export async function listFiles() {
-  return sdlFetch('POST', '/api/listFiles', { body: {} });
+/** 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 /api/getFile: read a configuration file by path.
- *  Returns { path, content, version, ...status }. */
-export async function getFile(path) {
-  return sdlFetch('POST', '/api/getFile', {
-    body: { path, prettyprint: true },
-  });
+/**
+ * POST /sdl/v2/graphql. Returns `data`; throws on the GraphQL `errors` array.
+ *
+ * GraphQL reports failure as HTTP 200 with an `errors` array, so the status
+ * code alone never proves success. Three things this must not do, each of which
+ * would resurface the exact false-negative class this module exists to remove:
+ *
+ *   1. Accept a non-JSON 200. sdlFetch falls back to raw text when JSON.parse
+ *      fails, so a proxy interstitial or WAF page arrives as a string. Left
+ *      unchecked, `payload.errors` is undefined and every caller returns its
+ *      empty default: "no files", "not found", "deleted".
+ *   2. Require `errors` to be an array. A bare `{errors: {...}}` object would
+ *      slip through an Array.isArray gate.
+ *   3. Return a payload carrying neither `data` nor `errors`.
+ *
+ * `readOnly` opts into status-based retry; only pass it for queries.
+ */
+async function sdlGraphql(opname, query, variables, { readOnly = false } = {}) {
+  const body = { query };
+  if (variables) body.variables = variables;
+  const payload = await sdlFetch(
+    'POST',
+    `/v2/graphql?opname=${encodeURIComponent(opname)}`,
+    { body, allowRetry: readOnly }
+  );
+
+  if (typeof payload !== 'object' || payload === null) {
+    throw new Error(
+      `SDL GraphQL ${opname}: expected a JSON object, got ${typeof payload}. ` +
+      'This usually means a proxy or auth interstitial answered instead of the API. ' +
+      `First 200 chars: ${String(payload).slice(0, 200)}`
+    );
+  }
+  if (payload.errors) {
+    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 SdlGraphqlError(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
+  }
+  if (!('data' in payload)) {
+    throw new SdlGraphqlError(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
+  }
+  return payload.data;
 }
 
-/** POST /api/putFile: create or update a configuration file.
- *  Pass expectedVersion (from a prior getFile) to enable optimistic locking. */
-export async function putFile(path, content, expectedVersion) {
-  const body = { path, content };
-  if (expectedVersion !== undefined && expectedVersion !== null) {
-    body.expectedVersion = expectedVersion;
+/** udoIds are 16 digits, within ~1.4x of Number.MAX_SAFE_INTEGER. A caller that
+ *  sends one as a JSON number has already lost precision before we stringify. */
+function assertSafeUdoId(udoId) {
+  if (typeof udoId === 'number' && !Number.isSafeInteger(udoId)) {
+    throw new Error(
+      `udoId ${udoId} exceeds the JS safe-integer range and has already lost precision. Pass it as a string.`
+    );
   }
-  return sdlFetch('POST', '/api/putFile', { body });
+  return String(udoId);
 }
 
-/** POST /api/putFile with deleteFile:true deletes a config file. */
-export async function deleteFile(path, expectedVersion) {
-  const body = { path, deleteFile: true };
-  if (expectedVersion !== undefined) body.expectedVersion = expectedVersion;
-  return sdlFetch('POST', '/api/putFile', { body });
+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(
+    'getConfigurationFiles',
+    `query getConfigurationFiles { configFiles { ${CONFIG_FIELDS} } }`,
+    undefined,
+    { readOnly: true }
+  );
+  return data?.configFiles ?? [];
 }
 
+/**
+ * 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');
+  // 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;
+  }
+}
+
+/**
+ * Create or update a config file.
+ *   - udoId given  → updates that file in place; pass expectedVersion to lock.
+ *   - name given   → updates in place for plain files, but CREATES A DUPLICATE
+ *                    for /dashboards/. Never write a dashboard by name.
+ */
+export async function putConfigFile({ name, udoId, content, expectedVersion }) {
+  if (!name && !udoId) throw new Error('putConfigFile requires either name or udoId');
+  // 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 && 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.
+    if (!all.length) {
+      throw new Error(
+        `Refusing to write "${name}" by name: the configFiles listing came back empty, so the ` +
+        'duplicate check could not run. Retry, or pass an explicit udoId.'
+      );
+    }
+    const existing = all.filter(f => matchesName(f, name));
+    if (existing.length) {
+      const ids = existing.map(f => f.udoId).filter(Boolean).join(', ');
+      throw new Error(
+        `Refusing to write "${name}" by name: ${existing.length} dashboard(s) already use that name, ` +
+        'and a name-addressed write to /dashboards/ creates another duplicate rather than updating. ' +
+        `Pass one of these udoIds instead: ${ids || '(none, file has no udoId)'}.`
+      );
+    }
+  }
+  // expectedVersion is honoured on BOTH address forms. Verified live 2026-08-07:
+  // a stale expectedVersion on a name-addressed /datatables/ write was rejected
+  // with "There are conflicting changes in the file." and the content was left
+  // untouched. Omitting it here would silently downgrade every parser, lookup,
+  // datatable and /automaticLookups write to last-write-wins.
+  const data = udoId
+    ? await sdlGraphql('addConfigFile',
+        `mutation f($udoId: ID, $content: String!, $expectedVersion: Long) { addConfigFile(udoId: $udoId, content: $content, expectedVersion: $expectedVersion) { ${CONFIG_FIELDS} } }`,
+        { udoId: assertSafeUdoId(udoId), content, expectedVersion })
+    : await sdlGraphql('addConfigFile',
+        `mutation f($name: String, $content: String!, $expectedVersion: Long) { addConfigFile(name: $name, content: $content, expectedVersion: $expectedVersion) { ${CONFIG_FIELDS} } }`,
+        { name, content, expectedVersion });
+  return data?.addConfigFile ?? null;
+}
+
+/**
+ * Delete a config file. Dashboards delete by udoId, plain files by name.
+ * A null return with no errors array is SUCCESS; the deleted object is not
+ * echoed back. Treating that null as a failure is the classic mistake here.
+ */
+export async function deleteConfigFile({ name, udoId, expectedVersion }) {
+  if (!name && !udoId) throw new Error('deleteConfigFile requires either name or udoId');
+  const raw = udoId
+    ? await sdlGraphql('deleteConfigFile',
+        'mutation f($udoId: ID, $expectedVersion: Long) { deleteConfigFile(udoId: $udoId, expectedVersion: $expectedVersion) { udoId } }',
+        { udoId: assertSafeUdoId(udoId), expectedVersion })
+    : await sdlGraphql('deleteConfigFile',
+        'mutation f($id: ID, $expectedVersion: Long) { deleteConfigFile(id: $id, expectedVersion: $expectedVersion) { udoId } }',
+        { id: name, expectedVersion });
+
+  // The mutation returns null on success and does not echo the deleted object,
+  // so its response cannot distinguish "deleted" from "matched nothing". Confirm
+  // by re-reading. This is the house rule established by uamSetStatus in
+  // lib/s1.js: never treat a mutation response as proof, re-get and verify.
+  const still = await configFile({ name, udoId });
+  if (still) {
+    throw new Error(
+      `deleteConfigFile: ${udoId ? `udoId ${udoId}` : name} still exists after the delete mutation ` +
+      `(version ${still.version}). The mutation reported no errors but nothing was removed.`
+    );
+  }
+  return { status: 'success', deleted: udoId ? { udoId: String(udoId) } : { name }, raw: raw?.deleteConfigFile ?? null };
+}
+
+// The legacy REST config-file endpoints (/api/listFiles, /api/getFile,
+// /api/putFile) are not wrapped here. They cannot see or modify a
+// udoId-addressed dashboard, so their listing is unsafe for any "does this file
+// exist" decision. The GraphQL operations above cover every namespace,
+// including parsers, lookups, datatables and /automaticLookups.
+
 // ─── V1 Query (schema discovery) ─────────────────────────────────────────────
 // Deprecated Feb 15 2027 but still the only way to get full event JSON per-event.
 // Use for schema discovery; use LRQ for hunting.
@@ -126,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.1',
+  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.1",
+  "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",
@@ -20,7 +20,7 @@
     "start": "node index.js",
     "start:http": "node index.js --transport http",
     "dev": "node --watch index.js",
-    "test": "node --test tests/smoke.test.mjs tests/stdio-transport.test.mjs tests/http-transport.test.mjs tests/ssrf-path.test.mjs tests/http-origin-guard.test.mjs tests/regressions-2026-07-29.test.mjs tests/regressions-2026-07-31.test.mjs",
+    "test": "node --test tests/smoke.test.mjs tests/stdio-transport.test.mjs tests/http-transport.test.mjs tests/ssrf-path.test.mjs tests/http-origin-guard.test.mjs tests/sdl-graphql.test.mjs tests/regressions-2026-07-29.test.mjs tests/regressions-2026-07-31.test.mjs",
     "regen:readme": "node scripts/regen-readme-tools-table.mjs"
   },
   "engines": {

package/tools/sdl-api.js

@@ -2,48 +2,76 @@
  * SDL API tools: sdl-api, sdl-dashboard, sdl-log-parser skills
  *
  * Tools:
- *   sdl_list_files     List all config files on the SDL tenant
- *   sdl_get_file       Get file content and version (parsers, dashboards, alerts, lookups)
+ *   sdl_list_files     List every config file on the SDL tenant (GraphQL configFiles)
+ *   sdl_get_file       Get file content and version, by path or udoId
  *   sdl_put_file       Deploy or update a config file (with optimistic locking)
  *   sdl_delete_file    Delete a config file
  *   hec_ingest         Ingest raw logs/events into SDL via the HEC endpoint (replaces uploadLogs)
+ *
+ * All four config-file tools run on `POST /sdl/v2/graphql`. The legacy REST
+ * `/sdl/api/*File` endpoints are NOT used: they silently omit every
+ * udoId-addressed dashboard (1,914 vs 2,264 files on a live tenant) and return
+ * `success/noSuchFile` for any of them.
  */
 
-import { listFiles, getFile, putFile, deleteFile } from '../lib/sdl.js';
+import { configFiles, configFile, putConfigFile, deleteConfigFile } from '../lib/sdl.js';
 import { hecIngest } from '../lib/hec.js';
 
+const UDOID_NOTE =
+  'Dashboards are addressed by udoId, everything else by path. The console shows a dashboard as ' +
+  '"/dashboards/id/<udoId>/<name>" in its Configuration Files grid; that display string is NOT a path, ' +
+  'the number in it is the udoId and the real path is "/dashboards/<name>". ' +
+  'udoId assignment is by namespace: only /dashboards/ files have one, /lookups/, /datatables/, ' +
+  '/logParsers/ and /automaticLookups are all name-addressed with udoId null.';
+
 export const tools = [
   // ─── sdl_list_files ───────────────────────────────────────────────────────
   {
     name: 'sdl_list_files',
-    description: `List all configuration files stored in the SDL tenant. Returns all paths organized by type: /logParsers/, /dashboards/, /alerts/, /lookups/, /datatables/. Use this to discover what parsers and dashboards are already deployed, or to find a file path before calling sdl_get_file or sdl_put_file.`,
+    description: `List every configuration file on the SDL tenant via the GraphQL configFiles query: /logParsers/, /dashboards/, /alerts/, /lookups/, /datatables/, /automaticLookups. Returns {udoId, name, readOnly, version} per file. ${UDOID_NOTE} Use this to discover what is deployed, and to resolve a dashboard name to the udoId that sdl_get_file/sdl_put_file need. Never conclude a file is absent from a listing produced any other way; the legacy REST listing omits ~350 dashboards.`,
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        pathPrefix: {
+          type: 'string',
+          description: 'Optional filter, e.g. "/dashboards/" or "/logParsers/". Applied client-side to the full listing.',
+        },
+      },
       required: [],
     },
-    async handler() {
-      const result = await listFiles();
-      return JSON.stringify(result, null, 2);
+    async handler({ pathPrefix } = {}) {
+      let files = await configFiles();
+      if (pathPrefix) files = files.filter(f => (f.name || '').startsWith(pathPrefix));
+      return JSON.stringify({ count: files.length, files }, null, 2);
     },
   },
 
   // ─── sdl_get_file ─────────────────────────────────────────────────────────
   {
     name: 'sdl_get_file',
-    description: `Get the content and current version number of a SDL configuration file. Use before sdl_put_file to read the current version for optimistic locking (pass the returned version as expectedVersion). Supports any file type: parsers (/logParsers/<name>), dashboards (/dashboards/<name>), alerts (/alerts/<name>), lookups (/lookups/<name>), datatables (/datatables/<name>). Always read before overwriting; this prevents concurrent-edit conflicts.`,
+    description: `Get the content and current version of a SDL configuration file. Pass "path" for name-addressed files (parsers, lookups, datatables, alerts, /automaticLookups) or "udoId" for a dashboard. ${UDOID_NOTE} Read this before sdl_put_file and pass the returned version as expectedVersion so the write is optimistically locked. If a lookup by path returns nothing, the file is probably udoId-addressed: list it with sdl_list_files and retry with its udoId rather than reporting it as missing.`,
     inputSchema: {
       type: 'object',
       properties: {
         path: {
           type: 'string',
-          description: 'Full SDL config path, e.g. "/logParsers/FortiGate" or "/dashboards/SOC-Overview". Get the path from sdl_list_files.',
+          description: 'Full SDL config path, e.g. "/logParsers/FortiGate" or "/lookups/assets.csv".',
+        },
+        udoId: {
+          type: 'string',
+          description: 'Dashboard udoId, e.g. "3559330396332032". Get it from sdl_list_files. Required for /dashboards/ files.',
         },
       },
-      required: ['path'],
+      required: [],
     },
-    async handler({ path }) {
-      const result = await getFile(path);
+    async handler({ path, udoId }) {
+      const result = await configFile({ name: path, udoId });
+      if (!result) {
+        return JSON.stringify({
+          status: 'notFound',
+          hint: 'No file at that address. If this is a dashboard, it is udoId-addressed: run sdl_list_files with pathPrefix "/dashboards/" and retry with its udoId.',
+        }, null, 2);
+      }
       return JSON.stringify(result, null, 2);
     },
   },
@@ -51,13 +79,17 @@ export const tools = [
   // ─── sdl_put_file ─────────────────────────────────────────────────────────
   {
     name: 'sdl_put_file',
-    description: `Deploy or update a SDL configuration file. Always call sdl_get_file first to obtain the current expectedVersion; this prevents overwriting concurrent edits. If creating a new file, omit expectedVersion. File type conventions: parsers go to /logParsers/<name>, dashboards to /dashboards/<name>, alerts to /alerts/<name>, lookups to /lookups/<name>. Authorised by S1_CONSOLE_API_TOKEN.`,
+    description: `Create or update a SDL configuration file. To create, pass "path". To update, pass the file's current address plus expectedVersion from sdl_get_file. ${UDOID_NOTE} CRITICAL for dashboards: update by udoId, never by path. A path-addressed write to /dashboards/ does not update, it creates a duplicate file sharing the name; that is how one tenant accumulated 152 copies of "/dashboards/AI Usage". This tool refuses path-addressed writes to /dashboards/ on an existing file for that reason. Name-addressed writes to every other namespace update in place normally.`,
     inputSchema: {
       type: 'object',
       properties: {
         path: {
           type: 'string',
-          description: 'Full SDL config path, e.g. "/logParsers/MyParser" or "/dashboards/SOC-Ops".',
+          description: 'Full SDL config path, e.g. "/logParsers/MyParser". Use for creates, and for updates to non-dashboard files.',
+        },
+        udoId: {
+          type: 'string',
+          description: 'Dashboard udoId. REQUIRED to update an existing dashboard; a path-addressed dashboard write duplicates instead of updating.',
         },
         content: {
           type: 'string',
@@ -65,13 +97,13 @@ export const tools = [
         },
         expectedVersion: {
           type: 'number',
-          description: 'Current file version from sdl_get_file. Required for updates to enable optimistic locking. Omit only 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: ['path', 'content'],
+      required: ['content'],
     },
-    async handler({ path, content, expectedVersion }) {
-      const result = await putFile(path, content, expectedVersion);
+    async handler({ path, udoId, content, expectedVersion }) {
+      const result = await putConfigFile({ name: path, udoId, content, expectedVersion });
       return JSON.stringify(result, null, 2);
     },
   },
@@ -79,23 +111,27 @@ export const tools = [
   // ─── sdl_delete_file ──────────────────────────────────────────────────────
   {
     name: 'sdl_delete_file',
-    description: `Delete a SDL configuration file (parser, dashboard, alert, lookup, datatable). Use with caution; deletion is permanent. Always read the file with sdl_get_file first to confirm you have the right path and version.`,
+    description: `Delete a SDL configuration file (parser, dashboard, alert, lookup, datatable). Deletion is permanent. Pass "udoId" for dashboards, "path" for everything else. ${UDOID_NOTE} Always read the file with sdl_get_file first to confirm the address and to get expectedVersion.`,
     inputSchema: {
       type: 'object',
       properties: {
         path: {
           type: 'string',
-          description: 'Full SDL config path to delete.',
+          description: 'Full SDL config path to delete (non-dashboard files).',
+        },
+        udoId: {
+          type: 'string',
+          description: 'Dashboard udoId to delete. Required for /dashboards/ files.',
         },
         expectedVersion: {
           type: 'number',
           description: 'Current file version for optimistic locking (from sdl_get_file). Strongly recommended.',
         },
       },
-      required: ['path'],
+      required: [],
     },
-    async handler({ path, expectedVersion }) {
-      const result = await deleteFile(path, expectedVersion);
+    async handler({ path, udoId, expectedVersion }) {
+      const result = await deleteConfigFile({ name: path, udoId, expectedVersion });
       return JSON.stringify(result, null, 2);
     },
   },