@pmoses-s1/sentinelone-mcp 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# SentinelOne MCP Server
+
+A Model Context Protocol (MCP) server that orchestrates all six SentinelOne skills and their APIs. Built in pure Node.js 18+ with zero external dependencies.
+
+## What this exposes
+
+**19 tools** covering every skill in the plugin:
+
+| Group | Tool | Skill |
+|-------|------|-------|
+| PowerQuery | `powerquery_enumerate_sources` | sentinelone-powerquery |
+| PowerQuery | `powerquery_run` | sentinelone-powerquery |
+| PowerQuery | `powerquery_schema_discover` | sentinelone-powerquery |
+| Mgmt Console | `s1_api_get` | sentinelone-mgmt-console-api |
+| Mgmt Console | `s1_api_post` | sentinelone-mgmt-console-api |
+| Mgmt Console | `purple_ai_query` | sentinelone-mgmt-console-api |
+| Mgmt Console | `uam_list_alerts` | sentinelone-mgmt-console-api |
+| Mgmt Console | `uam_get_alert` | sentinelone-mgmt-console-api |
+| Mgmt Console | `uam_add_note` | sentinelone-mgmt-console-api |
+| Mgmt Console | `uam_set_status` | sentinelone-mgmt-console-api |
+| SDL API | `sdl_list_files` | sentinelone-sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_get_file` | sentinelone-sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_put_file` | sentinelone-sdl-api / sdl-dashboard / sdl-log-parser |
+| SDL API | `sdl_delete_file` | sentinelone-sdl-api |
+| SDL API | `sdl_upload_logs` | sentinelone-sdl-api / sdl-log-parser |
+| Hyperautomation | `ha_list_workflows` | sentinelone-hyperautomation |
+| Hyperautomation | `ha_get_workflow` | sentinelone-hyperautomation |
+| Hyperautomation | `ha_import_workflow` | sentinelone-hyperautomation |
+| Hyperautomation | `ha_export_workflow` | sentinelone-hyperautomation |
+
+**2 resources:**
+- `sentinelone://soc-context`: CLAUDE.md (full SOC analyst operating instructions)
+- `sentinelone://credentials-status`: Which credentials are configured
+
+**2 prompts:**
+- `soc_analyst`: Embeds CLAUDE.md as a system prompt; call at session start
+- `session_init`: Structured initialization: enumerate sources + triage alerts in parallel
+
+## Prerequisites
+
+- Node.js 18 or later
+- No `npm install` needed: zero external dependencies
+
+## Credentials
+
+Credentials are passed as environment variables in `claude_desktop_config.json` (see Installation below). The server also auto-discovers a `credentials.json` file by searching from the working directory upward as a backwards-compatible fallback for direct-skill users.
+
+`S1_CONSOLE_URL` and `S1_CONSOLE_API_TOKEN` are sufficient for most tools. Add the SDL keys only if you need `sdl_upload_logs` (requires `SDL_LOG_WRITE_KEY`) or `sdl_put_file` (requires `SDL_CONFIG_WRITE_KEY`).
+
+| Variable | Description |
+|----------|-------------|
+| `S1_CONSOLE_URL` | Your console URL, e.g. `https://usea1-acme.sentinelone.net` |
+| `S1_CONSOLE_API_TOKEN` | Management Console API token (Settings → Users → Service Users) |
+| `S1_HEC_INGEST_URL` | HEC ingest host, e.g. `https://ingest.us1.sentinelone.net` |
+| `SDL_XDR_URL` | SDL tenant URL, e.g. `https://xdr.us1.sentinelone.net` |
+| `SDL_LOG_WRITE_KEY` | SDL Log Write key (required for `sdl_upload_logs` only) |
+| `SDL_LOG_READ_KEY` | SDL Log Read key (required for SDL query operations) |
+| `SDL_CONFIG_WRITE_KEY` | SDL Config Write key (required for `sdl_put_file`) |
+| `SDL_CONFIG_READ_KEY` | SDL Config Read key (required for `sdl_list_files`, `sdl_get_file`) |
+
+## Run the server
+
+```bash
+# From the published npm package (no clone, no install)
+npx -y @pmoses-s1/sentinelone-mcp
+
+# Or from a local clone (development)
+node /path/to/claude-skills/sentinelone-mcp/index.js
+```
+
+## Installation
+
+### Why you need this (or the allowlist alternative)
+
+The Claude sandbox proxy blocks outbound HTTPS to `*.sentinelone.net` by default. There are two ways to fix this:
+
+**Option A: Install sentinelone-mcp (recommended).** The MCP server runs as a local process on your machine outside the sandbox. All API calls go directly from your machine to SentinelOne, bypassing the sandbox proxy entirely. No allowlist changes needed.
+
+**Option B: Add `*.sentinelone.net` to the Claude sandbox allowlist.** In Claude Desktop go to Settings → Claude Code → Network Access and add `*.sentinelone.net` to the allowed domains. This lets the skills' Python scripts reach the API directly from inside the sandbox. Use this if you prefer to keep everything running in the sandbox rather than install a local server.
+
+Most users should use Option A: it requires no admin changes and keeps credentials out of the sandbox environment.
+
+### Option A: Add to Claude Desktop
+
+In `~/Library/Application Support/Claude/claude_desktop_config.json`, add the `sentinelone-mcp` entry to your `mcpServers` block. The server runs via `npx` directly from npm, so there is no clone, no install, and no absolute path to manage. Credentials go in the `env` section:
+
+```json
+{
+  "mcpServers": {
+    "sentinelone-mcp": {
+      "command": "npx",
+      "args": ["-y", "@pmoses-s1/sentinelone-mcp"],
+      "env": {
+        "S1_CONSOLE_URL":        "https://usea1-yourorg.sentinelone.net",
+        "S1_CONSOLE_API_TOKEN":  "eyJ...your-api-token...",
+        "S1_HEC_INGEST_URL":     "https://ingest.us1.sentinelone.net",
+        "SDL_XDR_URL":           "https://xdr.us1.sentinelone.net",
+        "SDL_LOG_WRITE_KEY":     "0Z1Fy0...",
+        "SDL_LOG_READ_KEY":      "0tzj...",
+        "SDL_CONFIG_WRITE_KEY":  "0mXas6PD...",
+        "SDL_CONFIG_READ_KEY":   "0MQTx..."
+      }
+    }
+  }
+}
+```
+
+`npx -y` answers "yes" to the install prompt on first launch, fetches the package, and caches it. Subsequent launches start instantly from the cache. Restart Claude Desktop after saving.
+
+`S1_CONSOLE_URL` and `S1_CONSOLE_API_TOKEN` are the minimum required for most tools. Include the SDL keys only if you need log ingest or parser/dashboard deploy. Set `S1_CLAUDE_MD_PATH` if you keep CLAUDE.md outside your Cowork project folder.
+
+### Option A: Add to Claude Code
+
+In `.mcp.json` at your project root, or `~/.mcp.json` globally. Same npx invocation, same env block:
+
+```json
+{
+  "mcpServers": {
+    "sentinelone-mcp": {
+      "command": "npx",
+      "args": ["-y", "@pmoses-s1/sentinelone-mcp"],
+      "env": {
+        "S1_CONSOLE_URL":       "https://usea1-yourorg.sentinelone.net",
+        "S1_CONSOLE_API_TOKEN": "eyJ...your-api-token..."
+      }
+    }
+  }
+}
+```
+
+### Option A: Run from a local clone (development only)
+
+If you are developing the MCP server itself, replace the `npx` invocation with a path to your clone:
+
+```json
+"sentinelone-mcp": {
+  "command": "node",
+  "args": ["/absolute/path/to/claude-skills/sentinelone-mcp/index.js"],
+  "env": { "...": "..." }
+}
+```
+
+### Option B: Sandbox allowlist (no MCP server)
+
+If you prefer to run API calls from inside the Claude sandbox rather than install a local server, add `*.sentinelone.net` to the network allowlist:
+
+1. Open Claude Desktop → Settings → Claude Code → Network Access
+2. Add `*.sentinelone.net` to the allowed domains
+3. Restart Claude Desktop
+
+The skills' Python scripts (`s1_client.py`, `sdl_client.py`, etc.) will then reach the API directly. No MCP server required for the skills to work.
+
+## Workflow: session startup
+
+When connecting to this MCP server, start every session with:
+
+1. Read the `soc_analyst` prompt (or the `sentinelone://soc-context` resource) to load operating instructions from CLAUDE.md.
+2. Call `powerquery_enumerate_sources` to discover active SDL data sources (mandatory: never assume sources from a prior session).
+3. In parallel, call `uam_list_alerts` with `filter="status=OPEN"` to pull active alerts.
+
+The `session_init` prompt automates steps 2-3 as a structured prompt.
+
+## Architecture
+
+```
+sentinelone-mcp/
+  index.js              Raw MCP JSON-RPC over stdio (no SDK dependency)
+  lib/
+    credentials.js      Auto-discovers credentials.json (env vars > file > walk-up > ~/mnt/*)
+    s1.js               S1 Mgmt REST API + LRQ PowerQuery + Purple AI + UAM GraphQL
+    sdl.js              SDL config files (get/put/list) + V1 query + uploadLogs
+  tools/
+    powerquery.js       PowerQuery enumerate/run/schema-discover tools
+    mgmt-console.js     S1 REST + Purple AI + UAM tools
+    sdl-api.js          SDL config file + log ingestion tools
+    hyperautomation.js  Hyperautomation list/get/import/export tools
+  README.md
+```
+
+## 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` |
+| SDL config ops | `Authorization: Bearer <key>` | `SDL_CONFIG_WRITE_KEY` or console JWT |
+| SDL uploadLogs | `Authorization: Bearer <key>` | `SDL_LOG_WRITE_KEY` only (console JWT rejected) |
+
+## Updating CLAUDE.md
+
+The `sentinelone://soc-context` resource and `soc_analyst` prompt load CLAUDE.md at server startup. Resolution order (highest priority wins):
+
+1. `S1_CLAUDE_MD_PATH` env var (explicit absolute path)
+2. `<cwd>/CLAUDE.md` (your Cowork project folder when launched from a project)
+3. Same-dir / parent / grandparent of the server's `index.js` (when running from a git clone)
+
+For npx installs, drop a copy of CLAUDE.md into your Cowork project folder, or set `S1_CLAUDE_MD_PATH` in the `env` block of `claude_desktop_config.json`. Restart Claude Desktop to pick up changes.

