@pmoses-s1/s1-secops-mcp 1.3.0

package/tools/mgmt-console.js

@@ -0,0 +1,344 @@
+/**
+ * Management Console API tools: mgmt-console-api skill
+ *
+ * Tools:
+ *   s1_api_get              Generic GET against S1 Mgmt Console REST API
+ *   s1_api_post             Generic POST against S1 Mgmt Console REST API
+ *   s1_api_put              Generic PUT against S1 Mgmt Console REST API
+ *   s1_api_delete           Generic DELETE against S1 Mgmt Console REST API
+ *   s1_api_patch            Generic PATCH against S1 Mgmt Console REST API
+ *   purple_ai_alert_summary Get a Purple AI natural-language summary for a specific UAM alert
+ *   uam_list_alerts         List/search UAM alerts via GraphQL
+ *   uam_get_alert           Get full alert details (notes, history)
+ *   uam_add_note            Add analyst note to an alert
+ *   uam_set_status          Update alert status (NEW, IN_PROGRESS, RESOLVED)
+ *
+ * REMOVED (2026-05-03: confirmed non-functional for API tokens):
+ *   purple_ai_query        : requires browser-session teamToken from /sdl/v2/graphql that
+ *                             API-token service accounts never obtain. Use Purple MCP instead.
+ *   purple_ai_investigate  : same root cause (SERVICE_ERROR). Use Purple MCP instead.
+ */
+
+import { apiGet, apiPost, apiPut, apiDelete, apiPatch, purpleAlertSummary, uamListAlerts, uamGetAlert, uamAddNote, uamSetStatus } from '../lib/s1.js';
+
+/**
+ * Defensive normalization for GET /cloud-detection/rules calls.
+ *
+ * Without `isLegacy=false`, the S1 API silently omits queryType="scheduled"
+ * PowerQuery rules from the response: no error, no warning, the response
+ * just lies by omission. Promoting "empty response" to "tenant has zero
+ * scheduled detections" without isLegacy=false is the failure mode this
+ * guard exists to prevent. Exported for unit testing.
+ */
+export function normalizeS1ApiGetParams(path, params) {
+  const p = { ...(params || {}) };
+  if (
+    typeof path === 'string' &&
+    /\/cloud-detection\/rules(\/|\?|$)/.test(path) &&
+    // Respect an explicit inline override in the path query string, e.g.
+    // /cloud-detection/rules?isLegacy=true; do not append a conflicting
+    // isLegacy=false. Mirrors _maybe_inject_islegacy in
+    // mgmt-console-api/scripts/s1_client.py.
+    !/[?&]is_?legacy=/i.test(path) &&
+    p.isLegacy === undefined &&
+    p.is_legacy === undefined
+  ) {
+    p.isLegacy = false;
+  }
+  return p;
+}
+
+export const tools = [
+  // ─── s1_api_get ───────────────────────────────────────────────────────────
+  {
+    name: 's1_api_get',
+    description: `Generic GET request to the SentinelOne Management Console REST API (v2.1). Use for ALL read operations: listing, counting, and exporting. The S1 API uses GET for every read: listing, counting, and exporting are always GET, never POST. The path should start with /web/api/v2.1/. Returns raw JSON response. For paginated endpoints, use the cursor or skip/limit params. Count examples: path="/web/api/v2.1/agents/count" returns {"data":{"total":N}}; path="/web/api/v2.1/threats" params={"countOnly":true} returns pagination.totalItems. Export example: path="/web/api/v2.1/threats/export" (no extra params). Get agents by IDs: path="/web/api/v2.1/agents" params={"ids":"<id1>,<id2>"} (comma-separated query param).
+
+⚠️ CLOUD-DETECTION RULES, MANDATORY isLegacy=false: For ANY GET on /cloud-detection/rules (listing, name search, queryType filter, scope filter) you MUST pass params.isLegacy=false. Without it the API silently omits queryType="scheduled" PowerQuery rules and returns only events-type rules; there is no error, no warning, the response just lies by omission. This handler auto-injects isLegacy=false when it sees a /cloud-detection/rules path and the caller forgot it, but always pass it explicitly so it shows up in audit logs. Promoting "empty response" to "tenant has zero scheduled detections" without isLegacy=false is the failure mode this guard exists to prevent.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          pattern: '^/web/api/v2\\.1/',
+          description: 'API path starting with /web/api/v2.1/, e.g. "/web/api/v2.1/agents".',
+        },
+        params: {
+          type: 'object',
+          description: 'Query string parameters as key-value pairs, e.g. {"limit": 20, "sortBy": "createdAt"}. For /cloud-detection/rules listings ALWAYS include {"isLegacy": false}; the handler auto-injects it as a safety net but explicit is better.',
+          additionalProperties: true,
+        },
+      },
+      required: ['path'],
+    },
+    async handler({ path, params = {} }) {
+      // Safety net: /cloud-detection/rules silently hides scheduled
+      // PowerQuery rules unless isLegacy=false is passed.
+      const normalized = normalizeS1ApiGetParams(path, params);
+      const result = await apiGet(path, normalized);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── s1_api_post ──────────────────────────────────────────────────────────
+  {
+    name: 's1_api_post',
+    description: `Generic POST request to the SentinelOne Management Console REST API (v2.1). Use ONLY for write and action operations: create IOC, isolate agent, add exclusion, create custom detection rule, trigger RemoteOps, etc. The path should start with /web/api/v2.1/. NEVER use POST for listing, counting, or exporting; all reads are GET. POST to a read path returns HTTP 404 because the path does not exist in the API (e.g. POST /agents/ids, POST /threats/summary, POST /export/threats are all wrong). Before calling, verify the path exists with: python3 scripts/search_endpoints.py "<keyword>". The body is NOT auto-wrapped; pass the complete envelope, e.g. {"data": {...}, "filter": {...}}.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          pattern: '^/web/api/v2\\.1/',
+          description: 'API path starting with /web/api/v2.1/, e.g. "/web/api/v2.1/threats/mark-as-threats".',
+        },
+        body: {
+          type: 'object',
+          description: 'Request body as JSON. For most S1 endpoints use the {"data": {...}, "filter": {...}} envelope. Pass the complete body.',
+          additionalProperties: true,
+        },
+      },
+      required: ['path', 'body'],
+    },
+    async handler({ path, body }) {
+      const result = await apiPost(path, body);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── s1_api_put ───────────────────────────────────────────────────────────
+  {
+    name: 's1_api_put',
+    description: `Generic PUT request to the SentinelOne Management Console REST API (v2.1). Use for full-replacement updates: update agent policies, replace exclusion rules, set system configuration, update firewall/device control rules, update group settings, etc. The path should start with /web/api/v2.1/. The body replaces the resource in full; include all required fields, not just the changed ones. Consult the swagger reference at references/tags/ in the mgmt-console-api skill before calling. Examples: path="/web/api/v2.1/accounts/{id}/policy" body={"data":{...policy fields...}}, path="/web/api/v2.1/system/configuration" body={"data":{...}}.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          pattern: '^/web/api/v2\\.1/',
+          description: 'API path starting with /web/api/v2.1/, e.g. "/web/api/v2.1/accounts/123/policy".',
+        },
+        body: {
+          type: 'object',
+          description: 'Full replacement body as JSON. Most S1 PUT endpoints use {"data": {...}} envelope. Include all required fields for the resource.',
+          additionalProperties: true,
+        },
+      },
+      required: ['path', 'body'],
+    },
+    async handler({ path, body }) {
+      const result = await apiPut(path, body);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── s1_api_delete ────────────────────────────────────────────────────────
+  {
+    name: 's1_api_delete',
+    description: `Generic DELETE request to the SentinelOne Management Console REST API (v2.1). Use for delete operations: delete IOCs (DELETE /web/api/v2.1/threat-intelligence/iocs), delete unified exclusions, delete custom detection rules, delete remote scripts, delete firewall/device control rules, delete tags, etc. The path should start with /web/api/v2.1/. Many S1 DELETE endpoints accept a filter body (e.g. IOCDeleteSchema uses accountId + one other field); pass it as the body param. Some accept query params only (body can be omitted). Consult the swagger reference at references/tags/ in the mgmt-console-api skill for the exact filter schema before calling. WARNING: deletions are irreversible. Confirm the target ID/filter before executing.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          pattern: '^/web/api/v2\\.1/',
+          description: 'API path starting with /web/api/v2.1/, e.g. "/web/api/v2.1/threat-intelligence/iocs".',
+        },
+        body: {
+          type: 'object',
+          description: 'Optional request body as JSON. Required for filter-based deletes (e.g. IOC delete requires {"filter": {"accountId": "...", "uuids": [...]}}). Omit for ID-in-path deletes.',
+          additionalProperties: true,
+        },
+      },
+      required: ['path'],
+    },
+    async handler({ path, body = {} }) {
+      const result = await apiDelete(path, body);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── s1_api_patch ─────────────────────────────────────────────────────────
+  {
+    name: 's1_api_patch',
+    description: `Generic PATCH request to the SentinelOne Management Console REST API (v2.1). Use for partial updates where only specific fields need to change without replacing the full resource. Less common in the S1 API than PUT, but used by some endpoints for partial config updates and field-level changes. The path should start with /web/api/v2.1/. Pass only the fields to change in the body. Consult the swagger reference at references/tags/ in the mgmt-console-api skill to confirm whether a given endpoint expects PUT (full replace) or PATCH (partial update).`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          pattern: '^/web/api/v2\\.1/',
+          description: 'API path starting with /web/api/v2.1/.',
+        },
+        body: {
+          type: 'object',
+          description: 'Partial update body as JSON. Include only the fields to change.',
+          additionalProperties: true,
+        },
+      },
+      required: ['path', 'body'],
+    },
+    async handler({ path, body }) {
+      const result = await apiPatch(path, body);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── purple_ai_alert_summary ──────────────────────────────────────────────
+  {
+    name: 'purple_ai_alert_summary',
+    description: `Get a Purple AI natural-language summary for a specific UAM alert. Calls purpleAlertSummary (operation AlertSummary) at /web/api/v2.1/graphql with the full OCSF alert JSON. This is what populates the "Purple AI" card in the alert detail panel. Synchronous (no polling required). Returns { token, summary }. Use uam_get_alert first to retrieve the raw alert data, then pass its OCSF JSON here.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        alertJson: {
+          type: 'string',
+          description: 'The full alert as a JSON string (OCSF format, as returned by uam_get_alert or the GetAlert GraphQL query). Pass the entire alert object serialised to a string.',
+        },
+      },
+      required: ['alertJson'],
+    },
+    async handler({ alertJson }) {
+      const result = await purpleAlertSummary(alertJson);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_list_alerts ──────────────────────────────────────────────────────
+  {
+    name: 'uam_list_alerts',
+    description: `List UAM (Unified Alert Management) alerts via GraphQL. The PRIMARY alert API in S1, covers all alert types (EDR, STAR, cloud, identity, third-party). Uses the correct FilterInput schema: dateTimeRange { start, end } for time windows (epoch ms). USE THIS instead of Purple MCP search_alerts for time-scoped searches; the Purple MCP sends date_range (snake_case) which UAM rejects; this tool uses dateTimeRange (the actual schema field). Convenience params (status, severity, startTime, endTime) build FilterInputs automatically. For deeper analysis, follow up with uam_get_alert.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        first: {
+          type: 'number',
+          description: 'Number of alerts to fetch per page (default 20). Not enforced client-side; the UAM GraphQL backend accepts larger pages (live-verified 2026-07-29: first=500 returned 500 with hasNextPage=true). Use the returned pageInfo.endCursor with `after` to paginate rather than requesting an unbounded page.',
+          default: 20,
+        },
+        after: {
+          type: 'string',
+          description: 'Pagination cursor from a prior call\'s pageInfo.endCursor. Omit for first page.',
+        },
+        viewType: {
+          type: 'string',
+          description: 'Alert view scope.',
+          enum: ['ALL', 'ENDPOINT', 'IDENTITY', 'STAR', 'CUSTOM_ALERTS', 'CLOUD', 'THIRD_PARTY'],
+          default: 'ALL',
+        },
+        status: {
+          type: 'string',
+          description: 'Filter by status. Uses stringEqual FilterInput. Valid values (confirmed against live tenant): "NEW", "IN_PROGRESS", "RESOLVED". "OPEN" is NOT a valid value and silently returns 0 results. "FALSE_POSITIVE" is an analystVerdict field, not a status; uam_set_status cannot set it. To set the analyst verdict, POST the raw alertTriggerActions mutation with the S1/alert/analystVerdictUpdate action via s1_api_post to /web/api/v2.1/unifiedalerts/graphql.',
+        },
+        severity: {
+          type: 'string',
+          description: 'Filter by severity. Uses stringEqual FilterInput. e.g. "CRITICAL", "HIGH", "MEDIUM", "LOW".',
+        },
+        detectionProduct: {
+          type: 'string',
+          description: 'Filter by detection product. e.g. "EDR", "STAR", "CLOUD".',
+        },
+        searchText: {
+          type: 'string',
+          description: 'Full-text search across alert fields.',
+        },
+        startTime: {
+          type: 'string',
+          description: 'Start of time window. ISO-8601 string ("2026-05-03T07:32:00Z") or epoch milliseconds as string. Builds a dateTimeRange FilterInput on detectedAt using { start, end }, the actual UAM schema fields confirmed by introspection.',
+        },
+        endTime: {
+          type: 'string',
+          description: 'End of time window. ISO-8601 string or epoch ms. Defaults to now when startTime is provided.',
+        },
+      },
+      required: [],
+    },
+    async handler({ first = 20, after, viewType = 'ALL', status, severity, detectionProduct, searchText, startTime, endTime } = {}) {
+      // Convert string epoch ms to numbers if needed
+      const parseTime = (v) => {
+        if (!v) return null;
+        const n = Number(v);
+        return isNaN(n) ? v : n; // if numeric string, use as epoch ms; otherwise pass as ISO
+      };
+      const result = await uamListAlerts({
+        first, after, viewType,
+        status: status || null,
+        severity: severity || null,
+        detectionProduct: detectionProduct || null,
+        searchText: searchText || null,
+        startTime: parseTime(startTime),
+        endTime: parseTime(endTime),
+      });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_get_alert ────────────────────────────────────────────────────────
+  {
+    name: 'uam_get_alert',
+    description: `Get full details for a specific UAM alert including analyst notes. ALWAYS call this before making a verdict; notes may contain MDR verdicts (False Positive / Benign / Resolved) that take precedence over detection engine severity. Returns alert fields plus a notes array from alertNotes query.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        alertId: {
+          type: 'string',
+          description: 'The UAM alert ID (string UUID, from uam_list_alerts results).',
+        },
+      },
+      required: ['alertId'],
+    },
+    async handler({ alertId }) {
+      const result = await uamGetAlert(alertId);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_add_note ─────────────────────────────────────────────────────────
+  {
+    name: 'uam_add_note',
+    description: `Add an analyst note to a UAM alert. Use to document investigation findings, intermediate verdicts, IOC enrichment results, or escalation decisions. Notes are visible to all analysts and MDR. Best practice: include a timestamp-like prefix and cite the evidence inline (e.g. "VT: 12/72 malicious on hash abc123; cross-correlated with FortiGate BLOCK events on same dst IP").`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        alertId: {
+          type: 'string',
+          description: 'The UAM alert ID.',
+        },
+        note: {
+          type: 'string',
+          description: 'Note text. Cite evidence inline. Avoid vague statements, be specific about what queries were run, what IOCs were checked, and what the results were.',
+        },
+      },
+      required: ['alertId', 'note'],
+    },
+    async handler({ alertId, note }) {
+      const result = await uamAddNote(alertId, note);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+
+  // ─── uam_set_status ───────────────────────────────────────────────────────
+  {
+    name: 'uam_set_status',
+    description: `Update the status of a UAM alert. Valid values: NEW (reopen), IN_PROGRESS (actively investigating), RESOLVED (threat contained and remediated). Note: FALSE_POSITIVE is NOT a status value on this API; it is an analystVerdict. To mark an alert as a false positive, add a note explaining why and set status to RESOLVED. Always add a note via uam_add_note before closing an alert.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        alertId: {
+          type: 'string',
+          description: 'The UAM alert ID.',
+        },
+        status: {
+          type: 'string',
+          description: 'New status. Must be one of the confirmed enum values.',
+          enum: ['NEW', 'IN_PROGRESS', 'RESOLVED'],
+        },
+      },
+      required: ['alertId', 'status'],
+    },
+    async handler({ alertId, status }) {
+      const result = await uamSetStatus(alertId, status);
+      return JSON.stringify(result, null, 2);
+    },
+  },
+];

