feat(crowdstrike): add alerts, host response, IOC, Spotlight, RTR, and case tools - #6746
Conversation
…d 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.
…g 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.
…e 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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR SummaryHigh Risk Overview The query route is split into The workflow block gains matching operations, US-3 cloud, default Query Alerts, stricter param mapping (clears stale fields, dedicated
Reviewed by Cursor Bugbot for commit 3666071. Configure here. |
Greptile SummaryThe PR expands the CrowdStrike integration from Identity Protection sensor queries to alerts, host response, host groups, custom IOCs, Spotlight, Real Time Response, and Case Management.
Confidence Score: 5/5The PR appears safe to merge because no blocking failure remains from the previously reported issues. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| apps/sim/app/api/tools/crowdstrike/query/operations.ts | Implements the expanded Falcon operations and now correctly distinguishes error-only query envelopes from empty and partial-success responses. |
| apps/sim/lib/api/contracts/tools/crowdstrike.ts | Defines operation-specific validation, including mutually exclusive IOC pagination modes and strict host-agent ID validation. |
| apps/sim/app/api/tools/crowdstrike/query/falcon.ts | Centralizes Falcon authentication, URL construction, request handling, and envelope helpers. |
| apps/sim/app/api/tools/crowdstrike/query/normalize.ts | Normalizes Falcon resource records into stable tool output shapes. |
| apps/sim/app/api/tools/crowdstrike/query/operations.test.ts | Covers the expanded operations and verifies both previous review fixes through the full route boundary. |
| apps/sim/blocks/blocks/crowdstrike.ts | Exposes the expanded CrowdStrike tool set and output fields to workflow blocks. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
W[Workflow CrowdStrike tool] --> V[Request contract validation]
V --> R[CrowdStrike API route]
R --> O[Operation dispatcher]
O --> F[Falcon API]
F --> N[Envelope and resource normalization]
N --> W
Reviews (5): Last reviewed commit: "refactor(crowdstrike): say which ID caps..." | Re-trigger Greptile
…uard 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.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit dd25265. Configure here.
…ropped 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
…epth # Conflicts: # apps/sim/tools/generated/tool-ids.ts # apps/sim/tools/generated/tool-metadata.ts # apps/sim/tools/generated/tool-outputs.ts
|
@cursor review |
…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.
|
@cursor review |
… 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.
…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.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 3666071. Configure here.
Summary
CrowdStrike Falcon shipped with three Identity Protection sensor tools. This adds 20 more across alerts, host response, host groups, custom IOCs, Spotlight, Real Time Response, and Case Management — 23 tools total.
Why the branch is shaped around Alerts and Cases rather than Detects and Incidents: the two APIs a Falcon integration would normally build on are gone.
/detects/queries/detects/v1,/detects/entities/detects/v2, and friends were superseded by the Alerts API.falcon/client/incidents/entirely, includingquery_behaviors/get_behaviors. Case Management is the replacement.So this builds on
/alerts/*(v2 queries, v2/v3 entities) and/cases/*, not on the dead surfaces. No specific March day is asserted — neither SDK attests one, only "March 2026".Tools added
Fixes found while building
csrutilRTR base command was removed — it appears nowhere in FalconPy.regcorrected toreg query.filterparam, so a filter-scoped delete fell back to the ID list.query_sensorsregression from the route split: the sharedbuildUrlhelper skips onlyundefined, so an emptyfilter/sortstring emitted?filter=/?sort=where the pre-split route omitted the param — sending Falcon an empty FQL expression. The contract now rejects blank values, matching the newer operations.deviceId,platform,pwd,offlineQueued,existingAidSessions,createdAt,queuedCommandOffline,baseCommand,taskId,sequenceId) were unreachable as block outputs.Deliberately not implemented
Structure
app/api/tools/crowdstrike/query/route.tswas split intofalcon.ts(auth, URL building, envelope helpers),normalize.ts(per-resource normalizers), andoperations.ts(the 20 new operations). The three original sensor operations stay inline in the route and are excluded fromExtendedOperationby type, so none of the new envelope-error semantics apply to them — verified field-by-field as behavior-preserving.Type of Change
Testing
24 tests in
operations.test.tscovering alert query/details/update, host and host-group actions, envelope-error handling, IOC filter precedence, Spotlight cursor pagination, RTR session lifecycle, case normalization, and the blank-filter rejection. Each new test verified to fail without its fix.bun run lint,bun run type-check,bun run check:api-validation,bun run tool-metadata:check, andbun run integration-catalog:checkall pass.Checklist