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

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 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 honoured on `udoId`-addressed writes and ignored on name-addressed ones.
+- 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.

package/README.md

@@ -65,7 +65,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.2"],
       "env": {
         "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
         "S1_CONSOLE_API_TOKEN": "eyJ...",
@@ -126,16 +126,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)
@@ -485,6 +485,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` |
 
 ## Testing
 

package/deploy/README.md

@@ -56,7 +56,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.2"]
     }
   }
 }
@@ -363,7 +363,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.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`.
 
 - **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/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,189 @@ 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 /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 Error(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
+  }
+  if (!('data' in payload)) {
+    throw new Error(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
+  }
+  return payload.data;
+}
+
+/** 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 String(udoId);
+}
 
-/** POST /api/listFiles: list every configuration file path on the SDL tenant. */
-export async function listFiles() {
-  return sdlFetch('POST', '/api/listFiles', { body: {} });
+const CONFIG_FIELDS = 'udoId name readOnly version';
+
+/** 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 ?? [];
 }
 
-/** 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 },
-  });
+/** Read one config file by name (plain files) or udoId (dashboards). */
+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;
 }
 
-/** 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;
+/**
+ * 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 && String(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 key = String(name).trim().toLowerCase();
+    const existing = all.filter(f => String(f.name || '').trim().toLowerCase() === key);
+    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)'}.`
+      );
+    }
   }
-  return sdlFetch('POST', '/api/putFile', { body });
+  // 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;
 }
 
-/** 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 });
+/**
+ * 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.

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.2',
 };
 
 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.2",
   "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. Honoured on udoId-addressed writes. Omit 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);
     },
   },