@pmoses-s1/sentinelone-mcp 1.0.0 → 1.2.0

package/scripts/test-mac.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+#
+# Mac validation script for sentinelone-mcp v1.1.0.
+#
+# Runs the same test matrix as Linux:
+#   - syntax-check every .js/.mjs file
+#   - npm test (smoke + stdio + HTTP suites, 22 assertions)
+#   - regen:readme --check (no doc drift)
+#   - sanity-run the server in stdio and HTTP modes
+#
+# Run this from the sentinelone-mcp/ directory on your Mac:
+#
+#   cd ~/path/to/claude-skills/sentinelone-mcp
+#   bash scripts/test-mac.sh
+#
+# All checks should pass with green PASS markers. Any FAIL line should be
+# reported back so the issue can be diagnosed.
+
+set -uo pipefail
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+green() { printf '\033[32m%s\033[0m' "$*"; }
+red()   { printf '\033[31m%s\033[0m' "$*"; }
+bold()  { printf '\033[1m%s\033[0m' "$*"; }
+
+pass() { printf '  %s %s\n' "$(green PASS)" "$1"; PASS_COUNT=$((PASS_COUNT+1)); }
+fail() { printf '  %s %s\n  %s\n' "$(red FAIL)" "$1" "${2:-}"; FAIL_COUNT=$((FAIL_COUNT+1)); }
+step() { printf '\n%s\n' "$(bold "$1")"; }
+
+# ─── 1. Environment ───────────────────────────────────────────────────────────
+
+step "1. Environment"
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "  WARNING: this script targets macOS but you're on $(uname -s). Continuing anyway."
+fi
+if ! command -v node >/dev/null 2>&1; then
+  fail "node not on PATH" "Install Node 18+: brew install node@20"
+  exit 1
+fi
+NODE_MAJOR="$(node --version | sed 's/^v\([0-9]*\).*/\1/')"
+if [[ "$NODE_MAJOR" -lt 18 ]]; then
+  fail "Node $(node --version) is too old" "Need Node 18+"
+  exit 1
+fi
+pass "Node $(node --version) on $(uname -srm)"
+
+if [[ ! -f "index.js" ]]; then
+  fail "Not in the sentinelone-mcp directory" "cd to .../claude-skills/sentinelone-mcp first"
+  exit 1
+fi
+pass "running from sentinelone-mcp directory"
+
+# ─── 2. Syntax check ──────────────────────────────────────────────────────────
+
+step "2. Syntax check"
+for f in index.js lib/*.js tests/*.mjs scripts/*.mjs; do
+  [[ -f "$f" ]] || continue
+  if node --check "$f" 2>/dev/null; then
+    pass "$f"
+  else
+    out="$(node --check "$f" 2>&1)"
+    fail "$f" "$out"
+  fi
+done
+
+# ─── 3. npm test (22 assertions across smoke + stdio + HTTP) ─────────────────
+
+step "3. Test suite (npm test)"
+# Node 18-22 default to the TAP reporter, Node 23+ default to spec. Both
+# reporters print the same passing assertions but with different summary
+# lines. We check exit code first (authoritative) and then count assertions.
+TEST_LOG="/tmp/mcp-test-mac.npm-test.log"
+if npm test >"$TEST_LOG" 2>&1; then
+  # Count passing assertions across both reporter formats:
+  #   TAP:   "ok 1 - <name>"
+  #   spec:  "✔ <name>" (U+2714 HEAVY CHECK MARK)
+  TAP_OKS="$(grep -cE '^ok [0-9]+' "$TEST_LOG" || true)"
+  SPEC_OKS="$(grep -cE '^[[:space:]]*✔' "$TEST_LOG" || true)"
+  TOTAL=$((TAP_OKS + SPEC_OKS))
+  if [[ "$TOTAL" -ge 22 ]]; then
+    pass "$TOTAL passing assertions (npm test exit 0)"
+  else
+    fail "npm test exited 0 but only $TOTAL passing lines found" "$(tail -30 "$TEST_LOG")"
+  fi
+else
+  fail "npm test exited non-zero" "$(tail -30 "$TEST_LOG")"
+fi
+
+# ─── 4. README/code drift check ───────────────────────────────────────────────
+
+step "4. README/code drift check"
+if npm run regen:readme -- --check >/dev/null 2>&1; then
+  pass "README tools table in sync with ALL_TOOLS"
+else
+  fail "README tools table is stale" "Run: npm run regen:readme"
+fi
+
+# ─── 5. CLI flag sanity ───────────────────────────────────────────────────────
+
+step "5. CLI flag sanity"
+if [[ "$(node index.js --version 2>/dev/null)" == "1.1.0" ]]; then
+  pass "--version returns 1.1.0"
+else
+  fail "--version did not return 1.1.0" "Got: $(node index.js --version 2>&1)"
+fi
+if node index.js --help 2>&1 | grep -q "sentinelone-mcp 1.1.0"; then
+  pass "--help renders"
+else
+  fail "--help broken" "$(node index.js --help 2>&1 | head -5)"
+fi
+
+# ─── 6. stdio round-trip ──────────────────────────────────────────────────────
+
+step "6. stdio round-trip"
+STDIO_REPLY="$(printf '%s\n%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mac-test","version":"1"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | 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"
+else
+  fail "stdio tools/list returned $TOOL_COUNT (expected 26)" "$STDIO_REPLY"
+fi
+
+# ─── 7. HTTP transport round-trip ─────────────────────────────────────────────
+
+step "7. HTTP transport round-trip"
+PORT=$((10000 + RANDOM % 1000))
+node index.js --transport http --port "$PORT" --host 127.0.0.1 >/tmp/mcp-test-mac.log 2>&1 &
+SERVER_PID=$!
+trap "kill $SERVER_PID 2>/dev/null || true" EXIT
+
+# Wait for healthz
+for i in $(seq 1 30); do
+  if curl -sf "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1; then
+    pass "HTTP server up on port $PORT"
+    break
+  fi
+  sleep 0.2
+  if [[ "$i" -eq 30 ]]; then
+    fail "HTTP server did not start within 6s" "$(cat /tmp/mcp-test-mac.log)"
+    exit 1
+  fi
+done
+
+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"
+else
+  fail "HTTP tools/list returned $HTTP_COUNT" "$HTTP_REPLY"
+fi
+
+# Auth: with no token loaded the server should accept unauthenticated requests
+# (single-user local-only mode). Confirmed by the 26-tools response above.
+pass "no-auth mode allows requests (single-user local)"
+
+kill $SERVER_PID 2>/dev/null || true
+trap - EXIT
+
+# ─── Summary ──────────────────────────────────────────────────────────────────
+
+step "Summary"
+printf "  Passed: %s\n" "$(green "$PASS_COUNT")"
+if [[ "$FAIL_COUNT" -gt 0 ]]; then
+  printf "  Failed: %s\n\n" "$(red "$FAIL_COUNT")"
+  echo "If any FAILs above, paste them so the issue can be diagnosed."
+  exit 1
+else
+  printf "  Failed: %s\n\n" "$FAIL_COUNT"
+  echo "$(green 'All checks passed on macOS.')"
+  exit 0
+fi

package/tools/hyperautomation.js

@@ -50,7 +50,7 @@ export const tools = [
         },
         siteIds: {
           type: 'string',
-          description: 'Comma-separated site IDs to scope results to (e.g. "2056852093198736293"). Omit for all accessible scopes.',
+          description: 'Comma-separated site IDs to scope results to (e.g. "<site-id-1>,<site-id-2>"). Omit for all accessible scopes.',
         },
         sortBy: {
           type: 'string',

package/tools/mgmt-console.js

@@ -21,11 +21,35 @@
 
 import { apiGet, apiPost, apiPut, apiDelete, apiPatch, purpleAlertSummary, uamListAlerts, uamGetAlert, uamAddNote, uamSetStatus } from '../lib/s1.js';
 
+/**
+ * Defensive normalization for GET /cloud-detection/rules calls.
+ *
+ * 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. Promoting "empty response" to "tenant has zero
+ * scheduled detections" without isLegacy=false is the failure mode this
+ * guard exists to prevent. Exported for unit testing.
+ */
+export function normalizeS1ApiGetParams(path, params) {
+  const p = { ...(params || {}) };
+  if (
+    typeof path === 'string' &&
+    /\/cloud-detection\/rules(\/|\?|$)/.test(path) &&
+    p.isLegacy === undefined &&
+    p.is_legacy === undefined
+  ) {
+    p.isLegacy = false;
+  }
+  return p;
+}
+
 export const tools = [
   // ─── s1_api_get ───────────────────────────────────────────────────────────
   {
     name: 's1_api_get',
-    description: `Generic GET request to the SentinelOne Management Console REST API (v2.1). Use for ALL read operations: listing, counting, and exporting. The S1 API uses GET for every read — listing, counting, and exporting are always GET, never POST. The path should start with /web/api/v2.1/. Returns raw JSON response. For paginated endpoints, use the cursor or skip/limit params. Count examples: path="/web/api/v2.1/agents/count" returns {"data":{"total":N}}; path="/web/api/v2.1/threats" params={"countOnly":true} returns pagination.totalItems. Export example: path="/web/api/v2.1/threats/export" (no extra params). Get agents by IDs: path="/web/api/v2.1/agents" params={"ids":"<id1>,<id2>"} (comma-separated query param).`,
+    description: `Generic GET request to the SentinelOne Management Console REST API (v2.1). Use for ALL read operations: listing, counting, and exporting. The S1 API uses GET for every read — listing, counting, and exporting are always GET, never POST. The path should start with /web/api/v2.1/. Returns raw JSON response. For paginated endpoints, use the cursor or skip/limit params. Count examples: path="/web/api/v2.1/agents/count" returns {"data":{"total":N}}; path="/web/api/v2.1/threats" params={"countOnly":true} returns pagination.totalItems. Export example: path="/web/api/v2.1/threats/export" (no extra params). Get agents by IDs: path="/web/api/v2.1/agents" params={"ids":"<id1>,<id2>"} (comma-separated query param).
+
+⚠️ CLOUD-DETECTION RULES — MANDATORY isLegacy=false: For ANY GET on /cloud-detection/rules (listing, name search, queryType filter, scope filter) you MUST pass params.isLegacy=false. Without it the API silently omits queryType="scheduled" PowerQuery rules and returns only events-type rules — there is no error, no warning, the response just lies by omission. This handler auto-injects isLegacy=false when it sees a /cloud-detection/rules path and the caller forgot it, but always pass it explicitly so it shows up in audit logs. Promoting "empty response" to "tenant has zero scheduled detections" without isLegacy=false is the failure mode this guard exists to prevent.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -35,14 +59,17 @@ export const tools = [
         },
         params: {
           type: 'object',
-          description: 'Query string parameters as key-value pairs, e.g. {"limit": 20, "sortBy": "createdAt"}.',
+          description: 'Query string parameters as key-value pairs, e.g. {"limit": 20, "sortBy": "createdAt"}. For /cloud-detection/rules listings ALWAYS include {"isLegacy": false}; the handler auto-injects it as a safety net but explicit is better.',
           additionalProperties: true,
         },
       },
       required: ['path'],
     },
     async handler({ path, params = {} }) {
-      const result = await apiGet(path, params);
+      // Safety net: /cloud-detection/rules silently hides scheduled
+      // PowerQuery rules unless isLegacy=false is passed.
+      const normalized = normalizeS1ApiGetParams(path, params);
+      const result = await apiGet(path, normalized);
       return JSON.stringify(result, null, 2);
     },
   },

package/tools/sdl-api.js

@@ -6,10 +6,11 @@
  *   sdl_get_file       Get file content and version (parsers, dashboards, alerts, lookups)
  *   sdl_put_file       Deploy or update a config file (with optimistic locking)
  *   sdl_delete_file    Delete a config file
- *   sdl_upload_logs    Upload raw log events to SDL (requires Log Write key)
+ *   hec_ingest         Ingest raw logs/events into SDL via the HEC endpoint (replaces uploadLogs)
  */
 
-import { listFiles, getFile, putFile, deleteFile, uploadLogs } from '../lib/sdl.js';
+import { listFiles, getFile, putFile, deleteFile } from '../lib/sdl.js';
+import { hecIngest } from '../lib/hec.js';
 
 export const tools = [
   // ─── sdl_list_files ───────────────────────────────────────────────────────
@@ -99,34 +100,25 @@ export const tools = [
     },
   },
 
-  // ─── sdl_upload_logs ──────────────────────────────────────────────────────
+  // ─── hec_ingest ─────────────────────────────────────────────────────────────
   {
-    name: 'sdl_upload_logs',
-    description: `Upload raw log events to SDL via the uploadLogs endpoint (plain text, newline-separated). Used for ingesting custom telemetry, testing parsers, and one-off log imports. Requires an SDL Log Write Access key (SDL_LOG_WRITE_KEY) — the console JWT is NOT accepted for this endpoint. Max 6 MB per request, 10 GB per day. Pair with a parser at logfile= to apply field extraction.`,
+    name: 'hec_ingest',
+    description: `Ingest raw logs/events into the SentinelOne AI SIEM Singularity Data Lake via the HEC (HTTP Event Collector) endpoint. Applies a named parser via ?sourcetype and lands the data in the Data Lake for Event Search, PowerQuery, and detection rules. Replaces the removed sdl_upload_logs. NOT UAM ingest (the uam_* tools post OCSF indicators/alerts to /v1/* on the same host but a separate API). Per S-26.1 HEC docs: POST {S1_HEC_INGEST_URL}/services/collector/raw, Authorization: Bearer <S1_CONSOLE_API_TOKEN>, query params become fields, gzip recommended, 10 MB uncompressed per request.`,
     inputSchema: {
       type: 'object',
       properties: {
-        logContent: {
-          type: 'string',
-          description: 'Raw log text, newline-separated. Each line becomes a separate SDL event.',
-        },
-        parser: {
-          type: 'string',
-          description: 'Parser name to apply to the uploaded events (matches the "parser" header). Omit to use the default parser.',
-        },
-        logfile: {
-          type: 'string',
-          description: 'Logical logfile identifier sent as the "logfile" header, e.g. "myapp/access.log". Used by parsers to route events.',
-        },
-        serverHost: {
-          type: 'string',
-          description: 'Source host name, sent as the "server-host" header.',
-        },
+        logContent: { type: 'string', description: 'Raw log text. For the /raw endpoint, newline-separated lines become separate events.' },
+        parser: { type: 'string', description: 'Parser name, sent as the ?sourcetype= query param. Omit to skip parsing (structured JSON on /event auto-parses).' },
+        fields: { type: 'object', description: 'Extra key-value pairs sent as query params; each key becomes a field in the UI, e.g. {"server":"dev","region":"ap1"}. Avoid HEC-reserved names (event, time, host, source, sourcetype, index, fields) as keys; use the parser arg to set sourcetype.' },
+        scope: { type: 'string', description: 'REQUIRED. accountId or "accountId:siteId" sent as the S1-Scope header; HEC rejects requests without it (400 "Missing S1-Scope header").' },
+        endpoint: { type: 'string', enum: ['raw','event'], description: "HEC endpoint: 'raw' (default, raw text) or 'event' (structured JSON)." },
+        compress: { type: 'boolean', description: 'gzip the body (Content-Encoding: gzip). Default true.' },
+        isParsed: { type: 'boolean', description: 'For /event with structured JSON: set ?isParsed=true so SDL indexes the JSON fields directly, with no SDL parser. Confirmed working.' },
       },
-      required: ['logContent'],
+      required: ['logContent', 'scope'],
     },
-    async handler({ logContent, parser, logfile, serverHost }) {
-      const result = await uploadLogs(logContent, { parser, logfile, serverHost });
+    async handler({ logContent, parser, fields, scope, endpoint, compress, isParsed }) {
+      const result = await hecIngest(logContent, { parser, fields, scope, endpoint, compress, isParsed });
       return JSON.stringify(result, null, 2);
     },
   },