@pmoses-s1/s1-secops-mcp 1.3.0

package/lib/auth.js

@@ -0,0 +1,161 @@
+/**
+ * Bearer token auth loader for HTTP transport.
+ *
+ * Sources (highest wins):
+ *   1. MCP_BEARER_TOKENS_FILE: path to JSON: { "<name>": "<token>", ... }
+ *      Allows per-user tokens with stable names for audit logs.
+ *      File mode is enforced via the install script (0600 recommended).
+ *   2. MCP_BEARER_TOKENS: comma-separated raw tokens (no per-user names).
+ *      Names default to "token-1", "token-2", etc.
+ *
+ * If neither is set, HTTP transport runs with NO authentication. The server
+ * logs a loud warning at startup. Suitable only for stdio-style local-only
+ * deployments where the bind address is 127.0.0.1 and no other process can
+ * reach the port.
+ *
+ * SIGHUP reloads the token store without restarting the server, so rotation
+ * is "edit file, kill -HUP <pid>" with zero downtime.
+ *
+ * Zero dependencies. Synchronous load, async reload via SIGHUP.
+ */
+
+import { readFileSync, existsSync, statSync } from 'fs';
+
+let _tokens = new Map();   // token -> name
+let _loadedFrom = null;
+let _warnedNoAuth = false;
+
+function parseFileTokens(path) {
+  const raw = readFileSync(path, 'utf-8');
+  const obj = JSON.parse(raw);
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('MCP_BEARER_TOKENS_FILE must contain a JSON object of {name: token}');
+  }
+  const m = new Map();
+  for (const [name, token] of Object.entries(obj)) {
+    if (typeof token !== 'string' || token.length < 16) {
+      throw new Error(`Token for "${name}" must be a string of at least 16 chars`);
+    }
+    m.set(token, name);
+  }
+  return m;
+}
+
+function parseEnvTokens(raw) {
+  const m = new Map();
+  const parts = raw.split(',').map(s => s.trim()).filter(Boolean);
+  parts.forEach((token, i) => {
+    if (token.length < 16) {
+      throw new Error(`Token #${i + 1} in MCP_BEARER_TOKENS must be at least 16 chars`);
+    }
+    m.set(token, `token-${i + 1}`);
+  });
+  return m;
+}
+
+function logModeForPath(path) {
+  try {
+    const s = statSync(path);
+    const mode = (s.mode & 0o777).toString(8);
+    if ((s.mode & 0o077) !== 0) {
+      process.stderr.write(
+        `[auth] WARNING: ${path} mode is ${mode}; recommended 0600. ` +
+        `Run: chmod 600 ${path}\n`
+      );
+    }
+    return mode;
+  } catch { return null; }
+}
+
+export function loadTokens() {
+  const filePath = process.env.MCP_BEARER_TOKENS_FILE;
+  const envRaw   = process.env.MCP_BEARER_TOKENS;
+
+  if (filePath) {
+    if (!existsSync(filePath)) {
+      throw new Error(`MCP_BEARER_TOKENS_FILE points at non-existent path: ${filePath}`);
+    }
+    _tokens = parseFileTokens(filePath);
+    _loadedFrom = `file:${filePath}`;
+    const mode = logModeForPath(filePath);
+    process.stderr.write(
+      `[auth] Loaded ${_tokens.size} bearer token(s) from ${filePath} (mode ${mode || 'unknown'})\n`
+    );
+    return _tokens.size;
+  }
+
+  if (envRaw) {
+    _tokens = parseEnvTokens(envRaw);
+    _loadedFrom = 'env:MCP_BEARER_TOKENS';
+    process.stderr.write(
+      `[auth] Loaded ${_tokens.size} bearer token(s) from MCP_BEARER_TOKENS env var\n`
+    );
+    return _tokens.size;
+  }
+
+  _tokens = new Map();
+  _loadedFrom = null;
+  return 0;
+}
+
+/**
+ * Returns true if any token store is configured. When false, HTTP transport
+ * must either (a) refuse to start, or (b) start with a loud warning,
+ * depending on caller policy.
+ */
+export function isAuthConfigured() {
+  return _tokens.size > 0;
+}
+
+/**
+ * Validates an Authorization header value and returns the matched token name
+ * (for audit logging), or null if the header is missing/invalid.
+ *
+ * Accepts:  "Bearer <token>"
+ * Rejects:  empty, malformed, unknown token.
+ */
+export function authenticate(authHeader) {
+  if (!authHeader || typeof authHeader !== 'string') return null;
+  const m = authHeader.match(/^Bearer\s+(.+)$/i);
+  if (!m) return null;
+  const token = m[1].trim();
+  return _tokens.get(token) || null;
+}
+
+/**
+ * Warn once if HTTP transport is enabled with no auth. Caller invokes this
+ * at startup.
+ */
+export function warnIfNoAuth(host) {
+  if (!isAuthConfigured() && !_warnedNoAuth) {
+    _warnedNoAuth = true;
+    const reachable = host !== '127.0.0.1' && host !== 'localhost';
+    process.stderr.write(
+      `[auth] WARNING: HTTP transport is running with NO authentication.\n` +
+      (reachable
+        ? `[auth] WARNING: bound to ${host} (reachable from other hosts). ` +
+          `Set MCP_BEARER_TOKENS_FILE or MCP_BEARER_TOKENS, or bind to 127.0.0.1.\n`
+        : `[auth] (Bound to ${host}; OK for purely local single-user use, ` +
+          `not OK for team / VM deployments.)\n`)
+    );
+  }
+}
+
+export function authSourceForLogging() {
+  return _loadedFrom;
+}
+
+/**
+ * Install a SIGHUP handler that reloads tokens from the same source.
+ * Returns nothing; intended to be called once at startup.
+ */
+export function installSighupReload() {
+  process.on('SIGHUP', () => {
+    try {
+      const n = loadTokens();
+      process.stderr.write(`[auth] SIGHUP: reloaded, ${n} token(s) active\n`);
+    } catch (e) {
+      process.stderr.write(`[auth] SIGHUP: reload FAILED, keeping previous tokens: ${e.message}\n`);
+    }
+  });
+}