package/index.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * SentinelOne MCP Server
+ *
+ * Implements the Model Context Protocol (MCP) over stdio using raw JSON-RPC 2.0.
+ * No external dependencies — pure Node.js 18+.
+ *
+ * Exposes:
+ *   Resources  : sentinelone://soc-context  (CLAUDE.md SOC analyst operating instructions)
+ *   Prompts    : soc_analyst                (system prompt embedding CLAUDE.md)
+ *   Tools (21) : PowerQuery, Mgmt Console, SDL API, Hyperautomation, UAM Ingest
+ *
+ * Run as: node index.js
+ * Configure in claude_desktop_config.json or .mcp.json — see README.md.
+ */
+
+import { createInterface } from 'readline';
+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 './lib/credentials.js';
+import { hasHecCreds } from './lib/uam-ingest.js';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+
+// ─── SOC context (CLAUDE.md) ──────────────────────────────────────────────────
+
+function loadSocContext() {
+  // Resolution order (highest priority wins):
+  //   1. S1_CLAUDE_MD_PATH env var (explicit override, e.g. set by claude_desktop_config.json)
+  //   2. <cwd>/CLAUDE.md (Cowork project folder when launched from a project)
+  //   3. relative to this server's install dir (works when running from a git clone)
+  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'),       // project root (git clone)
+    join(__dir, 'CLAUDE.md'),                   // same dir
+  ].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 ────────────────────────────────────────────────────────────
+
+const ALL_TOOLS = [...pqTools, ...mgmtTools, ...sdlTools, ...haTools, ...uamIngestTools];
+
+// MCP tool schema (inputSchema is JSON Schema)
+const TOOL_DEFS = ALL_TOOLS.map(t => ({
+  name: t.name,
+  description: t.description,
+  inputSchema: t.inputSchema,
+}));
+
+// Handler map
+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 protocol ─────────────────────────────────────────────────────────────
+
+const SERVER_INFO = {
+  name: 'sentinelone-mcp-server',
+  version: '1.0.0',
+};
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+function ok(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function err(id, code, message, data) {
+  return { jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } };
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+function log(...args) {
+  process.stderr.write('[sentinelone-mcp] ' + args.join(' ') + '\n');
+}
+
+// ─── Method handlers ──────────────────────────────────────────────────────────
+
+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(),
+            xdrUrl: c.SDL_XDR_URL || 'NOT SET',
+            configWriteKey: !!c.SDL_CONFIG_WRITE_KEY,
+            logWriteKey: !!c.SDL_LOG_WRITE_KEY,
+          },
+          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 filter="status=OPEN" to pull active alerts.
+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) open 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,
+        });
+      }
+    }
+
+    // Notifications have no id — just ignore
+    case 'notifications/initialized':
+    case 'initialized':
+      return null;
+
+    default: {
+      if (id !== undefined) {
+        return err(id, -32601, `Method not found: ${method}`);
+      }
+      return null;
+    }
+  }
+}
+
+// ─── Main loop ────────────────────────────────────────────────────────────────
+
+async function main() {
+  log(`Starting (node ${process.version})`);
+
+  const creds = getCreds();
+  log(`S1 Mgmt API:  ${hasS1Creds() ? 'configured (' + creds.S1_CONSOLE_URL + ')' : 'NOT configured'}`);
+  log(`SDL API:      ${hasSdlCreds() ? 'configured (' + creds.SDL_XDR_URL + ')' : 'NOT configured'}`);
+  log(`UAM Ingest:   ${hasHecCreds() ? 'configured (' + creds.S1_HEC_INGEST_URL + ')' : 'NOT configured (add S1_HEC_INGEST_URL to credentials.json)'}`);
+  log(`Tools:        ${ALL_TOOLS.length} registered`);
+
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  // Track in-flight async requests so we don't exit while one is still running
+  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(err(null, -32700, `Parse error: ${e.message}`));
+      return;
+    }
+
+    // Notification (no id) — handle but don't respond
+    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(err(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);
+  });
+}
+
+main().catch(e => {
+  process.stderr.write(`Fatal: ${e.message}\n${e.stack}\n`);
+  process.exit(1);
+});

