@pmoses-s1/s1-secops-mcp 1.3.0

package/lib/sdl.js

@@ -0,0 +1,130 @@
+/**
+ * SentinelOne Singularity Data Lake (SDL) API client.
+ *
+ * Auth: the console API token, sent as `Authorization: Bearer <token>`.
+ * It covers every SDL operation, config read, config write, and log read.
+ *
+ * All SDL endpoints live under `<console>/sdl`, derived from S1_CONSOLE_URL.
+ */
+
+import { getCreds } from './credentials.js';
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function sdlBase() {
+  const url = (getCreds().S1_CONSOLE_URL || '').replace(/\/+$/, '');
+  if (!url) throw new Error('S1_CONSOLE_URL not configured. Drop credentials.json into your project folder.');
+  return `${url}/sdl`;
+}
+
+/** The SDL credential: the console API token, used for every operation. */
+export function sdlToken() {
+  const token = getCreds().S1_CONSOLE_API_TOKEN;
+  if (!token) {
+    throw new Error('S1_CONSOLE_API_TOKEN not configured. Drop credentials.json into your project folder.');
+  }
+  return token;
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+function retryAfterMs(res, fallback) {
+  // Retry-After may be seconds OR an HTTP date; parseInt on a date yields NaN
+  // and sleep(NaN) fires immediately (no backoff). Validate and cap.
+  const raw = res.headers.get('Retry-After');
+  const secs = Number(raw);
+  if (raw && Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1000, 30000);
+  return fallback;
+}
+
+async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null, contentType = 'application/json' } = {}, retries = 3) {
+  const url = `${sdlBase()}${path}`;
+  const headers = {
+    Authorization: `Bearer ${sdlToken()}`,
+    'Content-Type': contentType,
+    ...extraHeaders,
+  };
+
+  let delay = 500;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: rawBody !== null ? rawBody : (body !== undefined ? JSON.stringify(body) : undefined),
+      });
+    } catch (err) {
+      if (attempt === retries) throw err;
+      await sleep(delay);
+      delay = Math.min(delay * 2, 8000);
+      continue;
+    }
+
+    if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+      await sleep(retryAfterMs(res, 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) {
+      const msg = typeof data === 'object' ? JSON.stringify(data) : text;
+      throw new Error(`SDL API ${method} ${path} → ${res.status}: ${msg}`);
+    }
+    return data;
+  }
+  throw new Error(`SDL API ${method} ${path}: request failed after retries`);
+}
+
+// ─── Config file operations ───────────────────────────────────────────────────
+
+/** POST /api/listFiles: list every configuration file path on the SDL tenant. */
+export async function listFiles() {
+  return sdlFetch('POST', '/api/listFiles', { body: {} });
+}
+
+/** POST /api/getFile: read a configuration file by path.
+ *  Returns { path, content, version, ...status }. */
+export async function getFile(path) {
+  return sdlFetch('POST', '/api/getFile', {
+    body: { path, prettyprint: true },
+  });
+}
+
+/** POST /api/putFile: create or update a configuration file.
+ *  Pass expectedVersion (from a prior getFile) to enable optimistic locking. */
+export async function putFile(path, content, expectedVersion) {
+  const body = { path, content };
+  if (expectedVersion !== undefined && expectedVersion !== null) {
+    body.expectedVersion = expectedVersion;
+  }
+  return sdlFetch('POST', '/api/putFile', { body });
+}
+
+/** POST /api/putFile with deleteFile:true deletes a config file. */
+export async function deleteFile(path, expectedVersion) {
+  const body = { path, deleteFile: true };
+  if (expectedVersion !== undefined) body.expectedVersion = expectedVersion;
+  return sdlFetch('POST', '/api/putFile', { body });
+}
+
+// ─── V1 Query (schema discovery) ─────────────────────────────────────────────
+// Deprecated Feb 15 2027 but still the only way to get full event JSON per-event.
+// Use for schema discovery; use LRQ for hunting.
+
+/** POST /api/query: retrieve raw event JSON for schema discovery.
+ *  Returns { matches: [{ timestamp, message, attributes }] }. */
+export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime } = {}) {
+  const body = {
+    queryType: 'log',
+    filter,
+    maxCount,
+    startTime,
+  };
+  if (endTime) body.endTime = endTime;
+  return sdlFetch('POST', '/api/query', { body });
+}

package/lib/server-core.js

