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

package/CHANGELOG.md

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

package/README.md

@@ -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 |
@@ -43,10 +49,12 @@ See **[deploy/README.md](./deploy/README.md)** for the full deployment walkthrou
 <!-- END AUTO-GENERATED TOOLS TABLE -->
 
 **2 resources:**
+
 - `sentinelone://soc-context`: `CLAUDE.md`, the Principal SOC Analyst operating instructions.
 - `sentinelone://credentials-status`: which credentials are configured and which API surfaces are available.
 
 **2 prompts:**
+
 - `soc_analyst`: embeds `CLAUDE.md` as a system prompt; call at session start.
 - `session_init`: structured init: enumerate sources + triage alerts in parallel.
 
@@ -65,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.2"],
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.4"],
       "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"
       }
     }
   }
@@ -204,7 +212,7 @@ If neither env var is set, HTTP transport runs **without** authentication and th
 
 Every authenticated HTTP request emits a structured stderr line that systemd captures via journald:
 
-```
+```json
 [audit] 2026-05-28T15:01:22.413Z | alice | tools/call | name=powerquery_run | 200 ok
 [audit] 2026-05-28T15:01:34.221Z | bob   | tools/list | -                  | 200 ok
 [audit] 2026-05-28T17:03:11.221Z | -     | -          | -                  | 401 unauthorized
@@ -434,7 +442,7 @@ The `maxRows` (`powerquery_run`) and `first` (`uam_list_alerts`) parameters are
 
 ## CLI reference
 
-```
+```text
 s1-secops-mcp [options]
 
 OPTIONS
@@ -448,7 +456,7 @@ OPTIONS
 
 ## Architecture
 
-```
+```text
 s1-secops-mcp/
   index.js                    Entry: flag parsing + transport selection
   lib/
@@ -485,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>`, do not send `s1-scope` (returns 403) | `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
 
@@ -495,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

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

package/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'),
   };
 }