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

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 1.3.5 - 2026-08-17
+
+Completes the scope work in 1.3.4. **Upgrade from 1.3.4 is recommended.**
+
+### Fixed
+
+- **Query methods ignored `scope`.** 1.3.4 added the `scope` argument to the
+  config-file and dashboard operations but not to the query paths, even though
+  log reads are filtered by the same `S1-Scope` header. A hunt or a
+  panel-validation query run without the intended scope silently answered for
+  the token default, which is the worst shape of this bug: a plausible number
+  for the wrong boundary, with no error.
+
+  Scope now threads through `lrqRun` (launch **and** poll, so the forward-tagged
+  follow-ups stay on the same scope) and through all five Python query methods:
+  `query`, `power_query`, `facet_query`, `numeric_query`, `timeseries_query`.
+  Exposed on the `powerquery_run`, `powerquery_enumerate_sources` and
+  `powerquery_schema_discover` tools.
+
+  Found by using the shipped 1.3.4 client to discover schema at a site scope and
+  getting `power_query() got an unexpected keyword argument 'scope'`.
+
+- **`scopeHeaders` is now exported from `lib/sdl.js`** and imported by the LRQ
+  path in `lib/s1.js`, rather than each surface resolving scope its own way. A
+  second implementation would drift, and the validation rules (numeric ids,
+  `null` suppresses the default) have to be identical on both.
+
+### Tests
+
+- 4 new JS cases: `v1Query` header presence and absence, malformed-scope
+  rejection before any request, and a direct contract test on the exported
+  `scopeHeaders`.
+- 8 new Python cases covering all five query methods, unscoped omission,
+  malformed-scope rejection, and `scope=None` suppression.
+- Totals: 114 JS, 59 Python client, 19 panel-safety. No regressions.
+
+### Docker
+
+Bundle image stays **1.3.2**; its npm pin moves to 1.3.5.
+
+## 1.3.4 - 2026-08-17
+
+Adds site-level dashboard lifecycle. Two gaps closed: SDL GraphQL calls never
+sent an `S1-Scope` header, and the dashboard operations the console itself uses
+were not wrapped at all. **26 tools → 32.**
+
+### Added
+
+- **`S1-Scope` on every SDL GraphQL and V1-query call.** Optional `scope`
+  argument on `configFiles`, `configFile`, `putConfigFile`, `deleteConfigFile`
+  and `v1Query`, and on the four `sdl_*_file` tools. Falls back to a new
+  `S1_SCOPE` credential; `scope: null` suppresses that default and sends no
+  header. Format `"<accountId>"` or `"<accountId>:<siteId>"`, validated before
+  the request so a typo cannot silently widen the read.
+- **Six dashboard-lifecycle tools** on the `dashboardsV2` surface:
+  `sdl_list_dashboards`, `sdl_get_dashboard`, `sdl_create_dashboard`,
+  `sdl_share_dashboard`, `sdl_save_dashboard_layout`, `sdl_delete_dashboard`.
+- **`sdl_create_dashboard`** takes the whole dashboard document as one `config`
+  string, the path the console uses. It parses the JSON first, so the UI
+  stub-append failure (`{graphs: []}{...}` → "Content is invalid json /
+  Additional text after JSON object", leaving an empty dashboard behind) is
+  reported as a caller error instead of filing a broken shell.
+- **`sdl_share_dashboard`** wraps `shareResource`, the only SDL operation that
+  takes an explicit scope target. This is how an account-scoped dashboard is
+  pushed to a site without recreating it. Scope targets are validated up front,
+  because the server accepts a malformed entry, shares nothing, and reports
+  success.
+- **`S1_SCOPE`** added to `getCreds()`. It was absent, so any credentials-file
+  default would have been read and then dropped.
+
+### Fixed
+
+- **Scope-sensitive call sites now scope consistently.** Absence
+  disambiguation re-lists at the scope of the failed lookup, the `/dashboards/`
+  duplicate guard lists at the scope of the write, and delete verification
+  re-reads at the scope of the delete. Mixing scopes across these steps reports
+  a live site-scoped file as deleted, which is the same false-negative class
+  1.3.3 fixed for error text.
+
+### Corrected documentation
+
+- `sdl-api/references/config-file-graphql.md` claimed the `s1-scope` header was
+  "ignored, not rejected" on `/sdl/v2/graphql`. **That was wrong.** Measured on
+  `usea1-purple`, same token and query: `configFiles` returned 113 files at
+  account scope and 4 at a site scope. Config listings and dashboard reads are
+  scope-FILTERED, so a dropped header changes which objects appear to exist.
+  `auth_and_limits.md` corrected to match.
+
+### Dashboard skill
+
+- **`site.id`, not `site.name`, is the scoping predicate.** For one site over
+  24h, `site.id='<id>'` matched 60,410 events of which 510 carried the site id
+  with a null `site.name`: `ActivityFeed` 172, `asset` 111, unattributed 99,
+  `SentinelOne` 70, `Windows Event Logs` 48, `alert` 10. A `site.name` filter
+  silently drops alert and asset records. `site.id` is also the same value as
+  the `S1-Scope` `siteId` and survives a site rename.
+- **New scope doctrine in `sdl-dashboard/SKILL.md`:** deployment scope and query
+  scope are separate decisions, and a site-deployed dashboard scopes its panels
+  to that site unless the user explicitly asks for account-wide queries.
+- **`panel_safety_check.py --site-id <id>`** adds rule **S01** (query panel with
+  no, or wrong, `site.id` predicate on a site-targeted dashboard; opt out with
+  `--allow-account-scope-queries`) and rule **S02** (`site.name` used as a
+  scoping filter; never suppressed, the substitution is wrong at any scope).
+- Recorded that the console's XDR selector injects
+  `preFilter: "dataSource.category = 'security'"` into every panel query.
+
+### Python client (`sdl-api/scripts/sdl_client.py`)
+
+- Per-call `scope` on `config_files`, `config_file`, `put_config_file`,
+  `delete_config_file`, with the same `_UNSET`-vs-`None` distinction.
+- Six new methods mirroring the JS layer: `list_dashboards`, `get_dashboard`,
+  `create_dashboard`, `share_dashboard`, `save_dashboard_layout`,
+  `delete_dashboard`.
+- `get_dashboard` treats both a null result and a GraphQL error as absence,
+  disambiguated against the listing. Assuming only the null form is what broke
+  every delete in 1.3.2; the confirming re-read threw on the success path.
+
+### Tests
+
+- 24 new cases in `tests/sdl-graphql.test.mjs`: header presence and absence,
+  credentials fallback, `scope: null` suppression, malformed-scope rejection
+  before any request, scope consistency across the guard / disambiguation /
+  delete-verify paths, the six dashboard operations, stub-append rejection, and
+  the `getDashboard` absence matrix.
+- New `sdl-dashboard/tests/test_panel_safety_check.py`: 19 cases over S01 and
+  S02 including the wrong-site case, the opt-out flag, exempt panel types, and
+  a regression guard that existing rules still fire.
+- Tool-count assertions updated 26 → 32 across the smoke, stdio, HTTP and
+  origin-guard suites.
+
 ## 1.3.3 - 2026-08-07
 
 Fixes a user-facing regression in 1.3.2 found by running the live MCP tools

package/README.md

@@ -10,7 +10,7 @@ See **[deploy/README.md](./deploy/README.md)** for the full deployment walkthrou
 ## What this exposes
 
 <!-- BEGIN AUTO-GENERATED TOOLS TABLE -->
-**26 tools** across PowerQuery, Mgmt Console, SDL API, Hyperautomation, and UAM Ingest:
+**32 tools** across PowerQuery, Mgmt Console, SDL API, Hyperautomation, and UAM Ingest:
 
 | Group | Tool | Skill |
 |-------|------|-------|
@@ -28,10 +28,16 @@ See **[deploy/README.md](./deploy/README.md)** for the full deployment walkthrou
 | Mgmt Console | `uam_list_alerts` | mgmt-console-api |
 | Mgmt Console | `uam_set_status` | mgmt-console-api |
 | SDL API | `hec_ingest` | sdl-api / sdl-log-parser |
+| SDL API | `sdl_create_dashboard` | sdl-api / sdl-dashboard |
+| SDL API | `sdl_delete_dashboard` | sdl-api / sdl-dashboard |
 | SDL API | `sdl_delete_file` | sdl-api |
+| SDL API | `sdl_get_dashboard` | sdl-api / sdl-dashboard |
 | SDL API | `sdl_get_file` | sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_list_dashboards` | sdl-api / sdl-dashboard |
 | SDL API | `sdl_list_files` | sdl-api / sdl-dashboard / sdl-log-parser |
 | SDL API | `sdl_put_file` | sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_save_dashboard_layout` | sdl-api / sdl-dashboard |
+| SDL API | `sdl_share_dashboard` | sdl-api / sdl-dashboard |
 | Hyperautomation | `ha_delete_workflow` | hyperautomation |
 | Hyperautomation | `ha_export_workflow` | hyperautomation |
 | Hyperautomation | `ha_get_workflow` | hyperautomation |
@@ -67,11 +73,11 @@ 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.3"],
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.5"],
       "env": {
         "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
         "S1_CONSOLE_API_TOKEN": "eyJ...",
-        "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net",
+        "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net"
       }
     }
   }
