feat(crowdstrike): add alerts, host response, IOC, Spotlight, RTR, and case tools (#6746)

* feat(crowdstrike): add alerts, host response, IOC, Spotlight, RTR, and case tools

CrowdStrike Falcon shipped only three read-only Identity Protection sensor
tools. This adds 20 tools across the response and investigation surface SecOps
teams actually automate against.

Alerts (current Alerts API): query, get details, update status/assignment/
tags/comment/visibility. Hosts: contain, lift containment, hide, unhide. Host
groups: query, get details, add/remove hosts. IOC Management: query, get, create,
update, delete. Spotlight: query vulnerabilities, get vulnerability details. Real
Time Response: init session, execute a read-only command, poll command status,
delete session. Case Management: query cases, get case details.

Every endpoint, request field, and response field is taken from CrowdStrike's
published surface (developer.crowdstrike.com API reference, FalconPy endpoint
definitions, and the swagger-generated gofalcon models). Required API scope is
documented in each tool description.

Deliberately not implemented:
- Detects API: decommissioned 2025-09-30, superseded by Alerts.
- CrowdScore Incidents API and behaviors: decommissioned 2026-03-09 and removed
  from the developer center entirely. Case Management is CrowdStrike's
  replacement, so its two documented read operations are implemented instead.
- Case create/update/merge: the swagger types case `status` and
  `severity_info.level` as bare strings with no enum, so a correct write cannot
  be built without guessing.

CrowdStrike answers 200 with a populated `errors` array for partial failures.
Responses now surface those per-item errors, and an empty result set carrying
errors is reported as a failure rather than silently succeeding.

The route's shared Falcon client, response normalizers, and operation dispatch
move into colocated modules so the handler stays readable at 23 operations.

* fix(crowdstrike): correct the RTR read-tier commands and stop dropping the IOC delete filter

Validation pass over all 23 tools against CrowdStrike's swagger-generated SDKs
(gofalcon falcon/models + falcon/client, FalconPy _endpoint/*.py) turned up four
real defects.

The Execute RTR Command dropdown offered `csrutil` and a bare `reg`. Neither is
a read-tier base command: CrowdStrike's own swagger description for
RTR_ExecuteCommand enumerates cat, cd, clear, env, eventlog, filehash, getsid,
help, history, ipconfig, ls, mount, netstat, ps, and "reg query". `csrutil`
appears nowhere in CrowdStrike's published surface, and `reg` alone is not a
base command — the registry variants are "reg query" (read) and "reg set"/"reg
delete" (Active Responder). Both entries are corrected everywhere they were
repeated: dropdown, tool description, and param description.

Delete Indicators showed a Filter input, declared the param, accepted it in the
contract, and implemented CrowdStrike's documented filter-takes-precedence rule
in the route — but the block never mapped the field into the tool call, so the
filter was silently discarded and a filter-only delete failed validation. The
`filter` case is now mapped alongside the ID list.

A 200 carrying only envelope errors was reported as HTTP 200 with success:false,
which reads as a success to anything inspecting status. Failures now adopt the
per-item error code the envelope supplies, falling back to 502.

Alert updates gain a first-class Remove Tags By Prefix field. The spelling was
previously unresolvable, so it was left to the raw action-parameter escape
hatch; CrowdStrike's swagger settles it as `remove_tags_by_prefix` in both the
PatchEntitiesAlertsV2 and PatchEntitiesAlertsV3 descriptions.

Case Management and Spotlight scopes now name the OAuth scope string
(case-templates:read, spotlight-vulnerabilities:read) alongside the label the
Falcon API client UI shows, so either rendering is findable.

* fix(crowdstrike): stop blank sensor filters reaching Falcon and expose the RTR outputs

The falcon.ts/normalize.ts/operations.ts split routed query_sensors through the
shared buildUrl helper, which skips only undefined. An empty filter or sort
string therefore emitted `?filter=` / `?sort=` where the pre-split route omitted
the param, sending Falcon an empty FQL expression. Reject blank values in the
contract instead, matching the newer operations.

Also surface the ten RTR fields the tools already return but the block never
declared, and broaden the block metadata past the original sensor-only surface.

* fix(crowdstrike): fail query operations on error-only envelopes and guard IOC pagination

Falcon can answer 200 with an errors array and no resources. The detail
operations already treated that as a failure, but the five query branches
returned an empty successful result, so a failed alert query read as a valid
no-match to the calling workflow.

Blank FQL rejection now covers the alert, host-group, indicator, vulnerability,
and case contracts too, not just sensors, and Query Indicators rejects offset
combined with after instead of forwarding a pagination pair CrowdStrike refuses.

* fix(crowdstrike): stop blank inputs reaching Falcon and restore the dropped output docs

The executor merges `tools.config.params` over the raw block inputs, so a key the
mapper omitted kept its raw subBlock value — and an untouched subBlock is stored
as `null`, which the route contract rejects. Query Alerts with an empty Filter,
Update Alerts without every optional field, and Delete Indicators without an
audit comment all 400'd before reaching CrowdStrike. Seed every optional key as
`undefined` so omission is authoritative, which also stops a value left over from
another operation riding along.

Shared output consts in `outputs.ts` were silently dropped from the generated
docs: the generator scans tool source and resolves consts only from `types.ts`,
so `errors`, `affected`, and `pagination` rows vanished from 17 tool pages and
every nested property row with them. Inline the literals.

Against CrowdStrike's own generated SDKs and developer portal:
- add csrutil, ifconfig, users, and the eventlog subcommand forms to the
  read-tier RTR base commands, matching PSFalcon's ValidateSet
- add detection_suppress/detection_unsuppress and cap host actions at the
  documented 100 ids
- cap the IOC search limit at the documented 500, not 2000
- correct the Cases scope to "Cases: Read"; case-templates guards a different
  collection
- type the IOC payload so a blank string cannot clear a stored field on PATCH
- send `MsaRangeSpec` bounds capitalized, as the spec serializes them
- fail the sensor and RTR-session-close paths on a 200 whose envelope carries
  only errors, and surface partial sensor errors
- give Delete Indicators its own filter so a stale alert query cannot widen it
- drop the pre-selected network-isolating host action

* fix(crowdstrike): correct the RTR command tier, IOC update contract, and US-3 region

Independent re-validation against gofalcon's swagger-generated models and
CrowdStrike's developer center turned up several wire-level errors.

- Real Time Response advertised "eventlog backup"/"export"/"list", "reg query",
  ifconfig, and users as base commands. base_command names a command family and
  subcommands belong in command_string; the eventlog write variants are Active
  Responder commands that would fail on scope under this Read-scoped tool, and
  ifconfig/users appear in neither authoritative list. The block now offers the
  16 documented read-tier families and the contract enforces them.
- Indicator updates accepted an entry with no id, which cannot name a record,
  and accepted type/value, which the update model does not expose. Creates
  accepted an entry with no type, value, or applied_globally -- the one property
  CrowdStrike marks required, and the one that decides fleet-wide scope.
- CrowdStrike documents that PATCH overwrites any omitted field with a blank
  value. The contract can only catch blanks, so the update tool now tells the
  caller to read the indicator first and resend its full field set.
- Added the US-3 commercial region, which was missing from every cloud list.
- Aggregate queries silently dropped percents and filters_spec.
- Deleted the response-envelope body unwrap: no endpoint this integration calls
  returns that shape, and getFalconErrorMessage never honored it anyway.
- Softened the Detects and Incidents claims to what the sources actually state.

A tool description longer than the docs generator's 600-character id-search
window silently publishes as an empty string; three descriptions had crossed it.
Shortened them and added a test that fails before the catalog goes blank.

* docs(crowdstrike): name the endpoint and Identity Protection scope on the sensor tools

The three sensor tools were the only ones in the family that named neither their
endpoint nor their OAuth2 scope, and none of them said these are the domain
controllers Falcon Identity Protection monitors rather than Falcon endpoint
sensors -- a distinction an agent choosing between them and the Hosts tools has
no other way to make. Identity Protection Entities: Read is also a separate
product entitlement from Hosts and Alerts.

* refactor(crowdstrike): say which ID caps are CrowdStrike's and which are Sim's

Every bulk-ID limit claimed CrowdStrike as its source, but only the sensor
(5000), host action (100), indicator batch (200), and Spotlight (400) caps are
published. The alert, host group, indicator, and case caps are Sim's own bound
on request size, and the validation message now says so instead of attributing
a limit CrowdStrike does not document.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/crowdstrike.mdx

@@ -0,0 +1,243 @@
+import { isRecordLike } from '@sim/utils/object'
+import type { CrowdStrikeBaseParams, CrowdStrikeCloud } from '@/tools/crowdstrike/types'
+
+export type JsonRecord = Record<string, unknown>
+
+const CLOUD_BASE_URLS: Record<CrowdStrikeCloud, string> = {
+  'eu-1': 'https://api.eu-1.crowdstrike.com',
+  'us-1': 'https://api.crowdstrike.com',
+  'us-2': 'https://api.us-2.crowdstrike.com',
+  'us-3': 'https://api.us-3.crowdstrike.com',
+  'us-gov-1': 'https://api.laggar.gcw.crowdstrike.com',
+  'us-gov-2': 'https://api.us-gov-2.crowdstrike.mil',
+}
+
+export function getCloudBaseUrl(cloud: CrowdStrikeCloud): string {
+  return CLOUD_BASE_URLS[cloud]
+}
+
+export function getString(value: unknown): string | null {
+  return typeof value === 'string' ? value : null
+}
+
+export function getNumber(value: unknown): number | null {
+  return typeof value === 'number' ? value : null
+}
+
+export function getBoolean(value: unknown): boolean | null {
+  return typeof value === 'boolean' ? value : null
+}
+
+export function getStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+export function getRecordArray(value: unknown): JsonRecord[] {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value.filter(isRecordLike)
+}
+
+export function getRecord(value: unknown): JsonRecord | null {
+  return isRecordLike(value) ? value : null
+}
+
+/**
+ * Every Falcon endpoint this integration calls answers with a flat
+ * `{ meta, resources, errors }` envelope, so the envelope readers below and
+ * `getFalconErrorMessage` both read the payload root directly.
+ */
+export function getResourcesArray(data: unknown): unknown[] {
+  if (!isRecordLike(data) || !Array.isArray(data.resources)) {
+    return []
+  }
+
+  return data.resources
+}
+
+export function getRecordResources(data: unknown): JsonRecord[] {
+  return getResourcesArray(data).filter(isRecordLike)
+}
+
+export function getStringResources(data: unknown): string[] {
+  return getStringArray(getResourcesArray(data))
+}
+
+export function getFirstRecordResource(data: unknown): JsonRecord | null {
+  return getRecordResources(data)[0] ?? null
+}
+
+export function getPagination(data: unknown) {
+  if (!isRecordLike(data) || !isRecordLike(data.meta) || !isRecordLike(data.meta.pagination)) {
+    return null
+  }
+
+  const { pagination } = data.meta
+
+  return {
+    limit: getNumber(pagination.limit),
+    offset: getNumber(pagination.offset),
+    total: getNumber(pagination.total),
+  }
+}
+
+/** Offset pagination plus the `after` cursor the IOC Management API returns. */
+export function getCursorPagination(data: unknown) {
+  if (!isRecordLike(data) || !isRecordLike(data.meta) || !isRecordLike(data.meta.pagination)) {
+    return null
+  }
+
+  const { pagination } = data.meta
+
+  return {
+    after: getString(pagination.after),
+    limit: getNumber(pagination.limit),
+    offset: getNumber(pagination.offset),
+    total: getNumber(pagination.total),
+  }
+}
+
+/** Spotlight paginates by cursor only — it returns no offset. */
+export function getSpotlightPagination(data: unknown) {
+  if (!isRecordLike(data) || !isRecordLike(data.meta) || !isRecordLike(data.meta.pagination)) {
+    return null
+  }
+
+  const { pagination } = data.meta
+
+  return {
+    after: getString(pagination.after),
+    limit: getNumber(pagination.limit),
+    total: getNumber(pagination.total),
+  }
+}
+
+/**
+ * CrowdStrike returns `{ meta, resources, errors }` on every endpoint, and a 200
+ * can still carry a populated `errors` array for the IDs that failed.
+ */
+export function getEnvelopeErrors(data: unknown) {
+  if (!isRecordLike(data)) {
+    return []
+  }
+
+  return getRecordArray(data.errors).map((entry) => ({
+    code: getNumber(entry.code),
+    id: getString(entry.id),
+    message: getString(entry.message),
+  }))
+}
+
+export function getFalconErrorMessage(data: unknown, fallback: string): string {
+  if (!isRecordLike(data)) {
+    return fallback
+  }
+
+  const errors = Array.isArray(data.errors) ? data.errors : []
+  const firstError = errors[0]
+  if (isRecordLike(firstError)) {
+    const firstMessage = getString(firstError.message) ?? getString(firstError.code)
+    if (firstMessage) {
+      return firstMessage
+    }
+  }
+
+  return (
+    getString(data.message) ??
+    getString(data.error_description) ??
+    getString(data.error) ??
+    fallback
+  )
+}
+
+export async function getAccessToken(params: CrowdStrikeBaseParams): Promise<string> {
+  const baseUrl = getCloudBaseUrl(params.cloud)
+  const response = await fetch(`${baseUrl}/oauth2/token`, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      grant_type: 'client_credentials',
+    }).toString(),
+    cache: 'no-store',
+  })
+
+  const data: unknown = await response.json().catch(() => null)
+  if (!response.ok) {
+    throw new Error(getFalconErrorMessage(data, 'Failed to authenticate with CrowdStrike'))
+  }
+
+  if (!isRecordLike(data) || typeof data.access_token !== 'string') {
+    throw new Error('CrowdStrike authentication did not return an access token')
+  }
+
+  return data.access_token
+}
+
+interface CrowdStrikeRequestOptions {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  query?: Record<string, string | number | boolean | undefined>
+  repeatedQuery?: Record<string, string[] | undefined>
+  body?: unknown
+}
+
+export interface CrowdStrikeCallResult {
+  ok: boolean
+  status: number
+  data: unknown
+}
+
+export function buildUrl(baseUrl: string, options: CrowdStrikeRequestOptions): string {
+  const url = new URL(options.path, baseUrl)
+
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== undefined) {
+      url.searchParams.set(key, String(value))
+    }
+  }
+
+  for (const [key, values] of Object.entries(options.repeatedQuery ?? {})) {
+    for (const value of values ?? []) {
+      url.searchParams.append(key, value)
+    }
+  }
+
+  return url.toString()
+}
+
+export async function callCrowdStrike(
+  baseUrl: string,
+  accessToken: string,
+  options: CrowdStrikeRequestOptions
+): Promise<CrowdStrikeCallResult> {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${accessToken}`,
+  }
+
+  if (options.body !== undefined) {
+    headers['Content-Type'] = 'application/json'
+  }
+
+  const response = await fetch(buildUrl(baseUrl, options), {
+    method: options.method,
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    cache: 'no-store',
+  })
+
+  const data: unknown = await response.json().catch(() => null)
+
+  return { ok: response.ok, status: response.status, data }
+}