package/lib/credentials.js

@@ -0,0 +1,116 @@
+/**
+ * Credential loader — zero dependencies, synchronous.
+ *
+ * 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
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+const CRED_FILENAMES = [
+  'credentials.json',
+  '.sentinelone/credentials.json',
+  '.claude/sentinelone/credentials.json',
+];
+
+const MNT_SKIP = new Set(['.claude', '.auto-memory', '.remote-plugins', 'outputs', 'uploads']);
+
+function tryLoad(dir) {
+  for (const rel of CRED_FILENAMES) {
+    const p = join(dir, rel);
+    if (existsSync(p)) {
+      try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { /* bad JSON */ }
+    }
+  }
+  return null;
+}
+
+function discoverCredentials() {
+  // 1. COWORK_WORKSPACE env override
+  const ws = process.env.COWORK_WORKSPACE;
+  if (ws) {
+    const found = tryLoad(ws);
+    if (found) return found;
+  }
+
+  // 2. Walk up from cwd
+  let dir;
+  try { dir = process.cwd(); } catch { dir = '/'; }
+  for (let i = 0; i < 20; i++) {
+    const found = tryLoad(dir);
+    if (found) return found;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // 3. ~/mnt/* scan (Cowork workspace mounts)
+  const homeMnt = join(homedir(), 'mnt');
+  if (existsSync(homeMnt)) {
+    try {
+      const entries = readdirSync(homeMnt, { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isDirectory() || MNT_SKIP.has(e.name)) continue;
+        const found = tryLoad(join(homeMnt, e.name));
+        if (found) return found;
+      }
+    } catch { /* skip */ }
+  }
+
+  // 4. CLAUDE_CONFIG_DIR plugin creds
+  const ccDir = process.env.CLAUDE_CONFIG_DIR;
+  if (ccDir) {
+    const p = join(ccDir, 'sentinelone', 'credentials.json');
+    if (existsSync(p)) {
+      try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { /* bad JSON */ }
+    }
+  }
+
+  // 5. ~/.config/sentinelone/credentials.json
+  const configPath = join(homedir(), '.config', 'sentinelone', 'credentials.json');
+  if (existsSync(configPath)) {
+    try { return JSON.parse(readFileSync(configPath, 'utf-8')); } catch { /* bad JSON */ }
+  }
+
+  return {};
+}
+
+// Load once at module init
+const _file = discoverCredentials();
+
+/**
+ * Returns merged credentials. Environment variables take precedence over file values.
+ */
+export function getCreds() {
+  const e = (key) => process.env[key] || _file[key] || '';
+  return {
+    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'),
+    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'),
+    VT_API_KEY:           e('VT_API_KEY'),
+  };
+}
+
+/** True if minimum required credentials for S1 Mgmt API are present. */
+export function hasS1Creds() {
+  const c = getCreds();
+  return !!(c.S1_CONSOLE_URL && c.S1_CONSOLE_API_TOKEN);
+}
+
+/** True if minimum required credentials for SDL are present. */
+export function hasSdlCreds() {
+  const c = getCreds();
+  return !!(c.SDL_XDR_URL && (c.SDL_CONFIG_WRITE_KEY || c.S1_CONSOLE_API_TOKEN));
+}