@@ -487,7 +493,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` |
+| SDL config files (`POST /sdl/v2/graphql`) | `Authorization: Bearer <jwt>`, plus an `s1-scope` header that IS honoured: listings and reads are scope-filtered (measured 113 files at account scope vs 4 at a site scope) | `S1_CONSOLE_API_TOKEN`, optional `S1_SCOPE` |
 
 ## Testing
 
@@ -497,7 +503,7 @@ npm test
 
 Three test suites under `tests/`:
 
-- `smoke.test.mjs`: introspects `ALL_TOOLS` directly, no spawning. Asserts 26 tools by name; catches any drift between code and the README regenerator.
+- `smoke.test.mjs`: introspects `ALL_TOOLS` directly, no spawning. Asserts 32 tools by name; catches any drift between code and the README regenerator.
 - `stdio-transport.test.mjs`: spawns the server in stdio mode, exercises `initialize`, `tools/list`, `resources/list`, `prompts/list`, and error handling.
 - `http-transport.test.mjs`: spawns in HTTP mode on a random ephemeral port, exercises `/healthz`, `POST /mcp`, both auth-required and auth-optional flows, and the env-var token fallback.
 

package/deploy/README.md

@@ -34,7 +34,7 @@ Then edit `~/.config/sentinelone/credentials.json` with your real values:
 {
   "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
   "S1_CONSOLE_API_TOKEN": "eyJ...",
-  "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net",
+  "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net"
 }
 ```
 
@@ -57,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.3"]
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.5"]
     }
   }
 }
@@ -376,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.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`.
+- **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.5` + `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

@@ -46,7 +46,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
 
 `MCP_URL` is whatever URL your team's admin gave you (it should end in `/mcp`). `MCP_BEARER` is your personal bearer token from `/etc/s1-secops-mcp/bearer-tokens.json` on the VM.
 
-Quit Claude Desktop fully (Cmd+Q on macOS, not just close the window) and reopen. The 26 tools should appear in the tools list.
+Quit Claude Desktop fully (Cmd+Q on macOS, not just close the window) and reopen. The 32 tools should appear in the tools list.
 
 ## Smoke test (without Claude Desktop)
 

package/deploy/bridge/s1-secops-mcp-bridge.mjs

@@ -33,7 +33,7 @@
  *   MCP_URL=... MCP_BEARER=... bash -c '
  *     echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}" \
  *     | node s1-secops-mcp-bridge.mjs'
- *   # -> JSON-RPC response with 26 tools in result.tools[]
+ *   # -> JSON-RPC response with 32 tools in result.tools[]
  */
 
 import { createInterface } from 'node:readline';

package/index.js

@@ -6,7 +6,7 @@
  * Streamable HTTP, using raw JSON-RPC 2.0 throughout. No external runtime
  * dependencies. Pure Node.js 18+.
  *
- * Exposes 26 tools across PowerQuery, Mgmt Console REST, UAM, SDL API,
+ * Exposes 32 tools across PowerQuery, Mgmt Console REST, UAM, SDL API,
  * Hyperautomation, and UAM Ingest; plus 2 resources and 2 prompts.
  *
  * Quick start:

package/lib/credentials.js

@@ -106,6 +106,12 @@ 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'),
+    // Default S1-Scope for SDL requests: "<accountId>" for account scope or
+    // "<accountId>:<siteId>" for site scope. Optional. Per-call scope arguments
+    // override it; passing scope:null suppresses it entirely. SDL reads are
+    // scope-FILTERED, so this value decides which config files and dashboards a
+    // session can see at all, not merely where new ones are filed.
+    S1_SCOPE:             e('S1_SCOPE'),
   };
 }
 

package/lib/s1.js

@@ -9,6 +9,7 @@
  */
 
 import { getCreds } from './credentials.js';
+import { scopeHeaders } from './sdl.js';
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -191,7 +192,7 @@ export function pickMatchCount(result) {
 }
 
 /** Run a full LRQ PowerQuery lifecycle. Returns { columns, rows, rowCount, matchCount }. */
-export async function lrqRun(query, { startTime, endTime, hours = 24, maxRows = 5000 } = {}) {
+export async function lrqRun(query, { startTime, endTime, hours = 24, maxRows = 5000, scope } = {}) {
   const b = base();
   const tok = jwt();
 
@@ -207,12 +208,17 @@ export async function lrqRun(query, { startTime, endTime, hours = 24, maxRows =
     pq: { query, resultType: 'TABLE' },
   };
 
+  // S1-Scope applies to log reads exactly as it does to config reads: an LRQ
+  // run without the intended scope silently answers for the token default.
+  const scopeHdrs = scopeHeaders(scope);
+
   // Launch
   const launchRes = await fetch(launchUrl, {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${tok}`,
       'Content-Type': 'application/json',
