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#6746waleedlatif1 wants to merge 6 commits into
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 refactored into shared Falcon HTTP/auth helpers ( The block and docs add operation-specific subBlocks (FQL, pagination cursors vs offset, alert updates, host actions including containment, IOC lifecycle, RTR session flow), stricter param mapping (optional keys cleared so stale fields don’t leak across operations, dedicated delete filter, per-endpoint limit caps), new block outputs for RTR fields, templates/skills, and full action reference in Reviewed by Cursor Bugbot for commit badcb40. Configure here. |
Greptile SummaryThe PR expands the CrowdStrike integration from Identity Protection sensor queries to a 23-tool Falcon suite.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| apps/sim/app/api/tools/crowdstrike/query/operations.ts | Implements the expanded Falcon operations and correctly distinguishes error-only query envelopes from successful empty results. |
| apps/sim/lib/api/contracts/tools/crowdstrike.ts | Defines operation-specific request and response schemas, including enforced mutual exclusion for IOC pagination modes. |
| apps/sim/app/api/tools/crowdstrike/query/falcon.ts | Centralizes authentication, Falcon requests, URL construction, pagination extraction, and envelope-error parsing. |
| apps/sim/app/api/tools/crowdstrike/query/normalize.ts | Normalizes Falcon alert, IOC, vulnerability, host-group, and case records into stable tool outputs. |
| apps/sim/blocks/blocks/crowdstrike.ts | Expands the CrowdStrike workflow block with operation-specific inputs, tool dispatch, and outputs. |
| apps/sim/app/api/tools/crowdstrike/query/operations.test.ts | Covers the new operation flows and the fixes for both previously reported defects. |
Sequence Diagram
sequenceDiagram
participant W as Workflow Block
participant T as CrowdStrike Tool
participant R as CrowdStrike API Route
participant F as Falcon API
W->>T: Invoke selected operation
T->>R: POST validated tool parameters
R->>R: Validate operation contract
R->>F: Authenticate and call Falcon endpoint
F-->>R: Resource/error envelope
R->>R: Normalize resources and envelope errors
R-->>T: Typed operation output
T-->>W: Workflow-visible result
Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/sta..." | 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 |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit badcb40. Configure here.
| localIp: getString(hostInfo.local_ip), | ||
| machineDomain: getString(hostInfo.machine_domain), | ||
| osVersion: getString(hostInfo.os_version), | ||
| platform: getString(hostInfo.platform), |
There was a problem hiding this comment.
Wrong vulnerability platform field
Medium Severity
normalizeVulnerability reads host_info.platform, but Spotlight exposes the host platform as platform_name (matching the FQL field host_info.platform_name documented elsewhere in this change). Vulnerability details therefore return hostInfo.platform as null even when Falcon includes platform data.
Reviewed by Cursor Bugbot for commit badcb40. Configure here.
| comment: nonBlankQuerySchema('Comment'), | ||
| retrodetects: z.boolean().optional(), | ||
| ignoreWarnings: z.boolean().optional(), | ||
| }) |
There was a problem hiding this comment.
Indicator updates skip required id
High Severity
updateIndicatorsSchema reuses indicatorPayloadSchema, where id is optional. The update tool docs require each entry to include id, but the contract accepts id-less PATCH payloads. Those requests can fail late at Falcon or apply unclear updates to fleet prevention indicators.
Reviewed by Cursor Bugbot for commit badcb40. 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