@pmoses-s1/sentinelone-mcp 1.0.0 → 1.2.0

package/lib/credentials.js

@@ -3,11 +3,12 @@
  *
  * Resolution order (highest wins):
  *   1. Environment variables
- *   2. COWORK_WORKSPACE/credentials.json
- *   3. Walk-up from cwd looking for credentials.json
- *   4. ~/mnt/<any-folder>/credentials.json (Cowork workspace mounts)
- *   5. CLAUDE_CONFIG_DIR/sentinelone/credentials.json
- *   6. ~/.config/sentinelone/credentials.json
+ *   2. S1_CREDS_FILE (explicit absolute path; recommended for team / VM deployments)
+ *   3. COWORK_WORKSPACE/credentials.json
+ *   4. Walk-up from cwd looking for credentials.json
+ *   5. ~/mnt/<any-folder>/credentials.json (Cowork workspace mounts)
+ *   6. CLAUDE_CONFIG_DIR/sentinelone/credentials.json
+ *   7. ~/.config/sentinelone/credentials.json
  */
 
 import { readFileSync, existsSync, readdirSync } from 'fs';
@@ -33,7 +34,18 @@ function tryLoad(dir) {
 }
 
 function discoverCredentials() {
-  // 1. COWORK_WORKSPACE env override
+  // 1. S1_CREDS_FILE — explicit absolute path. Useful for VM deployments and
+  //    secret-store integrations (Vault / Doppler / 1Password / sealed-secrets)
+  //    that render a credentials file to a known path at boot.
+  const credsFile = process.env.S1_CREDS_FILE;
+  if (credsFile && existsSync(credsFile)) {
+    try { return JSON.parse(readFileSync(credsFile, 'utf-8')); }
+    catch (e) {
+      process.stderr.write(`[credentials] S1_CREDS_FILE set but unreadable: ${e.message}\n`);
+    }
+  }
+
+  // 2. COWORK_WORKSPACE env override
   const ws = process.env.COWORK_WORKSPACE;
   if (ws) {
     const found = tryLoad(ws);
@@ -95,7 +107,6 @@ export function getCreds() {
     S1_CONSOLE_API_TOKEN: e('S1_CONSOLE_API_TOKEN') || e('S1_API_TOKEN'),
     S1_HEC_INGEST_URL:    e('S1_HEC_INGEST_URL'),
     SDL_XDR_URL:          e('SDL_XDR_URL') || e('SDL_BASE_URL'),
-    SDL_LOG_WRITE_KEY:    e('SDL_LOG_WRITE_KEY'),
     SDL_CONFIG_WRITE_KEY: e('SDL_CONFIG_WRITE_KEY'),
     SDL_CONFIG_READ_KEY:  e('SDL_CONFIG_READ_KEY'),
     SDL_LOG_READ_KEY:     e('SDL_LOG_READ_KEY'),

package/lib/hec.js

@@ -0,0 +1,128 @@
+/**
+ * HEC (HTTP Event Collector) raw-log ingestion into the SentinelOne AI SIEM
+ * Singularity Data Lake. This is the SDL log-ingestion path and the replacement
+ * for the removed SDL `uploadLogs`. It is NOT UAM ingest: the `uam_*` tools post
+ * OCSF indicators/alerts to /v1/* on the same ingest host, but that is a separate
+ * API and is not connected to HEC.
+ *
+ * Source of truth: S-26.1 User Guide, "Singularity Data Lake > Data Ingestion >
+ * Additional Integrations > HTTP Event Collector (HEC)", p.4723-4726.
+ *   Host      : S1_HEC_INGEST_URL (e.g. https://ingest.us1.sentinelone.net)
+ *   Endpoints : /services/collector/raw   (raw text — recommended for logs)
+ *               /services/collector/event (structured JSON)
+ *   Auth      : Authorization: Bearer <S1_CONSOLE_API_TOKEN> (the same Management Console API token the other tools use)
+ *   Scope     : S1-Scope header is REQUIRED (accountId or accountId:siteId). Without it HEC returns 400 "Missing S1-Scope header".
+ *   Parser    : ?sourcetype=<parserName> query param. Other query params become fields in the UI.
+ *   Pre-parsed: /event with ?isParsed=true indexes already-structured JSON fields directly, with no SDL parser.
+ *   Compress  : optional "Content-Encoding: gzip" (or zstd) — recommended, lowers egress cost.
+ *   Limits    : 10 MB uncompressed per request, 1000 requests/sec, 2 GB/sec per account.
+ */
+
+import { gzipSync } from 'zlib';
+import { getCreds } from './credentials.js';
+
+const MAX_UNCOMPRESSED = 10 * 1024 * 1024; // 10 MB per HEC docs
+
+function hecBase() {
+  const url = (getCreds().S1_HEC_INGEST_URL || '').replace(/\/+$/, '');
+  if (!url) {
+    throw new Error(
+      'S1_HEC_INGEST_URL not configured. Add it to credentials.json ' +
+      '(e.g. "S1_HEC_INGEST_URL": "https://ingest.us1.sentinelone.net"). ' +
+      'Find the regional ingest URL at https://community.sentinelone.com/s/article/000004961'
+    );
+  }
+  return url;
+}
+
+function hecToken() {
+  const tok = getCreds().S1_CONSOLE_API_TOKEN;
+  if (!tok) {
+    throw new Error('S1_CONSOLE_API_TOKEN not configured. HEC uses the same Management Console API token as the Bearer.');
+  }
+  return tok;
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+/**
+ * Ingest raw logs/events into SDL via the HEC endpoint.
+ *
+ * @param {string} logContent  Raw text. For /raw, newline-separated lines become separate events.
+ * @param {object} [opts]
+ * @param {string} [opts.parser]    Parser name -> ?sourcetype=
+ * @param {object} [opts.fields]    Extra {key: value} pairs -> query params, each becomes a UI field.
+ *                              Avoid HEC-reserved keys (event, time, host, source, sourcetype, index, fields):
+ *                              HEC interprets those, they are not stored as custom fields. Use `parser` (not a field) to set sourcetype. (S-26.1 HEC docs, p.4708.)
+ * @param {string} opts.scope       REQUIRED. accountId or "accountId:siteId" -> S1-Scope header. HEC returns 400 "Missing S1-Scope header" without it.
+ * @param {('raw'|'event')} [opts.endpoint='raw']
+ * @param {boolean} [opts.compress=true]  gzip the body (Content-Encoding: gzip)
+ * @param {boolean} [opts.isParsed=false] /event only: set ?isParsed=true to index already-structured JSON fields without an SDL parser.
+ * @returns {Promise<{status:number, endpoint:string, url:string, body:any}>}
+ */
+export async function hecIngest(logContent, { parser, fields = {}, scope, endpoint = 'raw', compress = true, isParsed = false } = {}) {
+  if (typeof logContent !== 'string' || logContent.length === 0) {
+    throw new Error('hecIngest: logContent must be a non-empty string.');
+  }
+  if (endpoint !== 'raw' && endpoint !== 'event') {
+    throw new Error("hecIngest: endpoint must be 'raw' or 'event'.");
+  }
+  if (!scope || typeof scope !== 'string') {
+    throw new Error('hecIngest: scope is required. HEC rejects requests without an S1-Scope header (400 "Missing S1-Scope header"). Pass an accountId or "accountId:siteId".');
+  }
+
+  const qs = new URLSearchParams();
+  if (parser) qs.set('sourcetype', parser);
+  for (const [k, v] of Object.entries(fields || {})) qs.set(k, String(v));
+  if (isParsed) qs.set('isParsed', 'true');
+  const query = qs.toString();
+  const url = `${hecBase()}/services/collector/${endpoint}${query ? `?${query}` : ''}`;
+
+  const rawBuf = Buffer.from(logContent, 'utf-8');
+  if (rawBuf.length > MAX_UNCOMPRESSED) {
+    throw new Error(
+      `hecIngest: payload is ${rawBuf.length} bytes, over the 10 MB uncompressed HEC limit. ` +
+      'Split into smaller batches.'
+    );
+  }
+  const body = compress ? gzipSync(rawBuf) : rawBuf;
+
+  const headers = {
+    Authorization: `Bearer ${hecToken()}`,
+    'Content-Type': 'text/plain',
+  };
+  if (compress) headers['Content-Encoding'] = 'gzip';
+  headers['S1-Scope'] = scope;
+
+  let delay = 1000;
+  let lastErr;
+  for (let attempt = 0; attempt <= 3; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, { method: 'POST', headers, body });
+    } catch (err) {
+      lastErr = err;
+      if (attempt === 3) throw err;
+      await sleep(delay);
+      delay = Math.min(delay * 2, 8000);
+      continue;
+    }
+
+    if ((res.status === 429 || res.status >= 500) && attempt < 3) {
+      const retryAfter = res.headers.get('Retry-After');
+      await sleep(retryAfter ? parseInt(retryAfter, 10) * 1000 : delay);
+      delay = Math.min(delay * 2, 8000);
+      continue;
+    }
+
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = text; }
+
+    if (!res.ok) {
+      throw new Error(`HEC POST /services/collector/${endpoint} -> ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return { status: res.status, endpoint, url, body: data };
+  }
+  throw lastErr;
+}

package/lib/http-transport.js

@@ -0,0 +1,223 @@
+/**
+ * Streamable HTTP transport (MCP 2024-11-05 / 2025-06-18 compatible subset).
+ *
+ * Single endpoint:
+ *   POST /mcp     accept JSON-RPC, return JSON-RPC reply (Content-Type: application/json)
+ *   GET  /healthz return 200 OK (for load balancers / systemd readiness checks)
+ *   Any other path / method returns 404 or 405.
+ *
+ * The server is stateless: it does not maintain MCP sessions or push
+ * server-initiated notifications, so the spec-allowed SSE response form
+ * is not used. Clients that try to GET /mcp for a server-initiated stream
+ * receive 405 Method Not Allowed, which spec-compliant clients tolerate.
+ *
+ * Auth: if any tokens are loaded via lib/auth.js, every POST /mcp must
+ * carry "Authorization: Bearer <token>". Missing/invalid token -> 401.
+ *
+ * Audit: every authenticated request logs to stderr (captured by journald
+ * on systemd or by Docker on container runtimes):
+ *   timestamp | client-name | method | params-summary | response-status
+ *
+ * Zero external dependencies (uses node:http).
+ */
+
+import { createServer } from 'http';
+import { authenticate, isAuthConfigured, warnIfNoAuth, authSourceForLogging } from './auth.js';
+import { err as makeErr } from './server-core.js';
+
+const MAX_BODY_BYTES = 4 * 1024 * 1024; // 4 MB — well above any normal MCP call
+
+function log(...args) {
+  process.stderr.write('[sentinelone-mcp] ' + args.join(' ') + '\n');
+}
+
+function audit(line) {
+  process.stderr.write(`[audit] ${line}\n`);
+}
+
+function summarizeParams(params) {
+  if (!params || typeof params !== 'object') return '';
+  if (params.name) return `name=${params.name}`;       // tools/call
+  if (params.uri) return `uri=${params.uri}`;          // resources/read
+  return '';
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error(`Request body exceeds ${MAX_BODY_BYTES} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      try {
+        const raw = Buffer.concat(chunks).toString('utf-8');
+        resolve(raw);
+      } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+    'Cache-Control': 'no-store',
+  });
+  res.end(body);
+}
+
+function sendText(res, status, text) {
+  res.writeHead(status, {
+    'Content-Type': 'text/plain; charset=utf-8',
+    'Content-Length': Buffer.byteLength(text),
+    'Cache-Control': 'no-store',
+  });
+  res.end(text);
+}
+
+async function handleMcp(req, res, dispatch, clientIp) {
+  // Auth check (only if any tokens are configured)
+  let clientName = '-';
+  if (isAuthConfigured()) {
+    clientName = authenticate(req.headers['authorization']) || '';
+    if (!clientName) {
+      audit(`${new Date().toISOString()} | ${clientIp} | - | - | 401 unauthorized`);
+      sendJson(res, 401, makeErr(null, -32001, 'Unauthorized: missing or invalid bearer token'));
+      return;
+    }
+  } else {
+    clientName = `anon@${clientIp}`;
+  }
+
+  // Parse JSON body
+  let raw;
+  try {
+    raw = await readBody(req);
+  } catch (e) {
+    audit(`${new Date().toISOString()} | ${clientName} | - | - | 413 body-too-large`);
+    sendJson(res, 413, makeErr(null, -32600, e.message));
+    return;
+  }
+
+  if (!raw) {
+    sendJson(res, 400, makeErr(null, -32600, 'Empty body'));
+    return;
+  }
+
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch (e) {
+    audit(`${new Date().toISOString()} | ${clientName} | - | - | 400 parse-error`);
+    sendJson(res, 400, makeErr(null, -32700, `Parse error: ${e.message}`));
+    return;
+  }
+
+  // JSON-RPC batch: out of spec for Streamable HTTP MCP; reject explicitly.
+  if (Array.isArray(msg)) {
+    sendJson(res, 400, makeErr(null, -32600, 'Batch requests are not supported'));
+    return;
+  }
+
+  const isNotification = msg.id === undefined;
+  const ts = new Date().toISOString();
+
+  try {
+    const response = await dispatch(msg.method, msg.params, msg.id);
+
+    if (isNotification) {
+      // Per JSON-RPC, notifications get no reply; per MCP Streamable HTTP, return 202.
+      audit(`${ts} | ${clientName} | ${msg.method} | ${summarizeParams(msg.params)} | 202 notification`);
+      res.writeHead(202);
+      res.end();
+      return;
+    }
+
+    if (response === null) {
+      sendJson(res, 200, makeErr(msg.id ?? null, -32603, 'Internal error: empty response'));
+      return;
+    }
+
+    const status = response.error ? 200 : 200; // JSON-RPC errors are 200 with error envelope
+    audit(`${ts} | ${clientName} | ${msg.method} | ${summarizeParams(msg.params)} | ${response.error ? `200 jsonrpc-error (${response.error.code})` : '200 ok'}`);
+    sendJson(res, status, response);
+
+  } catch (e) {
+    log('Dispatch error:', e.message, e.stack);
+    audit(`${ts} | ${clientName} | ${msg.method || '-'} | ${summarizeParams(msg.params)} | 500 internal-error`);
+    if (!isNotification) {
+      sendJson(res, 500, makeErr(msg.id ?? null, -32603, `Internal error: ${e.message}`));
+    } else {
+      res.writeHead(500);
+      res.end();
+    }
+  }
+}
+
+export async function startHttp(dispatch, { port, host, path }) {
+  warnIfNoAuth(host);
+
+  const server = createServer(async (req, res) => {
+    const clientIp = req.socket.remoteAddress || '-';
+
+    // Health check
+    if (req.method === 'GET' && (req.url === '/healthz' || req.url === '/health')) {
+      sendText(res, 200, 'ok\n');
+      return;
+    }
+
+    // MCP endpoint
+    if (req.url === path) {
+      if (req.method === 'POST') {
+        await handleMcp(req, res, dispatch, clientIp);
+        return;
+      }
+      if (req.method === 'GET' || req.method === 'DELETE') {
+        // Spec-allowed but not implemented (no server-push, no sessions).
+        res.writeHead(405, { 'Allow': 'POST', 'Content-Type': 'text/plain' });
+        res.end('Method not allowed; this server accepts POST only.\n');
+        return;
+      }
+      res.writeHead(405, { 'Allow': 'POST', 'Content-Type': 'text/plain' });
+      res.end('Method not allowed\n');
+      return;
+    }
+
+    sendText(res, 404, 'Not found. The MCP endpoint is ' + path + '.\n');
+  });
+
+  server.on('error', (e) => {
+    log(`HTTP server error: ${e.message}`);
+    if (e.code === 'EADDRINUSE') {
+      log(`Port ${port} is already in use. Pick a different --port.`);
+      process.exit(1);
+    }
+  });
+
+  await new Promise((resolve) => server.listen(port, host, resolve));
+  const authMode = isAuthConfigured() ? authSourceForLogging() : 'NONE (warn)';
+  log(`Transport: streamableHttp listening on http://${host}:${port}${path} (auth: ${authMode})`);
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    log('SIGINT received, draining HTTP server...');
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 5000).unref();
+  });
+  process.on('SIGTERM', () => {
+    log('SIGTERM received, draining HTTP server...');
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 5000).unref();
+  });
+
+  return server;
+}