+      ...scopeHdrs,
     },
     body: JSON.stringify(launchBody),
   });
@@ -230,6 +236,7 @@ export async function lrqRun(query, { startTime, endTime, hours = 24, maxRows =
   const pollHeaders = {
     Authorization: `Bearer ${tok}`,
     'Content-Type': 'application/json',
+    ...scopeHdrs,
     ...(forwardTag ? { 'X-Dataset-Query-Forward-Tag': forwardTag } : {}),
   };
 

package/lib/sdl.js

@@ -26,6 +26,50 @@ export function sdlToken() {
   return token;
 }
 
+/**
+ * Resolve the S1-Scope header value for a request.
+ *
+ * SDL objects (dashboards, saved searches, config files) are filed against the
+ * scope the request carries, and reads are filtered by it. Verified live on
+ * usea1-purple 2026-08-17, same token: `configFiles` returned 113 files at
+ * account scope (20 of them dashboards) and 4 at a site scope (all 4
+ * dashboards). A dashboard created at site scope is invisible to an
+ * account-scoped listing, so a missing header is not a neutral default, it
+ * silently changes which objects exist as far as the caller can tell.
+ *
+ * Precedence: explicit per-call scope, then S1_SCOPE from credentials. Passing
+ * `null` is NOT the same as omitting: `null` deliberately suppresses the creds
+ * default and sends no header, which is what the account-wide listing needs.
+ *
+ * Format: "<accountId>" for account scope, "<accountId>:<siteId>" for site
+ * scope. Group scope does not exist in SDL; the console silently promotes a
+ * Group selection to the Site above it.
+ */
+function resolveScope(scope) {
+  if (scope === null) return null;
+  const raw = scope !== undefined ? scope : getCreds().S1_SCOPE;
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw !== 'string') {
+    throw new Error(`S1-Scope must be a string, got ${typeof raw}. Use "<accountId>" or "<accountId>:<siteId>".`);
+  }
+  const trimmed = raw.trim();
+  if (!/^\d+(:\d+)?$/.test(trimmed)) {
+    throw new Error(
+      `Invalid S1-Scope ${JSON.stringify(trimmed)}. Expected "<accountId>" or "<accountId>:<siteId>", ` +
+      'both numeric ids. Get them from GET /web/api/v2.1/accounts and /web/api/v2.1/sites.'
+    );
+  }
+  return trimmed;
+}
+
+/** Header object carrying S1-Scope, or empty when the request is unscoped.
+ *  Exported so the LRQ path in lib/s1.js scopes identically; a second
+ *  implementation would drift. */
+export function scopeHeaders(scope) {
+  const resolved = resolveScope(scope);
+  return resolved ? { 'S1-Scope': resolved } : {};
+}
+
 function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
 function retryAfterMs(res, fallback) {
@@ -160,14 +204,15 @@ class SdlGraphqlError extends Error {
  *   3. Return a payload carrying neither `data` nor `errors`.
  *
  * `readOnly` opts into status-based retry; only pass it for queries.
+ * `scope` sets the S1-Scope header; see resolveScope for precedence.
  */
-async function sdlGraphql(opname, query, variables, { readOnly = false } = {}) {
+async function sdlGraphql(opname, query, variables, { readOnly = false, scope } = {}) {
   const body = { query };
   if (variables) body.variables = variables;
   const payload = await sdlFetch(
     'POST',
     `/v2/graphql?opname=${encodeURIComponent(opname)}`,
-    { body, allowRetry: readOnly }
+    { body, allowRetry: readOnly, extraHeaders: scopeHeaders(scope) }
   );
 
   if (typeof payload !== 'object' || payload === null) {
@@ -211,13 +256,15 @@ function matchesName(file, name) {
   return normaliseName(file?.name) === normaliseName(name);
 }
 
-/** Every config file on the tenant, including udoId-addressed dashboards. */
-export async function configFiles() {
+/** Every config file visible at `scope`, including udoId-addressed dashboards.
+ *  This listing IS scope-filtered: a site-scoped dashboard does not appear in an
+ *  account-scoped listing and vice versa. */
+export async function configFiles({ scope } = {}) {
   const data = await sdlGraphql(
     'getConfigurationFiles',
     `query getConfigurationFiles { configFiles { ${CONFIG_FIELDS} } }`,
     undefined,
-    { readOnly: true }
+    { readOnly: true, scope }
   );
   return data?.configFiles ?? [];
 }
@@ -239,15 +286,15 @@ export async function configFiles() {
  * 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 }) {
+export async function configFile({ name, udoId, scope }) {
   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 });
+      ? await sdlGraphql('configFile', `query f($udoId: ID!) { configFile(udoId: $udoId) { ${CONFIG_FIELDS} content } }`, { udoId: safeUdoId }, { readOnly: true, scope })
+      : await sdlGraphql('configFile', `query f($id: ID!) { configFile(id: $id) { ${CONFIG_FIELDS} content } }`, { id: name }, { readOnly: true, scope });
     return data?.configFile ?? null;
   } catch (err) {
     // Only a GraphQL-layer error can mean "absent". A transport failure whose
@@ -261,9 +308,13 @@ export async function configFile({ name, udoId }) {
     // 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.
+    // Same scope as the failed lookup. Disambiguating against a DIFFERENT
+    // scope's listing would report a site-scoped file as absent purely because
+    // the listing was taken at account scope, which is the exact false-negative
+    // class this branch exists to remove.
     let all;
     try {
-      all = await configFiles();
+      all = await configFiles({ scope });
     } catch (listErr) {
       err.message += ` (absence check failed: ${listErr.message})`;
       throw err;
@@ -282,13 +333,16 @@ export async function configFile({ name, udoId }) {
  *   - 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 }) {
+export async function putConfigFile({ name, udoId, content, expectedVersion, scope }) {
   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();
+    // Scoped to match the write. An account-scoped listing would not see a
+    // same-named site-scoped dashboard, so the guard has to look where the
+    // write is going, not where the token defaults.
+    const all = await configFiles({ scope });
     // 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) {
@@ -315,10 +369,10 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
   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 })
+        { udoId: assertSafeUdoId(udoId), content, expectedVersion }, { scope })
     : await sdlGraphql('addConfigFile',
         `mutation f($name: String, $content: String!, $expectedVersion: Long) { addConfigFile(name: $name, content: $content, expectedVersion: $expectedVersion) { ${CONFIG_FIELDS} } }`,
-        { name, content, expectedVersion });
+        { name, content, expectedVersion }, { scope });
   return data?.addConfigFile ?? null;
 }
 
@@ -327,21 +381,21 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
  * 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 }) {
+export async function deleteConfigFile({ name, udoId, expectedVersion, scope }) {
   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 })
+        { udoId: assertSafeUdoId(udoId), expectedVersion }, { scope })
     : await sdlGraphql('deleteConfigFile',
         'mutation f($id: ID, $expectedVersion: Long) { deleteConfigFile(id: $id, expectedVersion: $expectedVersion) { udoId } }',
-        { id: name, expectedVersion });
+        { id: name, expectedVersion }, { scope });
 
   // 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 });
