@pmoses-s1/s1-secops-mcp 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## 1.2.4 - 2026-07-31
+
+Hardening release from the 2026-07-31 code review. Tool count unchanged at 26.
+
+### Fixed
+- **Missing `Retry-After` header no longer sleeps 0ms before retrying.** `Number(null)` is 0, so `lib/s1.js`, `lib/hec.js`, and `lib/uam-ingest.js` treated an absent header as "wait 0ms" and hammered the backend. All three now use the validated pattern from `lib/sdl.js`: honor the header only when present and parseable as a finite number of seconds (capped at 30s), otherwise fall back to the exponential delay. Numeric headers behave exactly as before.
+- **`uam_set_status` no longer reports silent success.** The `alertTriggerActions` mutation selected only `__typename`, so a skipped or failed action still returned as if it worked (observed live: status unchanged after a "successful" call). The selection now mirrors the full `actions { success failure skip }` shape and the client throws when the backend reports a failure entry, skips the action without a success, or returns an empty actions list (nothing applied, e.g. the filter matched no alert). `uam_add_note` was audited for the same pattern; it already verifies via the returned note list.
+- **LRQ polling tolerates transient poll errors.** A single 429/5xx poll response used to throw and cancel the running query. Transient statuses now keep polling (interval doubles up to 5s) until the existing 5-minute deadline; other 4xx responses remain fatal.
+- **`hasSdlCreds()` recognizes read-only key deployments.** It required `SDL_CONFIG_WRITE_KEY` or the console token; tenants configured with only `SDL_LOG_READ_KEY` / `SDL_CONFIG_READ_KEY` were reported as unconfigured. All chain keys now count.
+- **HTTP transport: oversized bodies get their 413.** The request was destroyed before the response was written, so clients saw a connection reset instead of the 413 JSON error. The server now stops reading, sends the 413, then drops the connection after the response is flushed.
+- **HTTP transport exits nonzero on any listen-time server error** (EACCES, EADDRNOTAVAIL, ...), not only EADDRINUSE, so systemd/Docker restart policies see the failure.
+- **`powerquery_schema_discover` escapes backslashes before quotes** in the data-source name; quote-only escaping let a trailing backslash re-open the V1 filter string.
+- **`s1_api_get` honors an inline `?isLegacy=` already present in the path** instead of appending a conflicting `isLegacy=false` query param, matching `_maybe_inject_islegacy` in the Python twin.
+- **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.
+- **Docker entrypoint passes extra args through** to the selected server binary (e.g. `s1-secops-mcp --transport http`); no-args behavior is unchanged.
+- **`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.
+
+## 1.2.3 - 2026-07-29
+
+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.
+- **`uam_post_alert` schema help corrected** to require `class_uid 99602001` (the S1 Security Alert extension class); generic OCSF `2002` is silently dropped by the stitcher.
+- **`ha_export_workflow` no longer implies it returns the archive** (metadata only).
+- **`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).
+
+## 1.2.1 - 2026-06-11
+
+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.
+- **`S1_CREDS_FILE` credential resolver.** Highest-priority explicit path for credentials, useful for VM deployments and secret-store integrations (Vault, Doppler, 1Password Connect, sealed-secrets).
+- **Deploy artifacts** under `deploy/`:
+  - `install.sh`: one-shot installer for Mac and Linux. `--user` mode for individuals, `--server` mode for Linux VMs (creates `mcp` system user, generates an initial bearer token, installs systemd unit, starts the service).
+  - `systemd/s1-secops-mcp.service`: hardened unit with `NoNewPrivileges`, `ProtectSystem=strict`, `MemoryDenyWriteExecute`, SIGHUP-as-reload.
+  - `caddy/Caddyfile.example`: TLS reverse proxy template with bearer header gate and streaming-friendly flush.
+  - `README.md`: full topology guide (single-user local, single-user HTTP, team VM-hosted) with day-2 operations.
+- **Test suite.** Three new files under `tests/`, runnable via `npm test`:
+  - `smoke.test.mjs`: source-of-truth tool inventory (26 tools by name).
+  - `stdio-transport.test.mjs`: JSON-RPC round trip via spawned stdio process.
+  - `http-transport.test.mjs`: HTTP transport end-to-end, bearer auth happy/sad paths.
+- **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
+  - new scripts: `start:http`, `test`, `regen:readme`
+  - 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.
+
+## 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

