@pmoses-s1/sentinelone-mcp 1.0.0

package/tools/powerquery.js

@@ -0,0 +1,124 @@
+/**
+ * PowerQuery tools — sentinelone-powerquery skill
+ *
+ * Tools:
+ *   powerquery_run            Run a PowerQuery via the LRQ API
+ *   powerquery_schema_discover Discover field schema for a data source via V1 query
+ *   powerquery_enumerate_sources List all data sources active in SDL (session init)
+ */
+
+import { lrqRun } from '../lib/s1.js';
+import { v1Query } from '../lib/sdl.js';
+
+export const tools = [
+  // ─── powerquery_enumerate_sources ─────────────────────────────────────────
+  {
+    name: 'powerquery_enumerate_sources',
+    description: `MANDATORY SESSION INIT: Run the standard data-source enumeration query to discover every dataSource.name, dataSource.vendor, and dataSource.category active in this SDL tenant. Always call this at the start of every session before writing any hunt queries. Results are environment-specific and can change between sessions as integrations are added or removed. Never assume sources from a prior session.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        hours: {
+          type: 'number',
+          description: 'Lookback window in hours (default 24). Increase to 168 (7d) if the last 24h had low volume.',
+          default: 24,
+        },
+      },
+      required: [],
+    },
+    async handler({ hours = 24 } = {}) {
+      const query = `| group UniqueDataSourceNames = array_agg_distinct(dataSource.name),
+        UniqueVendors = array_agg_distinct(dataSource.vendor),
+        UniqueCategories = array_agg_distinct(dataSource.category)
+| limit 1000`;
+      const result = await lrqRun(query, { hours });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── powerquery_run ────────────────────────────────────────────────────────
+  {
+    name: 'powerquery_run',
+    description: `Run a SentinelOne PowerQuery against the Singularity Data Lake using the LRQ API. The LRQ API is async — this tool handles the full launch-poll-cancel lifecycle and returns results. Use for threat hunting, telemetry analysis, dashboard panel validation, and STAR rule testing. Auth: Bearer <jwt> (same token as mgmt API). Time range defaults to last 24 hours if startTime/endTime are omitted.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The PowerQuery string. Use pipe-separated commands: | filter | group | sort | limit | columns. Three distinct wildcard idioms — use the right one: (1) FIELD PRESENCE / ATTRIBUTE WILDCARD: field=* means "field is present/non-null", e.g. dataSource.name=* | group count=count() by dataSource.name — use this as a query-opener or whenever you need "all events that have this field". (2) ALL-COLUMN TEXT SEARCH: * contains \'value\' or * matches \'regex\' in the initial filter (before the first |) searches ALL indexed fields — use when the user asks to find text anywhere in the event, e.g. dataSource.name=\'MySource\' * contains \'evil.com\'. Dramatically faster than message contains. (3) EMPTY FILTER (all events): start with | and no initial predicate, e.g. | group ct=count() by event.type. Do NOT use bare * alone as the initial filter — that causes HTTP 500 ("Don\'t understand [*]").',
+        },
+        startTime: {
+          type: 'string',
+          description: 'ISO-8601 UTC start time, e.g. "2026-04-20T00:00:00Z". If omitted, defaults to (now - hours) ago.',
+        },
+        endTime: {
+          type: 'string',
+          description: 'ISO-8601 UTC end time, e.g. "2026-04-21T00:00:00Z". If omitted, defaults to now.',
+        },
+        hours: {
+          type: 'number',
+          description: 'Lookback window in hours when startTime/endTime are not specified (default 24).',
+          default: 24,
+        },
+        maxRows: {
+          type: 'number',
+          description: 'Maximum rows to return (default 1000, max 5000).',
+          default: 1000,
+        },
+      },
+      required: ['query'],
+    },
+    async handler({ query, startTime, endTime, hours = 24, maxRows = 1000 }) {
+      const result = await lrqRun(query, { startTime, endTime, hours, maxRows });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── powerquery_schema_discover ────────────────────────────────────────────
+  {
+    name: 'powerquery_schema_discover',
+    description: `Discover the field schema for a specific SDL data source by fetching raw event JSON via the V1 query endpoint. PowerQuery's default projection only returns timestamp+message; V1 query returns full event attributes so you can see what field names are actually present. Use this before authoring any hunt query or dashboard panel against a non-OCSF source. The V1 endpoint is deprecated (sunset Feb 2027) but is still the only way to get full event JSON per-source. Auth falls through to console JWT automatically.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dataSourceName: {
+          type: 'string',
+          description: 'Exact dataSource.name value (case-sensitive, as returned by powerquery_enumerate_sources).',
+        },
+        maxEvents: {
+          type: 'number',
+          description: 'Number of sample events to retrieve (default 5, max 50).',
+          default: 5,
+        },
+        startTime: {
+          type: 'string',
+          description: 'Lookback string or ISO date, e.g. "24h", "7d", or "2026-04-20T00:00:00Z" (default "24h").',
+          default: '24h',
+        },
+      },
+      required: ['dataSourceName'],
+    },
+    async handler({ dataSourceName, maxEvents = 5, startTime = '24h' }) {
+      const filter = `dataSource.name=='${dataSourceName}'`;
+      const result = await v1Query(filter, { maxCount: Math.min(maxEvents, 50), startTime });
+
+      const matches = result.matches || [];
+      if (matches.length === 0) {
+        return JSON.stringify({ dataSourceName, message: 'No events found in the specified time range. Try a longer startTime like "7d".', result }, null, 2);
+      }
+
+      // Extract field names from first event
+      const firstAttrs = matches[0]?.attributes || {};
+      const allFields = new Set();
+      matches.forEach(m => Object.keys(m?.attributes || {}).forEach(k => allFields.add(k)));
+
+      return JSON.stringify({
+        dataSourceName,
+        sampleEventCount: matches.length,
+        confirmedFields: Array.from(allFields).sort(),
+        firstEventAttributes: firstAttrs,
+        allSampleAttributes: matches.map(m => m.attributes),
+      }, null, 2);
+    },
+  },
+];

package/tools/sdl-api.js

@@ -0,0 +1,133 @@
+/**
+ * SDL API tools — sentinelone-sdl-api, sentinelone-sdl-dashboard, sentinelone-sdl-log-parser skills
+ *
+ * Tools:
+ *   sdl_list_files     List all config files on the SDL tenant
+ *   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)
+ */
+
+import { listFiles, getFile, putFile, deleteFile, uploadLogs } from '../lib/sdl.js';
+
+export const tools = [
+  // ─── sdl_list_files ───────────────────────────────────────────────────────
+  {
+    name: 'sdl_list_files',
+    description: `List all configuration files stored in the SDL tenant. Returns all paths organized by type: /logParsers/, /dashboards/, /alerts/, /lookups/, /datatables/. Use this to discover what parsers and dashboards are already deployed, or to find a file path before calling sdl_get_file or sdl_put_file.`,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+    async handler() {
+      const result = await listFiles();
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_get_file ─────────────────────────────────────────────────────────
+  {
+    name: 'sdl_get_file',
+    description: `Get the content and current version number of a SDL configuration file. Use before sdl_put_file to read the current version for optimistic locking (pass the returned version as expectedVersion). Supports any file type: parsers (/logParsers/<name>), dashboards (/dashboards/<name>), alerts (/alerts/<name>), lookups (/lookups/<name>), datatables (/datatables/<name>). Always read before overwriting — this prevents concurrent-edit conflicts.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Full SDL config path, e.g. "/logParsers/FortiGate" or "/dashboards/SOC-Overview". Get the path from sdl_list_files.',
+        },
+      },
+      required: ['path'],
+    },
+    async handler({ path }) {
+      const result = await getFile(path);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_put_file ─────────────────────────────────────────────────────────
+  {
+    name: 'sdl_put_file',
+    description: `Deploy or update a SDL configuration file. Always call sdl_get_file first to obtain the current expectedVersion — this prevents overwriting concurrent edits. If creating a new file, omit expectedVersion. File type conventions: parsers go to /logParsers/<name>, dashboards to /dashboards/<name>, alerts to /alerts/<name>, lookups to /lookups/<name>. Requires Configuration Write key (SDL_CONFIG_WRITE_KEY) or a console JWT that has config write permissions.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Full SDL config path, e.g. "/logParsers/MyParser" or "/dashboards/SOC-Ops".',
+        },
+        content: {
+          type: 'string',
+          description: 'File content as a string. For dashboards: valid dashboard JSON. For parsers: augmented-JSON parser definition. For lookups: CSV or JSON.',
+        },
+        expectedVersion: {
+          type: 'number',
+          description: 'Current file version from sdl_get_file. Required for updates to enable optimistic locking. Omit only when creating a new file.',
+        },
+      },
+      required: ['path', 'content'],
+    },
+    async handler({ path, content, expectedVersion }) {
+      const result = await putFile(path, content, expectedVersion);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_delete_file ──────────────────────────────────────────────────────
+  {
+    name: 'sdl_delete_file',
+    description: `Delete a SDL configuration file (parser, dashboard, alert, lookup, datatable). Use with caution — deletion is permanent. Always read the file with sdl_get_file first to confirm you have the right path and version.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Full SDL config path to delete.',
+        },
+        expectedVersion: {
+          type: 'number',
+          description: 'Current file version for optimistic locking (from sdl_get_file). Strongly recommended.',
+        },
+      },
+      required: ['path'],
+    },
+    async handler({ path, expectedVersion }) {
+      const result = await deleteFile(path, expectedVersion);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── sdl_upload_logs ──────────────────────────────────────────────────────
+  {
+    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.`,
+    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.',
+        },
+      },
+      required: ['logContent'],
+    },
+    async handler({ logContent, parser, logfile, serverHost }) {
+      const result = await uploadLogs(logContent, { parser, logfile, serverHost });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+];

package/tools/uam-ingest.js

@@ -0,0 +1,128 @@
+/**
+ * UAM Alert Interface tools — push OCSF indicators + alerts INTO UAM
+ * via the SentinelOne HEC ingest host (ingest.us1.sentinelone.net).
+ *
+ * Tools:
+ *   uam_ingest_alert      End-to-end: build + POST one FileSystem indicator + one SecurityAlert
+ *   uam_post_indicators   Low-level: POST raw OCSF indicators to /v1/indicators
+ *   uam_post_alert        Low-level: POST a single raw OCSF SecurityAlert to /v1/alerts
+ *
+ * These tools require S1_HEC_INGEST_URL in credentials.json in addition to
+ * S1_CONSOLE_API_TOKEN (same token, Bearer prefix instead of ApiToken).
+ */
+
+import { ingestAlert, ingestAlertInline, postIndicators, postAlert } from '../lib/uam-ingest.js';
+
+export const tools = [
+
+  // ─── uam_ingest_alert ─────────────────────────────────────────────────────
+  {
+    name: 'uam_ingest_alert',
+    description: `Create a synthetic test alert in Unified Alert Management (UAM) via the SentinelOne HEC ingest API. Supports two modes controlled by the "inline" parameter:
+
+Two-call mode (inline=false, default): POST indicator to /v1/indicators, sleep 3s, POST SecurityAlert to /v1/alerts referencing the indicator uid. The stitcher resolves the full indicator into alert.rawIndicators. Best for testing deep indicator stitching and the Indicators tab in UAM.
+
+Inline mode (inline=true): POST a single SecurityAlert to /v1/alerts with the indicator's file/device/actor fields embedded inside finding_info.related_events[]. No separate indicator POST, no sleep — one round-trip. Best for rapid alert creation or when a single call is preferred.
+
+Both modes return indicator_uid and alert_uid. The alert surfaces in UAM within 30-60s. Requires S1_HEC_INGEST_URL in credentials.json.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: {
+          type: 'string',
+          description: 'Mandatory. accountId or "accountId:siteId" (colon-separated). Find the accountId via s1_api_get /web/api/v2.1/accounts?limit=1.',
+        },
+        title: {
+          type: 'string',
+          description: 'Alert name shown in UAM. Default: "MCP Test Alert".',
+          default: 'MCP Test Alert',
+        },
+        description: {
+          type: 'string',
+          description: 'Alert description body. Default: generic synthetic alert text.',
+        },
+        hostname: {
+          type: 'string',
+          description: 'Hostname to use for the synthetic indicator device. Default: "mcp-test-host".',
+          default: 'mcp-test-host',
+        },
+        filename: {
+          type: 'string',
+          description: 'Filename for the OCSF FileSystem Activity indicator. Default: "test-payload.exe".',
+          default: 'test-payload.exe',
+        },
+        sha256: {
+          type: 'string',
+          description: 'SHA-256 hash (64 lowercase hex chars). If omitted, a zeroed placeholder hash is used.',
+        },
+        sleep_ms: {
+          type: 'number',
+          description: 'Two-call mode only. Milliseconds to sleep between the indicator POST and the alert POST. Default 3000. Do not go below 2000 on loaded tenants.',
+          default: 3000,
+        },
+        inline: {
+          type: 'boolean',
+          description: 'When true, embed indicator data (file, device, actor, observables) directly inside the alert\'s finding_info.related_events[] and POST only to /v1/alerts — no separate /v1/indicators call, no sleep. When false (default), use the two-call flow: POST indicator first, sleep, then POST alert.',
+          default: false,
+        },
+      },
+      required: ['scope'],
+    },
+    async handler({ scope, title, description, hostname, filename, sha256, sleep_ms = 3000, inline = false }) {
+      const result = inline
+        ? await ingestAlertInline({ scope, title, description, hostname, filename, sha256 })
+        : await ingestAlert({ scope, title, description, hostname, filename, sha256, sleepMs: sleep_ms });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_post_indicators ──────────────────────────────────────────────────
+  {
+    name: 'uam_post_indicators',
+    description: `POST one or more raw OCSF behavioral indicators to /v1/indicators on the SentinelOne HEC ingest host. Batching is supported — pass multiple indicators in the array and they are sent in a single gzip-compressed request. Each indicator must carry metadata.profiles=["s1/security_indicator"] and a unique metadata.uid (used as the join key when an alert references it). After posting, wait at least 3s before posting a SecurityAlert that references these indicator uids (use uam_post_alert or uam_ingest_alert which enforce the sleep). Requires S1_HEC_INGEST_URL in credentials.json.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: {
+          type: 'string',
+          description: 'accountId or "accountId:siteId". Mandatory.',
+        },
+        indicators: {
+          type: 'array',
+          description: 'Array of OCSF indicator objects. Each must have metadata.uid, metadata.profiles=["s1/security_indicator"], class_uid, and observables[]. file.hashes must be a Fingerprint array [{algorithm_id, algorithm, value}], not a plain dict.',
+          items: { type: 'object', additionalProperties: true },
+        },
+      },
+      required: ['scope', 'indicators'],
+    },
+    async handler({ scope, indicators }) {
+      const result = await postIndicators({ scope, indicators });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_post_alert ───────────────────────────────────────────────────────
+  {
+    name: 'uam_post_alert',
+    description: `POST a single raw OCSF SecurityAlert to /v1/alerts on the SentinelOne HEC ingest host. IMPORTANT: one alert per call. The HEC stitcher silently drops all but one alert in a multi-alert POST body (HTTP 202 still returned), so this tool rejects arrays. To send multiple alerts, loop this call. Always post indicator(s) first via uam_post_indicators and sleep at least 3s before calling this — posting an alert before its indicator uids are registered causes a silent drop. Requires S1_HEC_INGEST_URL in credentials.json.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scope: {
+          type: 'string',
+          description: 'accountId or "accountId:siteId". Mandatory.',
+        },
+        alert: {
+          type: 'object',
+          description: 'Single OCSF SecurityAlert object (class_uid 2002). Must have metadata.uid, finding_info.related_events[] each referencing a previously-posted indicator via uid. Each related_events entry needs class_uid, type_uid, category_uid, activity_id, severity_id, time, message, and observables[] with type+typeName.',
+          additionalProperties: true,
+        },
+      },
+      required: ['scope', 'alert'],
+    },
+    async handler({ scope, alert }) {
+      const result = await postAlert({ scope, alert });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+];