+  const still = await configFile({ name, udoId, scope });
   if (still) {
     throw new Error(
       `deleteConfigFile: ${udoId ? `udoId ${udoId}` : name} still exists after the delete mutation ` +
@@ -357,13 +411,275 @@ export async function deleteConfigFile({ name, udoId, expectedVersion }) {
 // exist" decision. The GraphQL operations above cover every namespace,
 // including parsers, lookups, datatables and /automaticLookups.
 
+// ─── Dashboard lifecycle (dashboardsV2, GraphQL) ──────────────────────────────
+//
+// A SECOND, HIGHER-LEVEL SURFACE on the same `POST /sdl/v2/graphql` endpoint.
+// This is what the console itself drives; captured from live console traffic on
+// usea1-purple 2026-08-17 (280 requests, 23 operations).
+//
+// Relationship to the config-file layer above:
+//
+//   dashboardsV2       dashboard-aware: name, description, tabs, access/sharing,
+//                      createdBy/updatedBy, isBuiltIn/isEditable. Create takes
+//                      the whole dashboard JSON as one `config` string.
+//   configFiles        the raw file underneath, addressed by udoId. Same object,
+//                      no sharing or authorship metadata, `content` is the JSON.
+//
+// The `id` in dashboardsV2 IS the `udoId` in configFiles. Verified: dashboard
+// "meta1" is id 6999000578736128 in getDashboardV2 and udoId 6999000578736128
+// / name "/dashboards/meta1" in configFile.
+//
+// WHY THIS EXISTS: creating a dashboard through addConfigFile(name:) files it at
+// the request's scope but gives no way to share it elsewhere, and the console's
+// own create path is createDashboardV2. Site-level lifecycle needs both this and
+// shareResource, which is the ONLY operation that takes an explicit scope target
+// rather than inferring one from the request header.
+//
+// VERSION FIELDS DIFFER, do not cross them. getDashboardV2 returns
+// `version: ""` (a display string, empty in practice); configFile returns
+// `version: 215771284` (the numeric CAS token). Only the configFile value is
+// valid as expectedVersion.
+
+const DASHBOARD_SUMMARY_FIELDS = 'id name description configType access { public users owner }';
+
+/** Every dashboard visible at `scope`, with sharing metadata. Prefer this over
+ *  configFiles({pathPrefix:'/dashboards/'}) when you need owner or access. */
+export async function listDashboards({ scope } = {}) {
+  const data = await sdlGraphql(
+    'GetDashboardNames',
+    `query GetDashboardNames { dashboardsV2 { ${DASHBOARD_SUMMARY_FIELDS} } }`,
+    undefined,
+    { readOnly: true, scope }
+  );
+  return data?.dashboardsV2 ?? [];
+}
+
+/**
+ * Read one dashboard by id (preferred) or name, including its tabs.
+ * Returns null when it does not exist at `scope`.
+ *
+ * `tabs[].graphs` / `.parameters` / `.filters` / `.options` come back as JSON
+ * STRINGS, not objects; the console parses them client-side. Callers that want
+ * structure must JSON.parse each one.
+ *
+ * ABSENCE HANDLING mirrors configFile deliberately. The live capture only shows
+ * a successful read, so it is not established whether a missing dashboard comes
+ * back as `data.getDashboardV2 = null` or as a GraphQL error. Both are treated
+ * as absence, disambiguated against the dashboard listing. Assuming only the
+ * null form is what broke every `sdl_delete_file` in 1.3.2: the confirming
+ * re-read threw on precisely the success path. A transport-layer error is still
+ * rethrown, so a proxy page containing "not found" can never be read as absence.
+ */
+export async function getDashboard({ id, name, scope }) {
+  if (!id && !name) throw new Error('getDashboard requires either id or name');
+  const safeId = id ? assertSafeUdoId(id) : undefined;
+  try {
+    const data = await sdlGraphql(
+      'GetDashboardConfigV2',
+      `query GetDashboardConfigV2($id: ID, $dashboardName: String) {
+         getDashboardV2(id: $id, dashboardName: $dashboardName, resolveParameters: true) {
+           id name description configType duration isBuiltIn isEditable version
+           access { public users owner }
+           tabs { tabName parameters graphs filters options }
+           createdAt createdBy updatedAt updatedBy
+         }
+       }`,
+      { id: safeId, dashboardName: name },
+      { readOnly: true, scope }
+    );
+    return data?.getDashboardV2 ?? null;
+  } catch (err) {
+    if (!err.graphql) throw err;
+    let all;
+    try {
+      all = await listDashboards({ scope });
+    } catch (listErr) {
+      err.message += ` (absence check failed: ${listErr.message})`;
+      throw err;
+    }
+    const present = safeId
+      ? all.some(d => String(d.id) === safeId)
+      : all.some(d => normaliseName(d.name) === normaliseName(name));
+    if (!present) return null;
+    throw err;
+  }
+}
+
+/**
+ * Create a dashboard from a full dashboard-JSON config, at `scope`.
+ *
+ * This is the console's own create path and it accepts the complete dashboard
+ * document (configType, duration, description, tabs[]) as ONE string. That is
+ * the important difference from the UI's "new dashboard then paste JSON" flow,
+ * which starts from a `{graphs: []}` stub: pasting after the stub instead of
+ * replacing it produces `{graphs: []}{...}` and the server rejects it with
+ * "Content is invalid json" / "Additional text after JSON object". Going
+ * through this function cannot hit that class of error.
+ *
+ * DUPLICATE NAMES ARE ALLOWED HERE, unlike putConfigFile. The console itself
+ * creates "<name> - Copy" siblings, and shareResource addresses dashboards by
+ * id, so duplicate names are not the footgun they are for name-addressed
+ * config-file writes. Set `failIfNameExists` to opt into the stricter
+ * behaviour; it costs one extra listing call.
+ */
+export async function createDashboard({ name, config, isPublic = false, scope, failIfNameExists = false }) {
+  if (!name || typeof name !== 'string') throw new Error('createDashboard requires a name');
+  if (typeof config !== 'string' || !config.trim()) {
+    throw new Error('createDashboard requires config as a JSON string (the full dashboard document).');
+  }
+  // Fail before the mutation rather than filing a broken dashboard the console
+  // then renders as an empty shell.
+  try {
+    JSON.parse(config);
+  } catch (e) {
+    throw new Error(
+      `createDashboard: config is not valid JSON (${e.message}). ` +
+      'If this came from the console\'s JSON editor, check for a leading "{graphs: []}" stub: ' +
+      'the new document must REPLACE it, not follow it.'
+    );
+  }
+
+  if (failIfNameExists) {
+    const existing = (await listDashboards({ scope })).filter(d => normaliseName(d.name) === normaliseName(name));
+    if (existing.length) {
+      throw new Error(
+        `createDashboard: ${existing.length} dashboard(s) named "${name}" already exist at this scope ` +
+        `(ids: ${existing.map(d => d.id).join(', ')}). Pass failIfNameExists:false to create a sibling anyway.`
+      );
+    }
+  }
+
+  const data = await sdlGraphql(
+    'CreateDashboard',
+    `mutation CreateDashboard($dashboardName: String!, $config: String, $public: Boolean) {
+       createDashboardV2(dashboardName: $dashboardName, config: $config, public: $public) { id name }
+     }`,
+    { dashboardName: name, config, public: isPublic },
+    { scope }
+  );
+  const created = data?.createDashboardV2 ?? null;
+  if (!created?.id) {
+    throw new SdlGraphqlError('createDashboard: mutation returned no id, so the dashboard was not created.');
+  }
+  return created;
+}
+
+/**
+ * Share a dashboard to scopes and/or users. THE ONLY OPERATION THAT TAKES AN
+ * EXPLICIT SCOPE TARGET; everything else infers scope from the S1-Scope header.
+ *
+ * `scopes` entries are {scopeType, scopeId, operation}:
+ *   scopeType  'site' | 'account' | 'global'
+ *   scopeId    the numeric id from /web/api/v2.1/sites or /accounts
+ *   operation  'ADD' | 'REMOVE'
+ *
+ * `scope` (the option, not the array) is still the header for the CALL, i.e.
+ * where you are standing when you share. It is independent of the targets.
+ */
+const VALID_SCOPE_TYPES = new Set(['site', 'account', 'global']);
+const VALID_SCOPE_OPS = new Set(['ADD', 'REMOVE']);
+
+export async function shareDashboard({ id, scopes = [], users = [], scope }) {
+  if (!id) throw new Error('shareDashboard requires the dashboard id');
+  if (!Array.isArray(scopes) || !Array.isArray(users)) {
+    throw new Error('shareDashboard: scopes and users must both be arrays.');
+  }
+  if (!scopes.length && !users.length) {
+    throw new Error('shareDashboard: pass at least one scope or user, otherwise the call is a no-op.');
+  }
+  // Validate up front: the server accepts a malformed entry and silently shares
+  // nothing, which reads as success.
+  const normalisedScopes = scopes.map((s, i) => {
+    const type = String(s?.scopeType ?? '').toLowerCase();
+    const op = String(s?.operation ?? 'ADD').toUpperCase();
+    if (!VALID_SCOPE_TYPES.has(type)) {
+      throw new Error(`shareDashboard: scopes[${i}].scopeType must be one of ${[...VALID_SCOPE_TYPES].join(', ')} (got ${JSON.stringify(s?.scopeType)}).`);
+    }
+    if (!VALID_SCOPE_OPS.has(op)) {
+      throw new Error(`shareDashboard: scopes[${i}].operation must be ADD or REMOVE (got ${JSON.stringify(s?.operation)}).`);
+    }
+    if (type !== 'global' && !/^\d+$/.test(String(s?.scopeId ?? ''))) {
+      throw new Error(`shareDashboard: scopes[${i}].scopeId must be a numeric id for scopeType "${type}" (got ${JSON.stringify(s?.scopeId)}).`);
+    }
+    return { scopeType: type, scopeId: String(s.scopeId), operation: op };
+  });
+
+  const data = await sdlGraphql(
+    'ShareDashboard',
+    `mutation ShareDashboard($id: ID!, $users: [UserSharingCommand], $scopes: [ScopeSharingCommand]) {
+       shareResource(id: $id, users: $users, scopes: $scopes) { id name }
+     }`,
+    { id: assertSafeUdoId(id), users, scopes: normalisedScopes },
+    { scope }
+  );
+  const shared = data?.shareResource ?? null;
+  if (!shared?.id) {
+    throw new SdlGraphqlError('shareDashboard: shareResource returned no id, so nothing was shared.');
+  }
+  return { status: 'success', dashboard: { id: String(shared.id), name: shared.name }, scopes: normalisedScopes, users };
+}
+
+/**
+ * Replace the panel layout of ONE tab. `graphs` is a JSON string shaped
+ * `{"graphs":[...]}` (note the wrapper key; the response echoes a bare array).
+ * Use this for incremental panel edits; use createDashboard for a whole document.
+ */
+export async function saveDashboardLayout({ id, name, tabName, graphs, options, scope }) {
+  if (!id && !name) throw new Error('saveDashboardLayout requires either id or name');
+  if (typeof graphs !== 'string' || !graphs.trim()) {
+    throw new Error('saveDashboardLayout requires graphs as a JSON string, shaped {"graphs":[...]}.');
+  }
+  try {
+    const parsed = JSON.parse(graphs);
+    if (!parsed || !Array.isArray(parsed.graphs)) {
+      throw new Error('missing the top-level "graphs" array');
+    }
+  } catch (e) {
+    throw new Error(`saveDashboardLayout: graphs is not a valid {"graphs":[...]} JSON string (${e.message}).`);
+  }
+  const data = await sdlGraphql(
+    'SaveDashboardLayout',
+    `mutation SaveDashboardLayout($id: ID, $dashboardName: String, $graphs: String, $options: String, $tabName: String) {
+       saveDashboardLayout(id: $id, dashboardName: $dashboardName, graphs: $graphs, options: $options, tabName: $tabName) { graphs options }
+     }`,
+    { id: id ? assertSafeUdoId(id) : undefined, dashboardName: name, graphs, options, tabName },
+    { scope }
+  );
+  return data?.saveDashboardLayout ?? null;
+}
+
+/**
+ * Delete a dashboard by id or name. `deleteDashboard` returns a bare boolean,
+ * so per the house rule the removal is confirmed by re-reading rather than
+ * trusted from the mutation response.
+ */
+export async function deleteDashboard({ id, name, scope }) {
+  if (!id && !name) throw new Error('deleteDashboard requires either id or name');
+  const data = await sdlGraphql(
+    'DeleteDashboard',
+    'mutation DeleteDashboard($id: ID, $dashboardName: String) { deleteDashboard(id: $id, dashboardName: $dashboardName) }',
+    { id: id ? assertSafeUdoId(id) : undefined, dashboardName: name },
+    { scope }
+  );
+  const reported = data?.deleteDashboard;
+
+  const still = await getDashboard({ id, name, scope });
+  if (still) {
+    throw new Error(
+      `deleteDashboard: ${id ? `id ${id}` : name} still exists after the delete mutation ` +
+      `(mutation returned ${JSON.stringify(reported)}). Nothing was removed.`
+    );
+  }
+  return { status: 'success', deleted: id ? { id: String(id) } : { name }, raw: reported ?? null };
+}
+
 // ─── 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.
 
 /** POST /api/query: retrieve raw event JSON for schema discovery.
  *  Returns { matches: [{ timestamp, message, attributes }] }. */
-export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime } = {}) {
+export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime, scope } = {}) {
   const body = {
     queryType: 'log',
     filter,
@@ -373,5 +689,5 @@ export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime
   if (endTime) body.endTime = endTime;
   // 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 });
+  return sdlFetch('POST', '/api/query', { body, allowRetry: true, extraHeaders: scopeHeaders(scope) });
 }

package/lib/server-core.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmoses-s1/s1-secops-mcp",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "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/scripts/regen-readme-tools-table.mjs

@@ -44,6 +44,13 @@ const TOOL_SKILL = {
   sdl_get_file:                  'sdl-api / sdl-dashboard / sdl-log-parser',
   sdl_put_file:                  'sdl-api / sdl-dashboard / sdl-log-parser',
   sdl_delete_file:               'sdl-api',
+  // SDL dashboard lifecycle (dashboardsV2)
+  sdl_list_dashboards:           'sdl-api / sdl-dashboard',
+  sdl_get_dashboard:             'sdl-api / sdl-dashboard',
+  sdl_create_dashboard:          'sdl-api / sdl-dashboard',
+  sdl_share_dashboard:           'sdl-api / sdl-dashboard',
+  sdl_save_dashboard_layout:     'sdl-api / sdl-dashboard',
+  sdl_delete_dashboard:          'sdl-api / sdl-dashboard',
   hec_ingest:                    'sdl-api / sdl-log-parser',
   // Hyperautomation
   ha_list_workflows:             'hyperautomation',

package/scripts/smoke-test-http.sh

@@ -5,7 +5,7 @@
 # Exercises the public contract end-to-end:
 #   1. healthz returns 200 (no auth)
 #   2. initialize returns the expected protocol version and server info
-#   3. tools/list returns 26 tools
+#   3. tools/list returns 32 tools
 #   4. tools/call s1_api_get works (uses /agents/count as a cheap probe)
 #   5. bad bearer returns HTTP 401
 #   6. unknown method returns JSON-RPC error -32601 inside a 200 envelope
@@ -81,7 +81,7 @@ echo "=== 3. tools/list count ==="
 TOOLS_COUNT=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" \
   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' |
   jq '.result.tools | length')
-[[ "$TOOLS_COUNT" == "26" ]] && pass "tools/list returned 26 tools" || fail "tools/list returned $TOOLS_COUNT"
+[[ "$TOOLS_COUNT" == "32" ]] && pass "tools/list returned 32 tools" || fail "tools/list returned $TOOLS_COUNT"
 
 echo
 echo "=== 4. tools/call s1_api_get on /agents/count ==="

package/scripts/test-mac.sh

@@ -128,8 +128,8 @@ STDIO_REPLY="$(printf '%s\n%s\n' \
   node index.js 2>/dev/null)"
 
 TOOL_COUNT="$(echo "$STDIO_REPLY" | tail -n 1 | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
-if [[ "$TOOL_COUNT" == "26" ]]; then
-  pass "stdio tools/list returned 26 tools"
+if [[ "$TOOL_COUNT" == "32" ]]; then
+  pass "stdio tools/list returned 32 tools"
 else
   fail "stdio tools/list returned $TOOL_COUNT (expected 26)" "$STDIO_REPLY"
 fi
@@ -159,8 +159,8 @@ HTTP_REPLY="$(curl -sf -X POST "http://127.0.0.1:$PORT/mcp" \
   -H 'Content-Type: application/json' \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
 HTTP_COUNT="$(echo "$HTTP_REPLY" | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
-if [[ "$HTTP_COUNT" == "26" ]]; then
-  pass "HTTP tools/list returned 26 tools"
+if [[ "$HTTP_COUNT" == "32" ]]; then
+  pass "HTTP tools/list returned 32 tools"
 else
   fail "HTTP tools/list returned $HTTP_COUNT" "$HTTP_REPLY"
 fi

package/tools/powerquery.js

@@ -23,15 +23,19 @@ export const tools = [
           description: 'Lookback window in hours (default 24). Increase to 168 (7d) if the last 24h had low volume.',
           default: 24,
         },
+        scope: {
+          type: 'string',
+          description: 'Optional S1-Scope, "<accountId>" or "<accountId>:<siteId>". LOG READS ARE SCOPE-FILTERED just like config reads, so this changes which events the query can see. Use it to hunt within one site, and to validate a site-scoped dashboard panel against the same boundary the dashboard will see. Omit to use S1_SCOPE from credentials.json, or the token default when that is unset.',
+        },
       },
       required: [],
     },