@@ -0,0 +1,519 @@
+# SentinelOne MCP Server
+
+Model Context Protocol server orchestrating the SentinelOne Management Console, Singularity Data Lake, UAM Alert Interface, and Hyperautomation APIs. Pure Node.js 18+, zero external dependencies. Supports both stdio (for Claude Desktop / Cowork / Claude Code) and Streamable HTTP (for team-shared VM deployments) transports.
+
+- **Single-user, local:** install with `npx`, plug into Claude Desktop in 30 seconds.
+- **Team, VM-hosted:** install on one Linux box, per-user bearer tokens, audit logs, SIGHUP-reloadable rotation.
+
+See **[deploy/README.md](./deploy/README.md)** for the full deployment walkthrough across all three topologies.
+
+## What this exposes
+
+<!-- BEGIN AUTO-GENERATED TOOLS TABLE -->
+**26 tools** across PowerQuery, Mgmt Console, SDL API, Hyperautomation, and UAM Ingest:
+
+| Group | Tool | Skill |
+|-------|------|-------|
+| PowerQuery | `powerquery_enumerate_sources` | powerquery |
+| PowerQuery | `powerquery_run` | powerquery |
+| PowerQuery | `powerquery_schema_discover` | powerquery |
+| Mgmt Console | `purple_ai_alert_summary` | mgmt-console-api |
+| Mgmt Console | `s1_api_delete` | mgmt-console-api |
+| Mgmt Console | `s1_api_get` | mgmt-console-api |
+| Mgmt Console | `s1_api_patch` | mgmt-console-api |
+| Mgmt Console | `s1_api_post` | mgmt-console-api |
+| Mgmt Console | `s1_api_put` | mgmt-console-api |
+| Mgmt Console | `uam_add_note` | mgmt-console-api |
+| Mgmt Console | `uam_get_alert` | mgmt-console-api |
+| 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_delete_file` | sdl-api |
+| SDL API | `sdl_get_file` | sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_list_files` | sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_put_file` | sdl-api / sdl-dashboard / sdl-log-parser |
+| Hyperautomation | `ha_delete_workflow` | hyperautomation |
+| Hyperautomation | `ha_export_workflow` | hyperautomation |
+| Hyperautomation | `ha_get_workflow` | hyperautomation |
+| Hyperautomation | `ha_import_workflow` | hyperautomation |
+| Hyperautomation | `ha_list_workflows` | hyperautomation |
+| UAM Ingest | `uam_ingest_alert` | mgmt-console-api (UAM Alert Interface) |
+| UAM Ingest | `uam_post_alert` | mgmt-console-api (UAM Alert Interface) |
+| UAM Ingest | `uam_post_indicators` | mgmt-console-api (UAM Alert Interface) |
+<!-- 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.
+
+## Quick install
+
+For the end-user install paths (Docker quick start, npx/uvx, and team VM), see the canonical **[README Installation section](../README.md#installation)**; credential keys and where to get them are in **[docs/credentials.md](../docs/credentials.md)**. This section is the MCP-server-specific reference: the exact npm package and pin, the reproducible install script, and the Claude Desktop stdio bridge for a shared team VM. Three paths, pick the one that matches your setup:
+
+### A. Local single-user via `npx` (Claude Desktop / Claude Code / Cowork)
+
+MCP runs as a subprocess on your machine, talking SentinelOne APIs directly. Credentials live in the Claude config `env` block.
+
+Add this to `claude_desktop_config.json` (or `.mcp.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "s1-secops-mcp": {
+      "command": "npx",
+      "args": ["-y", "@pmoses-s1/s1-secops-mcp@1.3.0"],
+      "env": {
+        "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
+        "S1_CONSOLE_API_TOKEN": "eyJ...",
+        "S1_HEC_INGEST_URL":    "https://ingest.us1.sentinelone.net",
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. `npx -y` caches the package on first launch.
+
+### B. Reproducible: install script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/pmoses-s1/claude-skills/main/s1-secops-mcp/deploy/install.sh | bash
+```
+
+Sets up a per-user npm prefix if needed, installs the package, drops a credentials skeleton at `~/.config/sentinelone/credentials.json` (mode 0600), and prints the wiring instructions for Claude Desktop.
+
+For VM deployments, the same script in `--server` mode does everything (system user, systemd unit, initial bearer token, service start). See [deploy/README.md](./deploy/README.md).
+
+### C. Claude Desktop connecting to a team VM (stdio bridge)
+
+When the MCP is running as a shared service on a Linux VM (deploy topology C in [deploy/README.md](./deploy/README.md)) and you're connecting from Claude Desktop, you need a small stdio↔HTTPS shim because Claude Desktop's stable build doesn't accept `type: "http"` configs. (Claude Cowork and Claude Code do; see "[Calling the HTTP endpoint directly](#calling-the-http-endpoint-directly)" for the native `type: "http"` form.)
+
+The bridge is a 40-line zero-dependency Node script shipped at [`deploy/bridge/s1-secops-mcp-bridge.mjs`](./deploy/bridge/s1-secops-mcp-bridge.mjs).
+
+Each team member installs the script once:
+
+```bash
+mkdir -p ~/.local/bin
+curl -fsSL https://raw.githubusercontent.com/pmoses-s1/claude-skills/main/s1-secops-mcp/deploy/bridge/s1-secops-mcp-bridge.mjs \
+  -o ~/.local/bin/s1-secops-mcp-bridge.mjs
+chmod +x ~/.local/bin/s1-secops-mcp-bridge.mjs
+```
+
+Then adds this block to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "s1-secops-mcp": {
+      "command": "node",
+      "args": ["/Users/<you>/.local/bin/s1-secops-mcp-bridge.mjs"],
+      "env": {
+        "MCP_URL":    "https://mcp.example.internal:8764/mcp",
+        "MCP_BEARER": "<your personal bearer token>"
+      }
+    }
+  }
+}
+```
+
+Cmd+Q and reopen Claude Desktop. SentinelOne credentials live on the VM in `/etc/s1-secops-mcp/credentials.json`, only the bearer token sits in each user's local Claude config. Full setup + smoke-test instructions at [`deploy/bridge/README.md`](./deploy/bridge/README.md).
+
+## Credentials
+
+Credential keys, where to get each one, and the two token types are documented canonically in **[docs/credentials.md](../docs/credentials.md)**. This section adds the MCP-server-specific detail: which tools each key gates, and the server's full credential-resolution order.
+
+`S1_CONSOLE_URL` and `S1_CONSOLE_API_TOKEN` are sufficient for the PowerQuery, Mgmt Console REST, Purple AI summary, and UAM tools (16 of the 26).
+
+`S1_HEC_INGEST_URL` is **required** for the three UAM Ingest tools (`uam_ingest_alert`, `uam_post_indicators`, `uam_post_alert`) and for `hec_ingest`. Without it those tools error at call time; the rest still work.
+
+`SDL_*` keys gate the SDL tools as follows:
+
+| Variable | Description | Required for |
+|----------|-------------|--------------|
+| `S1_CONSOLE_URL` | Console URL, e.g. `https://usea1-acme.sentinelone.net` | All Mgmt + PowerQuery tools |
+| `S1_CONSOLE_API_TOKEN` | Mgmt Console API token (Settings → Users → Service Users) | All Mgmt + PowerQuery + UAM tools |
+| `S1_HEC_INGEST_URL` | HEC ingest host, e.g. `https://ingest.us1.sentinelone.net` | `uam_ingest_alert`, `uam_post_indicators`, `uam_post_alert`, `hec_ingest` |
+
+### Credential resolution order (highest priority wins)
+
+1. Environment variables (set in `claude_desktop_config.json` `env`, systemd `EnvironmentFile`, or your shell).
+2. `S1_CREDS_FILE`: explicit path to a JSON file (recommended for VM deployments and secret-store integrations).
+3. `COWORK_WORKSPACE/credentials.json`.
+4. Walk-up from the current working directory looking for `credentials.json`.
+5. `~/mnt/<folder>/credentials.json` (Cowork workspace mounts).
+6. `$CLAUDE_CONFIG_DIR/sentinelone/credentials.json`.
+7. `~/.config/sentinelone/credentials.json`.
+
+The server logs the resolved credential source at startup so you can diagnose surprise overrides.
+
+## Transport modes
+
+### stdio (default)
+
+The transport used by Claude Desktop, Claude Code, Claude Cowork, and any other client launched via `npx` / `node index.js`.
+
+```bash
+s1-secops-mcp                          # auto-discovers credentials
+node index.js                            # same as above, from a local clone
+```
+
+### Streamable HTTP
+
+```bash
+s1-secops-mcp --transport http                       # 127.0.0.1:8765/mcp, no auth
+s1-secops-mcp --transport http --host 0.0.0.0        # all interfaces, no auth (loud warning)
+MCP_BEARER_TOKENS_FILE=/etc/s1-secops-mcp/bearer-tokens.json \
+  s1-secops-mcp --transport http --host 0.0.0.0      # team mode with per-user tokens
+```
+
+Configuration via flags or environment variables:
+
+| Flag | Env var | Default | Purpose |
+|------|---------|---------|---------|
+| `--transport` | `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. |
+| `--host` | `MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind address. Use `0.0.0.0` for cross-host access. |
+| `--port` | `MCP_HTTP_PORT` | `8765` | HTTP port. |
+| `--path` | `MCP_HTTP_PATH` | `/mcp` | MCP endpoint path. |
+
+In HTTP mode the server exposes:
+
+- `POST /mcp`: accepts JSON-RPC, returns JSON-RPC. The MCP entry point.
+- `GET /healthz`: returns `200 ok`. For load balancer probes; no auth.
+
+### Team auth: bearer tokens
+
+To enable team auth, set one of:
+
+- `MCP_BEARER_TOKENS_FILE=/path/to/file.json` (recommended). The file is `{ "<name>": "<token>", ... }`. Names appear in audit logs; revoking a user is a one-line edit. SIGHUP reloads without restart.
+- `MCP_BEARER_TOKENS="token1,token2,..."` (fallback, no per-user names).
+
+Token rotation:
+
+```bash
+sudo vim /etc/s1-secops-mcp/bearer-tokens.json   # add/remove entries
+sudo systemctl reload s1-secops-mcp              # SIGHUP, no connection drops
+```
+
+If neither env var is set, HTTP transport runs **without** authentication and the server logs a warning at startup. That's acceptable for `--host 127.0.0.1` single-user use; never use it on `0.0.0.0` in production.
+
+### Audit log
+
+Every authenticated HTTP request emits a structured stderr line that systemd captures via journald:
+
+```
+[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
+```
+
+## Calling the HTTP endpoint directly
+
+You don't need an MCP client library. The HTTP transport is plain JSON-RPC 2.0 over `POST`, with bearer auth in the `Authorization` header. Any HTTP client works, `curl`, Python `requests`, Node `fetch`, Go `net/http`, etc. This is how you'd integrate from a custom script, a CI job, or a non-MCP tool that just needs to call SentinelOne via the same wrapped surface.
+
+> **Ready-made check:** [`scripts/smoke-test-http.sh`](./scripts/smoke-test-http.sh) runs the six contract checks documented below (healthz, initialize, tools/list, tools/call, bad-bearer 401, unknown-method JSON-RPC error) and prints PASS/FAIL. Run as `MCP_HOST=<host:port> MCP_BEARER=<token> bash s1-secops-mcp/scripts/smoke-test-http.sh`. Good for new-team-member onboarding and post-rotation validation.
+
+### Endpoint contract
+
+| Item | Value |
+|---|---|
+| Method | `POST` |
+| URL | `https://<host>:<port>/mcp` (path is `/mcp` by default; configurable with `--path`) |
+| `Content-Type` | `application/json` |
+| `Authorization` | `Bearer <token>` (one of the tokens in `MCP_BEARER_TOKENS_FILE`) |
+| Body | JSON-RPC 2.0 envelope |
+| Response | JSON-RPC 2.0 envelope (`result` on success, `error` on failure) |
+
+Health probe (no auth, no JSON): `GET /healthz` returns `200 ok`.
+
+### Initialize, then list tools, then call one (curl)
+
+```bash
+HOST=mcp.s1.internal
+TOKEN='your-bearer-token-here'
+
+# 1. initialize (required first call per spec; advertises protocol version and capabilities)
+curl -s -X POST "https://$HOST/mcp" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+          "protocolVersion": "2024-11-05",
+          "capabilities": {},
+          "clientInfo": { "name": "my-script", "version": "1.0" }
+        }
+      }'
+# -> {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}}}
+
+# 2. list every tool the server exposes
+curl -s -X POST "https://$HOST/mcp" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | jq '.result.tools | length'
+# -> 26
+
+# 3. call a tool (here: list custom detection rules with the mandatory isLegacy=false)
+curl -s -X POST "https://$HOST/mcp" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "tools/call",
+        "params": {
+          "name": "s1_api_get",
+          "arguments": {
+            "path": "/web/api/v2.1/cloud-detection/rules",
+            "params": { "isLegacy": false, "limit": 50 }
+          }
+        }
+      }' \
+  | jq '.result.content[0].text | fromjson | .pagination.totalItems'
+```
+
+### Python (requests)
+
+```python
+import json
+import requests
+
+URL    = "https://mcp.s1.internal/mcp"
+TOKEN  = "your-bearer-token-here"
+HEADERS = {
+    "Authorization": f"Bearer {TOKEN}",
+    "Content-Type":  "application/json",
+}
+
+def rpc(method, params=None, id=1):
+    body = {"jsonrpc": "2.0", "id": id, "method": method}
+    if params is not None:
+        body["params"] = params
+    r = requests.post(URL, headers=HEADERS, json=body, timeout=30)
+    r.raise_for_status()
+    return r.json()
+
+# initialize once per session
+rpc("initialize", {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {},
+    "clientInfo": {"name": "python-client", "version": "1.0"},
+}, id=0)
+
+# list tools
+tools = rpc("tools/list", id=1)["result"]["tools"]
+print(f"{len(tools)} tools available")
+
+# call a tool
+resp = rpc("tools/call", {
+    "name": "powerquery_run",
+    "arguments": {
+        "query": "dataSource.name=* | group count=count() by dataSource.name | sort -count | limit 10",
+        "hours": 24,
+    },
+}, id=2)
+
+# Tool results live in result.content[0].text as a JSON string.
+payload = json.loads(resp["result"]["content"][0]["text"])
+print(json.dumps(payload, indent=2))
+```
+
+### Node (built-in fetch, Node 18+)
+
+```javascript
+const URL    = 'https://mcp.s1.internal/mcp';
+const TOKEN  = process.env.MCP_BEARER;
+
+async function rpc(method, params, id = 1) {
+  const body = { jsonrpc: '2.0', id, method };
+  if (params !== undefined) body.params = params;
+  const res = await fetch(URL, {
+    method:  'POST',
+    headers: {
+      'Authorization': `Bearer ${TOKEN}`,
+      'Content-Type':  'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+await rpc('initialize', {
+  protocolVersion: '2024-11-05',
+  capabilities: {},
+  clientInfo: { name: 'node-client', version: '1.0' },
+}, 0);
+
+const { result } = await rpc('tools/list', null, 1);
+console.log(`${result.tools.length} tools available`);
+
+const call = await rpc('tools/call', {
+  name: 'uam_list_alerts',
+  arguments: { first: 20, status: 'NEW' },
+}, 2);
+console.log(JSON.parse(call.result.content[0].text));
+```
+
+### JSON-RPC envelope shapes
+
+**Success response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": { ... method-specific payload ... }
+}
+```
+
+**Error response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "error": {
+    "code": -32602,
+    "message": "Tool not found: bad_tool_name"
+  }
+}
+```
+
+**Notifications** (one-way messages with no `id`, e.g. `notifications/initialized`):
+
+```bash
+curl -i -s -X POST "https://$HOST/mcp" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+# -> HTTP/2 202 (no body, per JSON-RPC spec)
+```
+
+### Error codes you'll actually see
+
+| HTTP | JSON-RPC code | Meaning |
+|---|---|---|
+| 200 | (none, has `result`) | Success |
+| 200 | `-32601` | Method not found (e.g. typo in method name) |
+| 200 | `-32602` | Invalid params (tool not found, missing required arg) |
+| 200 | `-32603` | Tool handler threw: upstream S1 API error usually |
+| 400 | `-32700` | Parse error (malformed JSON body) |
+| 400 | `-32600` | Invalid request (e.g. JSON-RPC batch, not supported) |
+| 401 | `-32001` | Missing or invalid bearer token |
+| 405 | (none) | Wrong HTTP method on `/mcp` (only POST is accepted) |
+| 413 | `-32600` | Body exceeds 4 MB |
+
+### Tool inputs and outputs
+
+Every tool's input schema is documented in the `tools/list` response (look at the `inputSchema` JSON Schema on each tool). The response shape is always:
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "<JSON-encoded result>" }
+  ],
+  "isError": false
+}
+```
+
+Parse `content[0].text` as JSON to get the actual data the tool returned. Tool-level errors set `isError: true` and put the error text in the same field.
+
+### Row / page limits (measured, not enforced)
+
+The `maxRows` (`powerquery_run`) and `first` (`uam_list_alerts`) parameters are soft client-side hints, not hard backend caps. Live-verified 2026-07-29:
+
+- `powerquery_run` `maxRows`: default 1000, but not a ceiling. The LRQ engine returns as many rows as the query's own `| limit N` asks for. A `| limit 20000` query with `maxRows: 20000` returned 20,000 rows in a single response. Set `maxRows` to match a large `| limit`; the practical ceiling is LRQ response size, not a fixed 5000. Prefer aggregating in the query (`| group ... | limit N`) over pulling tens of thousands of raw rows.
+- `uam_list_alerts` `first`: default 20, not enforced client-side. The UAM GraphQL backend accepts larger pages: `first: 500` returned 500 alerts with `pageInfo.hasNextPage: true`. Paginate with the returned `pageInfo.endCursor` via `after` rather than requesting one unbounded page.
+
+## CLI reference
+
+```
+s1-secops-mcp [options]
+
+OPTIONS
+  --transport <stdio|http>    Transport. Default: stdio.
+  --host <host>               HTTP bind address. Default: 127.0.0.1.
+  --port <port>               HTTP port. Default: 8765.
+  --path <path>               HTTP MCP endpoint path. Default: /mcp.
+  -h, --help                  Show help.
+  -v, --version               Show server version.
+```
+
+## Architecture
+
+```
+s1-secops-mcp/
+  index.js                    Entry: flag parsing + transport selection
+  lib/
+    server-core.js            Tool registry, JSON-RPC dispatch (transport-agnostic)
+    stdio-transport.js        stdin/stdout JSON-RPC loop
+    http-transport.js         Streamable HTTP (node:http, zero deps)
+    auth.js                   Bearer token allowlist with SIGHUP reload
+    credentials.js            S1 + SDL credential resolution
+    s1.js                     Mgmt REST + LRQ PowerQuery + Purple AI + UAM GraphQL
+    sdl.js                    SDL config files + V1 query
+    uam-ingest.js             HEC alert/indicator ingestion
+  tools/
+    powerquery.js             PowerQuery enumerate/run/schema-discover
+    mgmt-console.js           S1 REST verbs + Purple AI summary + UAM
+    sdl-api.js                SDL config file + log ingestion tools
+    hyperautomation.js        Hyperautomation list/get/import/export/delete
+    uam-ingest.js             UAM Alert Interface ingestion tools
+  deploy/
+    install.sh                One-shot installer (Mac and Linux)
+    systemd/                  Service unit for Linux VM deployments
+    caddy/                    TLS reverse proxy template
+    README.md                 Deployment walkthrough
+  scripts/
+    regen-readme-tools-table.mjs   Tools-table regenerator (no drift)
+  tests/                      Smoke + stdio + HTTP test suites (node --test)
+```
+
+## Auth patterns (implemented)
+
+| API surface | Auth header | Key |
+|-------------|-------------|-----|
+| S1 Mgmt REST API | `Authorization: ApiToken <jwt>` | `S1_CONSOLE_API_TOKEN` |
+| LRQ PowerQuery | `Authorization: Bearer <jwt>` | Same token, different prefix |
+| 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` |
+
+## Testing
+
+```bash
+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.
+- `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.
+
+The smoke suite is the source of truth for the tool count and is what `scripts/regen-readme-tools-table.mjs` derives the README table from. If the table goes stale, `npm run regen:readme -- --check` fails CI; `npm run regen:readme` fixes it.
+
+## Updating CLAUDE.md
+
+The `sentinelone://soc-context` resource and `soc_analyst` prompt load `CLAUDE.md` at server startup. Resolution order:
+
+1. `S1_CLAUDE_MD_PATH` env var (explicit absolute path).
+2. `<cwd>/CLAUDE.md`: your Cowork project folder, when launched from there.
+3. Same-dir / parent / grandparent of the server's `index.js`: when running from a git clone.
+
+For npx installs without a CLAUDE.md nearby, set `S1_CLAUDE_MD_PATH` in the `env` block of `claude_desktop_config.json` to point at the one in your Cowork project folder. Restart Claude Desktop to pick up edits.
+
+## Removed tools
+
+`purple_ai_query` and `purple_ai_investigate` were removed on 2026-05-03. Both required a browser-session `teamToken` from `/sdl/v2/graphql` that service-account API tokens never obtain (returns `AsimovError` / `SERVICE_ERROR`). Use `mcp__purple-mcp__purple_ai` instead, which holds the right credentials.
+
+## Version history
+
+See [CHANGELOG.md](./CHANGELOG.md).