package/lib/s1.js

@@ -248,7 +248,7 @@ export async function lrqRun(query, { startTime, endTime, hours = 24, maxRows =
 }
 
 // ─── Purple AI ────────────────────────────────────────────────────────────────
-// Reverse-engineered from live network traffic on usea1-purple.sentinelone.net.
+// Reverse-engineered from live network traffic on usea1-acme.sentinelone.net.
 //
 // IMPORTANT: purpleLaunchQuery is a GraphQL QUERY (not mutation).
 // Variable wrapper is `request` (type PurpleLaunchQueryRequest), NOT `input`.

package/lib/sdl.js

@@ -5,7 +5,6 @@
  *   putFile             → config_write_key
  *   getFile / listFiles → config_write_key || config_read_key || console_api_token
  *   V1 query methods    → config_write_key || config_read_key || log_read_key || console_api_token
- *   uploadLogs          → log_write_key  (console token NOT accepted here)
  *
  * All SDL endpoints live at SDL_XDR_URL (e.g. https://xdr.us1.sentinelone.net).
  * The Authorization header is: Bearer <key>
@@ -30,7 +29,6 @@ function pickKey(chain) {
     // Confirmed: SDL_CONFIG_WRITE_KEY does NOT grant "View logs" permission on /api/query.
     // SDL_LOG_READ_KEY must be first in chain for V1 query to succeed.
     log_read:          [c.SDL_LOG_READ_KEY, c.SDL_CONFIG_READ_KEY, c.SDL_CONFIG_WRITE_KEY, c.S1_CONSOLE_API_TOKEN],
-    log_write_strict:  [c.SDL_LOG_WRITE_KEY],  // console token NOT accepted
   };
   const candidates = chains[chain] || chains.config_read;
   const key = candidates.find(k => k);
@@ -117,36 +115,6 @@ export async function deleteFile(path, expectedVersion) {
   return sdlFetch('POST', '/api/putFile', { body, chain: 'config_write' });
 }
 
-// ─── Log ingestion ────────────────────────────────────────────────────────────
-
-/** POST /api/uploadLogs — upload raw text log lines (newline-separated events). */
-export async function uploadLogs(logContent, { parser, serverHost, logfile } = {}) {
-  const extraHeaders = {};
-  if (parser)     extraHeaders['parser']      = parser;
-  if (serverHost) extraHeaders['server-host'] = serverHost;
-  if (logfile)    extraHeaders['logfile']      = logfile;
-
-  const raw = typeof logContent === 'string' ? Buffer.from(logContent, 'utf-8') : logContent;
-  return sdlFetch('POST', '/api/uploadLogs', {
-    chain: 'log_write_strict',
-    rawBody: raw,
-    contentType: 'text/plain',
-    extraHeaders,
-  });
-}
-
-/** POST /api/addEvents — ingest structured events (JSON). */
-export async function addEvents(events, session) {
-  const body = {
-    session: session || `mcp-${Date.now()}`,
-    events: events.map(e => ({
-      ts: e.ts || BigInt(Date.now()) * 1_000_000n,
-      attrs: e.attrs || e,
-    })),
-  };
-  return sdlFetch('POST', '/api/addEvents', { body, chain: 'log_write_strict' });
-}
-
 // ─── 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.