-    async handler({ hours = 24 } = {}) {
+    async handler({ hours = 24, scope } = {}) {
       const query = `| group UniqueDataSourceNames = array_agg_distinct(dataSource.name),
         UniqueVendors = array_agg_distinct(dataSource.vendor),
         UniqueCategories = array_agg_distinct(dataSource.category)
 | limit 1000`;
-      const result = await lrqRun(query, { hours });
+      const result = await lrqRun(query, { hours, scope });
       return JSON.stringify(result, null, 2);
     },
   },
@@ -65,11 +69,15 @@ export const tools = [
           description: 'Client-side cap on rows returned (default 1000). Not a hard backend limit: the LRQ engine returns as many rows as the query\'s own `| limit N` asks for (live-verified 2026-07-29: a `| limit 20000` query returned 20,000 rows in one response). Raise this to match a large `| limit`; the real ceiling is LRQ response size, not a fixed 5000.',
           default: 1000,
         },
+        scope: {
+          type: 'string',
+          description: 'Optional S1-Scope, "<accountId>" or "<accountId>:<siteId>". LOG READS ARE SCOPE-FILTERED just like config reads, so this changes which events the query can see. Use it to hunt within one site, and to validate a site-scoped dashboard panel against the same boundary the dashboard will see. Omit to use S1_SCOPE from credentials.json, or the token default when that is unset.',
+        },
       },
       required: ['query'],
     },