@@ -0,0 +1,263 @@
+/**
+ * MCP server core: transport-agnostic.
+ *
+ * Exports:
+ *   - dispatch(method, params, id):    JSON-RPC method dispatcher
+ *   - SERVER_INFO, PROTOCOL_VERSION:    server identity
+ *   - TOOL_DEFS:                        for diagnostics / introspection
+ *   - ALL_TOOLS:                        for tests
+ *
+ * Both stdio-transport and http-transport import dispatch() and feed it
+ * parsed JSON-RPC envelopes. They are responsible for serialization,
+ * framing, and any transport-specific concerns (auth, sessions, headers).
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import { tools as pqTools }        from '../tools/powerquery.js';
+import { tools as mgmtTools }       from '../tools/mgmt-console.js';
+import { tools as sdlTools }        from '../tools/sdl-api.js';
+import { tools as haTools }         from '../tools/hyperautomation.js';
+import { tools as uamIngestTools }  from '../tools/uam-ingest.js';
+import { getCreds, hasS1Creds, hasSdlCreds } from './credentials.js';
+import { hasHecCreds } from './uam-ingest.js';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+
+// ─── SOC context (CLAUDE.md) ──────────────────────────────────────────────────
+
+function loadSocContext() {
+  const candidates = [
+    process.env.S1_CLAUDE_MD_PATH,
+    process.cwd() ? join(process.cwd(), 'CLAUDE.md') : null,
+    join(__dir, '..', '..', 'CLAUDE.md'),    // claude-skills/CLAUDE.md (git clone)
+    join(__dir, '..', '..', '..', 'CLAUDE.md'),
+    join(__dir, '..', 'CLAUDE.md'),
+  ].filter(Boolean);
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try { return readFileSync(p, 'utf-8'); } catch { /* skip */ }
+    }
+  }
+  return '# SentinelOne SOC Analyst Context\n\n_CLAUDE.md not found. Place it in your Cowork project folder, or set S1_CLAUDE_MD_PATH to an absolute path._';
+}
+
+const SOC_CONTEXT = loadSocContext();
+
+// ─── Tool registry ────────────────────────────────────────────────────────────
+
+export const ALL_TOOLS = [...pqTools, ...mgmtTools, ...sdlTools, ...haTools, ...uamIngestTools];
+
+export const TOOL_DEFS = ALL_TOOLS.map(t => ({
+  name: t.name,
+  description: t.description,
+  inputSchema: t.inputSchema,
+}));
+
+const HANDLERS = Object.fromEntries(ALL_TOOLS.map(t => [t.name, t.handler]));
+
+// ─── Resources ────────────────────────────────────────────────────────────────
+
+const RESOURCES = [
+  {
+    uri: 'sentinelone://soc-context',
+    name: 'SOC Analyst Operating Instructions',
+    description: 'CLAUDE.md: Principal SOC Analyst operating instructions including investigation workflow, evidence discipline, anomaly detection playbook, MITRE ATT&CK mapping, and tool usage priorities.',
+    mimeType: 'text/markdown',
+  },
+  {
+    uri: 'sentinelone://credentials-status',
+    name: 'Credential Configuration Status',
+    description: 'Reports which credentials are configured and which API surfaces are available.',
+    mimeType: 'application/json',
+  },
+];
+
+// ─── Prompts ──────────────────────────────────────────────────────────────────
+
+const PROMPTS = [
+  {
+    name: 'soc_analyst',
+    description: 'Load the Principal SOC Analyst system context from CLAUDE.md. Call at the start of every security investigation session to prime the operating instructions, evidence discipline rules, investigation workflow, and tool usage priorities.',
+    arguments: [],
+  },
+  {
+    name: 'session_init',
+    description: 'Structured session initialization prompt. Triggers mandatory data-source enumeration, alert triage, and schema discovery in parallel, mirroring the standard engagement workflow from the SOC playbook.',
+    arguments: [],
+  },
+];
+
+// ─── MCP envelope helpers ─────────────────────────────────────────────────────
+
+export const SERVER_INFO = {
+  name: 's1-secops-mcp-server',
+  version: '1.3.0',
+};
+
+export const PROTOCOL_VERSION = '2024-11-05';
+
+export function ok(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+export function err(id, code, message, data) {
+  return { jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } };
+}
+
+function log(...args) {
+  process.stderr.write('[s1-secops-mcp] ' + args.join(' ') + '\n');
+}
+
+// ─── dispatch ────────────────────────────────────────────────────────────────
+
+export async function dispatch(method, params, id) {
+  switch (method) {
+
+    case 'initialize': {
+      return ok(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          resources: { subscribe: false, listChanged: false },
+          tools: { listChanged: false },
+          prompts: { listChanged: false },
+        },
+        serverInfo: SERVER_INFO,
+        instructions: 'SentinelOne MCP server providing PowerQuery, Mgmt Console API, SDL API, and Hyperautomation tools. Load the "soc_analyst" prompt at session start for full operating context.',
+      });
+    }
+
+    case 'ping': {
+      return ok(id, {});
+    }
+
+    case 'resources/list': {
+      return ok(id, { resources: RESOURCES });
+    }
+
+    case 'resources/read': {
+      const uri = params?.uri;
+      if (uri === 'sentinelone://soc-context') {
+        return ok(id, {
+          contents: [{ uri, mimeType: 'text/markdown', text: SOC_CONTEXT }],
+        });
+      }
+      if (uri === 'sentinelone://credentials-status') {
+        const c = getCreds();
+        const status = {
+          s1MgmtApi: {
+            configured: hasS1Creds(),
+            consoleUrl: c.S1_CONSOLE_URL ? c.S1_CONSOLE_URL.replace(/https?:\/\//, '').split('.')[0] + '...' : 'NOT SET',
+            tokenPresent: !!c.S1_CONSOLE_API_TOKEN,
+          },
+          sdlApi: {
+            configured: hasSdlCreds(),
+            tokenPresent: !!c.S1_CONSOLE_API_TOKEN,
+          },
+          uamIngestApi: {
+            configured: hasHecCreds(),
+            hecUrl: c.S1_HEC_INGEST_URL || 'NOT SET (add S1_HEC_INGEST_URL to credentials.json)',
+            tokenPresent: !!c.S1_CONSOLE_API_TOKEN,
+          },
+        };
+        return ok(id, {
+          contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(status, null, 2) }],
+        });
+      }
+      return err(id, -32002, `Resource not found: ${uri}`);
+    }
+
+    case 'prompts/list': {
+      return ok(id, { prompts: PROMPTS });
+    }
+
+    case 'prompts/get': {
+      const name = params?.name;
+
+      if (name === 'soc_analyst') {
+        return ok(id, {
+          description: 'Principal SOC Analyst operating instructions from CLAUDE.md',
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `You are operating as a Principal SOC Analyst. Load and follow the instructions below precisely.\n\n${SOC_CONTEXT}`,
+              },
+            },
+          ],
+        });
+      }
+
+      if (name === 'session_init') {
+        return ok(id, {
+          description: 'Structured session initialization',
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Begin a new SOC analyst session. Follow this initialization sequence:
+
+1. Call \`powerquery_enumerate_sources\` to discover active SDL data sources (MANDATORY, never assume sources from prior sessions).
+2. In parallel, call \`uam_list_alerts\` with status="NEW" to pull untriaged active alerts. Valid status values are "NEW", "IN_PROGRESS", or "RESOLVED" (there is no "OPEN" status; it silently returns 0 results). Omit the status argument to pull the most recent alerts across all states.
+3. For each discovered data source not already in the schema registry, plan schema discovery via \`powerquery_schema_discover\`.
+4. Report: (a) active data sources list, (b) untriaged (NEW) alert count and top 5 by severity, (c) which sources need schema discovery.
+
+Apply the SOC analyst context from the soc_analyst prompt throughout.`,
+              },
+            },
+          ],
+        });
+      }
+
+      return err(id, -32002, `Prompt not found: ${name}`);
+    }
+
+    case 'tools/list': {
+      return ok(id, { tools: TOOL_DEFS });
+    }
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const args = params?.arguments || {};
+
+      if (!toolName) {
+        return err(id, -32602, 'Missing tool name');
+      }
+
+      const handler = HANDLERS[toolName];
+      if (!handler) {
+        return err(id, -32602, `Tool not found: ${toolName}`);
+      }
+
+      try {
+        const output = await handler(args);
+        const text = typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+        return ok(id, {
+          content: [{ type: 'text', text }],
+          isError: false,
+        });
+      } catch (e) {
+        log(`Tool error [${toolName}]:`, e.message);
+        return ok(id, {
+          content: [{ type: 'text', text: `Error: ${e.message}` }],
+          isError: true,
+        });
+      }
+    }
+
+    case 'notifications/initialized':
+    case 'initialized':
+      return null;
+
+    default: {
+      if (id !== undefined) {
+        return err(id, -32601, `Method not found: ${method}`);
+      }
+      return null;
+    }
+  }
+}