package/tools/powerquery.js

@@ -0,0 +1,129 @@
+/**
+ * PowerQuery tools: 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 [*]"). Beyond filtering, | datasource <name> [from <dataset>] reads SentinelOne-managed inventory (assets, alerts, vulnerabilities, misconfigurations, metering; e.g. | datasource assets from \'surface/identity\') and | savelookup \'<name>\' persists the result as a reusable lookup table (see references/datasource-command.md in powerquery).',
+        },
+        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: 'Client-side cap on rows returned (default 1000). Not a hard backend limit: the LRQ engine returns as many rows as the query\'s own `| limit N` asks for (live-verified 2026-07-29: a `| limit 20000` query returned 20,000 rows in one response). Raise this to match a large `| limit`; the real ceiling is LRQ response size, not a fixed 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 tries each configured SDL key in scope order and falls through to the console JWT on 401/403.`,
+    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' }) {
+      // Escape backslashes first, then single quotes, to keep tenant-defined
+      // source names from breaking (or altering) the V1 filter expression.
+      // Quote-only escaping let a trailing backslash neutralise the added
+      // escape (e.g. name\' -> \\' which re-opens the string).
+      const safeName = String(dataSourceName).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+      const filter = `dataSource.name=='${safeName}'`;
+      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,125 @@
+/**
+ * SDL API tools: sdl-api, sdl-dashboard, 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
+ *   hec_ingest         Ingest raw logs/events into SDL via the HEC endpoint (replaces uploadLogs)
+ */
+
+import { listFiles, getFile, putFile, deleteFile } from '../lib/sdl.js';
+import { hecIngest } from '../lib/hec.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>. Authorised by S1_CONSOLE_API_TOKEN.`,
+    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);
+    },
+  },
+
+  // ─── hec_ingest ─────────────────────────────────────────────────────────────
+  {
+    name: 'hec_ingest',
+    description: `Ingest raw logs/events into the SentinelOne AI SIEM Singularity Data Lake via the HEC (HTTP Event Collector) endpoint. Applies a named parser via ?sourcetype and lands the data in the Data Lake for Event Search, PowerQuery, and detection rules. Replaces the removed sdl_upload_logs. NOT UAM ingest (the uam_* tools post OCSF indicators/alerts to /v1/* on the same host but a separate API). Per S-26.1 HEC docs: POST {S1_HEC_INGEST_URL}/services/collector/raw, Authorization: Bearer <S1_CONSOLE_API_TOKEN>, query params become fields, gzip recommended, 10 MB uncompressed per request.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        logContent: { type: 'string', description: 'Raw log text. For the /raw endpoint, newline-separated lines become separate events.' },
+        parser: { type: 'string', description: 'Parser name, sent as the ?sourcetype= query param. Omit to skip parsing (structured JSON on /event auto-parses).' },
+        fields: { type: 'object', description: 'Extra key-value pairs sent as query params; each key becomes a field in the UI, e.g. {"server":"dev","region":"ap1"}. Avoid HEC-reserved names (event, time, host, source, sourcetype, index, fields) as keys; use the parser arg to set sourcetype.' },
+        scope: { type: 'string', description: 'REQUIRED. accountId or "accountId:siteId" sent as the S1-Scope header; HEC rejects requests without it (400 "Missing S1-Scope header").' },
+        endpoint: { type: 'string', enum: ['raw','event'], description: "HEC endpoint: 'raw' (default, raw text) or 'event' (structured JSON)." },
+        compress: { type: 'boolean', description: 'gzip the body (Content-Encoding: gzip). Default true.' },
+        isParsed: { type: 'boolean', description: 'For /event with structured JSON: set ?isParsed=true so SDL indexes the JSON fields directly, with no SDL parser. Confirmed working.' },
+      },
+      required: ['logContent', 'scope'],
+    },
+    async handler({ logContent, parser, fields, scope, endpoint, compress, isParsed }) {
+      const result = await hecIngest(logContent, { parser, fields, scope, endpoint, compress, isParsed });
+      return JSON.stringify(result, null, 2);
+    },
+  },
+];