-    async handler({ query, startTime, endTime, hours = 24, maxRows = 1000 }) {
-      const result = await lrqRun(query, { startTime, endTime, hours, maxRows });
+    async handler({ query, startTime, endTime, hours = 24, maxRows = 1000, scope }) {
+      const result = await lrqRun(query, { startTime, endTime, hours, maxRows, scope });
       return JSON.stringify(result, null, 2);
     },
   },
@@ -95,17 +103,21 @@ export const tools = [
           description: 'Lookback string or ISO date, e.g. "24h", "7d", or "2026-04-20T00:00:00Z" (default "24h").',
           default: '24h',
         },
+        scope: {
+          type: 'string',
+          description: 'Optional S1-Scope, "<accountId>" or "<accountId>:<siteId>". Schema discovery is scope-filtered: a source present at one site may be absent at another, so discover at the scope you will query.',
+        },
       },
       required: ['dataSourceName'],
     },
-    async handler({ dataSourceName, maxEvents = 5, startTime = '24h' }) {
+    async handler({ dataSourceName, maxEvents = 5, startTime = '24h', scope }) {
       // Escape backslashes first, then single quotes, to keep tenant-defined
       // source names from breaking (or altering) the V1 filter expression.
       // Quote-only escaping let a trailing backslash neutralise the added
       // escape (e.g. name\' -> \\' which re-opens the string).
       const safeName = String(dataSourceName).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
       const filter = `dataSource.name=='${safeName}'`;
-      const result = await v1Query(filter, { maxCount: Math.min(maxEvents, 50), startTime });
+      const result = await v1Query(filter, { maxCount: Math.min(maxEvents, 50), startTime, scope });
 
       const matches = result.matches || [];
       if (matches.length === 0) {

package/tools/sdl-api.js

@@ -1,20 +1,34 @@
 /**
  * SDL API tools: sdl-api, sdl-dashboard, sdl-log-parser skills
  *
- * Tools:
- *   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)
+ * Config-file tools (raw SDL config layer):
+ *   sdl_list_files            List every config file visible at a scope
+ *   sdl_get_file              Get file content and version, by path or udoId
+ *   sdl_put_file              Deploy or update a config file (optimistic locking)
+ *   sdl_delete_file           Delete a config file
  *
- * All four config-file tools run on `POST /sdl/v2/graphql`. The legacy REST
+ * Dashboard lifecycle tools (dashboardsV2, the console's own surface):
+ *   sdl_list_dashboards       List dashboards with owner and sharing metadata
+ *   sdl_get_dashboard         Read one dashboard including its tabs
+ *   sdl_create_dashboard      Create from a full dashboard-JSON config
+ *   sdl_share_dashboard       Share to a site / account / global scope
+ *   sdl_save_dashboard_layout Replace the panel layout of one tab
+ *   sdl_delete_dashboard      Delete a dashboard
+ *
+ * Ingest:
+ *   hec_ingest                Ingest raw logs/events into SDL via HEC
+ *
+ * Everything except hec_ingest runs 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 { configFiles, configFile, putConfigFile, deleteConfigFile } from '../lib/sdl.js';
+import {
+  configFiles, configFile, putConfigFile, deleteConfigFile,
+  listDashboards, getDashboard, createDashboard, shareDashboard,
+  saveDashboardLayout, deleteDashboard,
+} from '../lib/sdl.js';
 import { hecIngest } from '../lib/hec.js';
 
 const UDOID_NOTE =
@@ -24,11 +38,25 @@ const UDOID_NOTE =
   'udoId assignment is by namespace: only /dashboards/ files have one, /lookups/, /datatables/, ' +
   '/logParsers/ and /automaticLookups are all name-addressed with udoId null.';
 
+const SCOPE_NOTE =
+  'SDL config objects are filed against the scope of the request and reads are FILTERED by it, so this ' +
+  'argument changes which objects exist as far as the caller can tell. Verified live: the same listing ' +
+  'returned 113 files at account scope and 4 at a site scope. Format "<accountId>" for account scope or ' +
+  '"<accountId>:<siteId>" for site scope; ids come from GET /web/api/v2.1/accounts and /sites. Omit to ' +
+  'use S1_SCOPE from credentials.json, or the token default when that is unset. If an object you expect ' +
+  'is missing, re-check at the scope it was created in before concluding it is gone.';
+
+/** Shared scope property for every tool schema. */
+const scopeProp = {
+  type: 'string',
+  description: `Optional S1-Scope, e.g. "2046190533732727925:2547662415802335157". ${SCOPE_NOTE}`,
+};
+
 export const tools = [
   // ─── sdl_list_files ───────────────────────────────────────────────────────
   {
     name: 'sdl_list_files',
-    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.`,
+    description: `List every configuration file visible at the given scope 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. THIS LISTING IS SCOPE-FILTERED: ${SCOPE_NOTE} Never conclude a file is absent from a listing produced any other way; the legacy REST listing omits ~350 dashboards.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -36,13 +64,14 @@ export const tools = [
           type: 'string',
           description: 'Optional filter, e.g. "/dashboards/" or "/logParsers/". Applied client-side to the full listing.',
         },
+        scope: scopeProp,
       },
       required: [],
     },
-    async handler({ pathPrefix } = {}) {
-      let files = await configFiles();
+    async handler({ pathPrefix, scope } = {}) {
+      let files = await configFiles({ scope });
       if (pathPrefix) files = files.filter(f => (f.name || '').startsWith(pathPrefix));
-      return JSON.stringify({ count: files.length, files }, null, 2);
+      return JSON.stringify({ count: files.length, scope: scope ?? null, files }, null, 2);
     },
   },
 
@@ -61,15 +90,17 @@ export const tools = [
           type: 'string',
           description: 'Dashboard udoId, e.g. "3559330396332032". Get it from sdl_list_files. Required for /dashboards/ files.',
         },
+        scope: scopeProp,
       },
       required: [],
     },
-    async handler({ path, udoId }) {
-      const result = await configFile({ name: path, udoId });
+    async handler({ path, udoId, scope }) {
+      const result = await configFile({ name: path, udoId, scope });
       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.',
+          scope: scope ?? null,
+          hint: 'No file at that address AT THIS SCOPE. Two things to check: (1) if this is a dashboard it is udoId-addressed, run sdl_list_files with pathPrefix "/dashboards/" and retry with its udoId; (2) the file may exist at a different scope, a site-scoped dashboard is invisible from account scope, so retry with the scope it was created in.',
         }, null, 2);
       }
       return JSON.stringify(result, null, 2);