package/lib/stdio-transport.js

@@ -0,0 +1,77 @@
+/**
+ * stdio transport: reads JSON-RPC messages from stdin (one per line),
+ * dispatches via the provided dispatcher, writes responses to stdout.
+ *
+ * This is the default transport and the one used by Claude Desktop,
+ * Claude Code, Claude Cowork, and any other client launched via the
+ * `npx` / `node index.js` invocation pattern.
+ */
+
+import { createInterface } from 'readline';
+import { err as makeErr } from './server-core.js';
+
+function log(...args) {
+  process.stderr.write('[s1-secops-mcp] ' + args.join(' ') + '\n');
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+export async function startStdio(dispatch) {
+  log('Transport: stdio');
+
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  let inFlight = 0;
+  let stdinClosed = false;
+
+  function maybeExit() {
+    if (stdinClosed && inFlight === 0) {
+      log('All requests complete, exiting.');
+      process.exit(0);
+    }
+  }
+
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch (e) {
+      send(makeErr(null, -32700, `Parse error: ${e.message}`));
+      return;
+    }
+
+    const isNotification = msg.id === undefined;
+
+    inFlight++;
+    try {
+      const response = await dispatch(msg.method, msg.params, msg.id);
+      if (response !== null && !isNotification) {
+        send(response);
+      }
+    } catch (e) {
+      log('Unhandled dispatch error:', e.message, e.stack);
+      if (!isNotification) {
+        send(makeErr(msg.id ?? null, -32603, `Internal error: ${e.message}`));
+      }
+    } finally {
+      inFlight--;
+      maybeExit();
+    }
+  });
+
+  rl.on('close', () => {
+    log('stdin closed, waiting for in-flight requests...');
+    stdinClosed = true;
+    maybeExit();
+  });
+
+  process.on('SIGINT', () => {
+    log('SIGINT received, exiting.');
+    process.exit(0);
+  });
+}