package/lib/credentials.js

@@ -0,0 +1,124 @@
+/**
+ * Credential loader: zero dependencies, synchronous.
+ *
+ * Resolution order (highest wins):
+ *   1. Environment variables
+ *   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';
+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. 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);
+    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'),
+    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.
+ *  SDL lives under <console>/sdl and uses the console API token. */
+export function hasSdlCreds() {
+  const c = getCreds();
+  return !!(c.S1_CONSOLE_URL && c.S1_CONSOLE_API_TOKEN);
+}

package/lib/hec.js

@@ -0,0 +1,144 @@
+/**
+ * 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']
+ *                              For 'event', logContent must be newline-separated HEC JSON envelopes:
+ *                              {"time": <epoch seconds>, "event": <string|object>, "fields": {...}}.
+ *                              The body is passed through verbatim and Content-Type is application/json,
+ *                              so per-event "time" BACKDATES the event (live-verified 2026-07-29; with the
+ *                              old text/plain Content-Type the envelope was indexed as opaque text at
+ *                              receive time and "time" was ignored).
+ * @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()}`,
+    // /event takes HEC JSON envelopes and must be application/json, or the
+    // envelope (including per-event "time") is treated as opaque text and the
+    // event is indexed at receive time. /raw is plain text. Fixed 2026-07-29.
+    'Content-Type': endpoint === 'event' ? 'application/json' : '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;
+    }
+
+    // 429 means the request was rejected before processing: safe to retry.
+    // 5xx after a raw-log POST is ambiguous (the events may already be
+    // committed) and HEC has no idempotency key, so retrying risks duplicate
+    // events inflating SDL counts. Fixed 2026-07-29: no automatic 5xx retry.
+    if (res.status === 429 && attempt < 3) {
+      // Retry-After may be missing or an HTTP date. Number(null) is 0, so a
+      // missing header must fall back to the exponential delay, not sleep 0ms.
+      const raRaw = res.headers.get('Retry-After');
+      const ra = Number(raRaw);
+      await sleep(raRaw && Number.isFinite(ra) && ra >= 0 ? Math.min(ra * 1000, 30000) : 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;
+}