@@ -99,11 +130,12 @@ export const tools = [
           type: 'number',
           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.',
         },
+        scope: scopeProp,
       },
       required: ['content'],
     },
-    async handler({ path, udoId, content, expectedVersion }) {
-      const result = await putConfigFile({ name: path, udoId, content, expectedVersion });
+    async handler({ path, udoId, content, expectedVersion, scope }) {
+      const result = await putConfigFile({ name: path, udoId, content, expectedVersion, scope });
       return JSON.stringify(result, null, 2);
     },
   },
@@ -127,11 +159,147 @@ export const tools = [
           type: 'number',
           description: 'Current file version for optimistic locking (from sdl_get_file). Strongly recommended.',
         },
+        scope: scopeProp,
+      },
+      required: [],
+    },
+    async handler({ path, udoId, expectedVersion, scope }) {
+      const result = await deleteConfigFile({ name: path, udoId, expectedVersion, scope });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_list_dashboards ──────────────────────────────────────────────────
+  {
+    name: 'sdl_list_dashboards',
+    description: `List dashboards visible at the given scope via the GraphQL dashboardsV2 query, returning {id, name, description, configType, access:{public, users, owner}} each. Prefer this over sdl_list_files when you need the owner or the sharing state; use sdl_list_files when you need the config-file version for optimistic locking. The "id" here IS the "udoId" in sdl_list_files, they address the same object. ${SCOPE_NOTE}`,
+    inputSchema: {
+      type: 'object',
+      properties: { scope: scopeProp },
+      required: [],
+    },
+    async handler({ scope } = {}) {
+      const dashboards = await listDashboards({ scope });
+      return JSON.stringify({ count: dashboards.length, scope: scope ?? null, dashboards }, null, 2);
+    },
+  },
+
+  // ─── sdl_get_dashboard ────────────────────────────────────────────────────
+  {
+    name: 'sdl_get_dashboard',
+    description: `Read one dashboard including its tabs, description, duration, sharing and authorship, via getDashboardV2. Address by id (preferred) or name. NOTE tabs[].graphs, .parameters, .filters and .options come back as JSON STRINGS, not objects; parse each one to inspect panels. The "version" field here is a display string and is usually empty; it is NOT the optimistic-locking token, use sdl_get_file for the numeric version. Returns status notFound when the dashboard does not exist at this scope. ${SCOPE_NOTE}`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Dashboard id, e.g. "6994516145065984". Same value as udoId in sdl_list_files.' },
+        name: { type: 'string', description: 'Dashboard display name, e.g. "Metacortex Site". Use when you do not have the id; ambiguous if duplicates exist.' },
+        scope: scopeProp,
+      },
+      required: [],
+    },
+    async handler({ id, name, scope }) {
+      const result = await getDashboard({ id, name, scope });
+      if (!result) {
+        return JSON.stringify({
+          status: 'notFound',
+          scope: scope ?? null,
+          hint: 'No dashboard at that address AT THIS SCOPE. A site-scoped dashboard is invisible from account scope and vice versa; retry with the scope it was created in, or run sdl_list_dashboards at that scope to confirm.',
+        }, null, 2);
+      }
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_create_dashboard ─────────────────────────────────────────────────
+  {
+    name: 'sdl_create_dashboard',
+    description: `Create a dashboard from a complete dashboard-JSON document via createDashboardV2, filed at the given scope. THIS IS THE PREFERRED WAY TO DEPLOY A NEW DASHBOARD: it accepts the whole document (configType, duration, description, tabs[]) in one call, unlike sdl_put_file which writes the raw config file. It also avoids the console's stub-append trap, where creating an empty dashboard in the UI and pasting JSON after the existing "{graphs: []}" stub yields "Content is invalid json / Additional text after JSON object" and leaves an empty dashboard behind. To deploy to a SITE, either pass scope as "<accountId>:<siteId>" here, or create at account scope and then use sdl_share_dashboard. Duplicate names ARE allowed (the console itself makes "<name> - Copy" siblings); set failIfNameExists to refuse instead. ${SCOPE_NOTE}`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Dashboard display name, e.g. "Metacortex Site Replica".' },
+        config: { type: 'string', description: 'The full dashboard JSON document as a string: {"configType":"TABBED","duration":"24h","description":"...","tabs":[...]}. Validated as JSON before the mutation is sent.' },
+        isPublic: { type: 'boolean', description: 'Share with all users in scope (the console\'s "Public" badge). Default false.' },
+        failIfNameExists: { type: 'boolean', description: 'Refuse if a dashboard of this name already exists at this scope. Default false, which permits siblings. Costs one extra listing call.' },
+        scope: scopeProp,
+      },
+      required: ['name', 'config'],
+    },
+    async handler({ name, config, isPublic, failIfNameExists, scope }) {
+      const result = await createDashboard({ name, config, isPublic, failIfNameExists, scope });
+      return JSON.stringify({ status: 'created', scope: scope ?? null, dashboard: result }, null, 2);
+    },
+  },
+
+  // ─── sdl_share_dashboard ──────────────────────────────────────────────────
+  {
+    name: 'sdl_share_dashboard',
+    description: 'Share (or unshare) a dashboard to one or more scopes and/or users via the shareResource mutation. THIS IS THE ONLY SDL OPERATION THAT TAKES AN EXPLICIT SCOPE TARGET; every other operation infers scope from the request header. Use it to push an account-scoped dashboard down to a specific site without recreating it, which is how site-level deployment is done when the calling token sits at account scope. Note the two different scope arguments: the "scopes" array is WHERE THE DASHBOARD GOES, while "scope" is the header for this call, i.e. where you are standing when you share.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Dashboard id from sdl_list_dashboards or sdl_create_dashboard.' },
+        scopes: {
+          type: 'array',
+          description: 'Share targets. Each entry is {scopeType, scopeId, operation}: scopeType is "site" | "account" | "global"; scopeId is the numeric id from GET /web/api/v2.1/sites or /accounts (not required for global); operation is "ADD" or "REMOVE" (default ADD). Example: [{"scopeType":"site","scopeId":"2547662415802335157","operation":"ADD"}].',
+          items: {
+            type: 'object',
+            properties: {
+              scopeType: { type: 'string', enum: ['site', 'account', 'global'] },
+              scopeId: { type: 'string' },
+              operation: { type: 'string', enum: ['ADD', 'REMOVE'] },
+            },
+            required: ['scopeType'],
+          },
+        },
+        users: { type: 'array', description: 'Optional user share targets, same command shape as the console sends. Pass [] when sharing only to scopes.', items: { type: 'object' } },
+        scope: scopeProp,
+      },
+      required: ['id'],
+    },
+    async handler({ id, scopes, users, scope }) {
+      const result = await shareDashboard({ id, scopes, users, scope });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_save_dashboard_layout ────────────────────────────────────────────
+  {
+    name: 'sdl_save_dashboard_layout',
+    description: 'Replace the panel layout of ONE tab of a dashboard via saveDashboardLayout. Use for incremental panel edits (repositioning, adding or removing a panel on a single tab); use sdl_create_dashboard for a whole new document, or sdl_put_file with expectedVersion to rewrite an existing dashboard\'s full config. The graphs argument is a JSON string shaped {"graphs":[...]} including the wrapper key, even though the response echoes a bare array.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Dashboard id.' },
+        name: { type: 'string', description: 'Dashboard display name, as an alternative to id.' },
+        tabName: { type: 'string', description: 'Exact tab name to replace, e.g. "2. Metacortex operations". Must match an existing tab.' },
+        graphs: { type: 'string', description: 'JSON string shaped {"graphs":[{panel},...]}. Validated before sending; the top-level "graphs" array is required.' },
+        options: { type: 'string', description: 'Optional tab options as a JSON string, e.g. "{}".' },
+        scope: scopeProp,
+      },
+      required: ['graphs', 'tabName'],
+    },
+    async handler({ id, name, tabName, graphs, options, scope }) {
+      const result = await saveDashboardLayout({ id, name, tabName, graphs, options, scope });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_delete_dashboard ─────────────────────────────────────────────────
+  {
+    name: 'sdl_delete_dashboard',
+    description: `Delete a dashboard by id or name via the deleteDashboard mutation. Deletion is permanent. The mutation returns a bare boolean, so this tool re-reads the dashboard afterwards and only reports success once it is confirmed gone. Equivalent to sdl_delete_file by udoId; prefer this one when you are working through the dashboard surface. ${SCOPE_NOTE}`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Dashboard id to delete.' },
+        name: { type: 'string', description: 'Dashboard name to delete, as an alternative to id. Ambiguous if duplicates exist; prefer id.' },
+        scope: scopeProp,
       },
       required: [],
     },
-    async handler({ path, udoId, expectedVersion }) {
-      const result = await deleteConfigFile({ name: path, udoId, expectedVersion });
+    async handler({ id, name, scope }) {
+      const result = await deleteDashboard({ id, name, scope });
       return JSON.stringify(result, null, 2);
     },
   },