ContraForce integrates with CrowdStrike Falcon to bring every Falcon detection into the unified Command Dashboard as a ContraForce incident, and to power Gamebook response actions on Falcon-managed devices. The integration is split across two CrowdStrike API clients — one for ingestion, one for response — so each client carries only the scopes it needs.Documentation Index
Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt
Use this file to discover all available pages before exploring further.
Detection-first ingestion. Each Falcon detection becomes its own ContraForce incident across every tier (EDR, XDR, NG-SIEM). Cases and automated leads are not surfaced as incidents — they are CrowdStrike’s analyst- and AI-curated groupings over the underlying detections, and ingesting them too would either double-count the signal or leave detections that never roll into a case or lead as silent blind spots. A first-class ContraForce Cases primitive that sits above incidents (cross-source) is on the roadmap as separate work.
This page describes what the integration does and what the tier you pick on the configuration page unlocks. For the step-by-step setup, see CrowdStrike Falcon Detection and Response Modules.
What the Integration Does
Ingestion
Polls CrowdStrike’s unified Alerts API on a continuous loop and surfaces every new Falcon detection in the Command Dashboard as a ContraForce incident.
Investigation
Hydrates the detection with process tree, events timeline, device, and identity context drawn from CrowdStrike NG-SIEM and the alert payload itself.
Status round-trip
Status changes you make in ContraForce (New → In Progress → Closed) PATCH back to CrowdStrike via the Alerts API.
Owner assignment (with optional writeback)
Assigning a CrowdStrike incident in ContraForce always records the owner in the ContraForce audit log. If the workspace has a CrowdStrike service account bound on the Assignment Writeback card, the assignment is also PATCHed onto the underlying Falcon alert as that service account. See the callout below.
Response actions
Powers the Contain, Lift Containment, and On-Demand Scan Gamebooks on Falcon-managed devices via the Response API client.
Agents on queue
Triggers Security Delivery Agents on every CrowdStrike incident that lands in the unified pipeline.
Why owner assignment defaults to audit-only. In MSSP topologies the ContraForce user (Entra UPN) frequently has no matching principal in the customer’s CrowdStrike tenant, so pushing the assignment directly to Falcon either fails or lands on the wrong account. Recording the assignment locally lets every ContraForce user who can see the incident see the assigned owner without requiring a vendor-side identity match. The list view and the incident detail both hydrate the owner from the audit log on read.The optional service-account writeback lets you opt back into vendor-side visibility without giving up the MSSP-friendly default. You bind one Falcon user (typically a named service account in the customer’s tenant) on the workspace’s Assignment Writeback card; from then on every analyst assignment in ContraForce is mirrored onto the underlying alert as that bound user, and unassigning in ContraForce clears the Falcon-side assignee. The CF audit log is still the source of truth for which analyst actually picked up the incident; the writeback only controls what the customer sees on the Falcon side. Writeback failures (Falcon outage, deleted user, missing scope) are logged but do not fail the CF-side assignment, so the analyst queue stays responsive even when the vendor is degraded.
Tier Selection — What You Pick on the Configuration Page
When you configure the Detection module in ContraForce, you pick which Falcon tier the customer is licensed for. The tier you declare drives which scopes the API client needs and which advanced investigation surfaces (Process Tree ancestor walk, Events Timeline) unlock. It does not change the ingestion shape — every Falcon detection becomes its own ContraForce incident on every tier. There are three options:- Falcon Insight (EDR)
- Falcon Insight XDR
- Falcon NG-SIEM
For tenants on Falcon Insight (EDR) only. Cases workbench is not available on this tier.
| Behaviour | What you get |
|---|---|
| Incidents table shape | Each Falcon detection becomes its own incident |
| Case context | Not available — Cases workbench doesn’t exist on this tier |
| Process Tree | Falls back to the alert payload’s 3-level lineage (no NG-SIEM ancestor walk) |
| Events Timeline | Falls back to the detection alerts on the device itself (no LogScale events) |
| Agents on queue / gamebook auto-run | Trigger on every detection |
| ”Incidents Detected” metric | Counts every detection ingested |
How the Pipeline Works
The ingestion shape is uniform across tiers — every Falcon detection becomes a ContraForce incident — and every downstream consumer reads from the same unified incident pipeline:| Stage | Behaviour |
|---|---|
| Poller (continuous) | Pulls alerts from CrowdStrike’s Alerts API and filters out container types (cases, automated leads, legacy CrowdScore incidents) so only Falcon detections enter the pipeline |
| Interactive incidents-table query | Same deny-list filter so what you see on a refresh matches what was queued |
IncidentDetected audit / metric | Written once per detection that enters the pipeline |
| Gamebook auto-run subscriber | Triggers on every detection that lands in the pipeline |
| Agents on queue | Same — agents trigger on every detection in the pipeline |
Per-Product Allow-List
Independent of the tier, each workspace can narrow ingestion to a subset of CrowdStrike’sproduct values via the Alert Types card on the Detection module configuration page. Useful for MSSPs whose contract scope is narrower than the customer’s full Falcon SKU.
How the filter is applied
The allow-list is enforced at every ingestion site so the queue, stats, agents, and gamebook auto-run all see the same shape:| Site | Filter behaviour |
|---|---|
| Poller (continuous) | Drops alerts whose product is outside the allow-list before queueing to the unified pipeline |
| Interactive incidents-table query | Same allow-list applied post-hydration so refresh matches the queue |
| Stats / “Incidents detected” metric | Counts only alerts that pass the allow-list |
| Related-incidents-by-entity | Same allow-list applied to related-incident search results |
Persistence model
| Stored value | Meaning |
|---|---|
null (default for pre-existing workspaces) | “Ingest all products” — no narrowing applied |
| Empty list | Same as null — friendly fallback when every box is unchecked |
Explicit list (e.g. ["epp", "idp"]) | Ingest only the listed products; everything else is dropped |
Tier-driven shortlist
The Alert Types card only shows the products typical for the declared tier by default to keep the UI compact:| Tier | Default checkbox shortlist |
|---|---|
| Falcon Insight (EDR) | epp |
| Falcon Insight XDR | epp, idp, xdr |
| Falcon NG-SIEM | All products (toggle hidden — no narrowing to do) |
Why a CF-side filter
CrowdStrike’s OAuth scopes don’t expose per-product granularity — the only available scope isalerts.read across all products. So the filter has to live in ContraForce code; we cannot narrow at the API-client level.
Verification Panel
After you click Test Connection on the configuration page, ContraForce runs a live probe of the API client and renders a verification panel below the form. The panel doesn’t override your tier choice — it confirms the claim against what’s actually present on the API client:| Indicator | Meaning |
|---|---|
| ✓ on Cases workbench | The Cases endpoint returned data — case context resolution will work on detections that reference a case |
| ✗ on Cases workbench | Cases endpoint returned no data — add Cases: Read + Write to the API client and confirm the tenant has the workbench enabled. Detections still ingest normally without it; only case-context resolution is degraded |
| ✓ on NG-SIEM | NG-SIEM is reachable; if the tenant has retention metadata, the panel shows the approximate base_sensor retention horizon |
| ✗ on NG-SIEM (NG-SIEM tier picked) | Add NGSIEM: Read + Write to the API client and confirm the tenant has the NG-SIEM SKU before saving |
| ℹ︎ on NG-SIEM (EDR / XDR tier picked) | NG-SIEM is reachable on this client but the declared tier doesn’t use it; pick the NG-SIEM tier to unlock the Process Tree ancestor walk and Events Timeline |
CrowdStrike Data Retention — How It Affects the Platform
The data ContraForce surfaces from CrowdStrike is bounded by Falcon’s own retention policy. The Falcon console may have access to additional historical data that ContraForce doesn’t query.Where retention shows up in the platform
| Surface | What’s bounded | By what |
|---|---|---|
| Detection Events Timeline (NG-SIEM tier) | The events shown for a detection | The base_sensor repository’s retention horizon on your Falcon NG-SIEM SKU. ContraForce reads this from the NG-SIEM repos-metadata endpoint at Test Connection / Save and persists it on the workspace; the Detection Events Timeline only queries within that window. |
| Process Tree ancestors (NG-SIEM tier) | How far back the ancestor walk reaches | Same base_sensor retention. Ancestor processes that started before the retention window are missing from the tree. The Falcon console can sometimes show ancestors beyond this because it has access to repositories ContraForce doesn’t query. |
| Detection visibility | The earliest incident you can investigate in ContraForce | CrowdStrike’s standard alert retention. Detections older than that no longer come back from the Alerts API at all. |
| Module configuration page | How fresh the verification panel’s NG-SIEM retention number is | The probe runs on Test Connection / Save. If retention has changed since you last saved, the displayed number may be stale until the next save. |
What this means in practice
| Symptom you might see | Likely cause |
|---|---|
| Process tree stops at a process you’d expect to have a parent | Parent process started before the base_sensor retention horizon |
| Events Timeline shows fewer events than the Falcon console for the same detection | Detection’s process lifetime spans events older than the NG-SIEM retention window |
| Detection Events Timeline is empty on the NG-SIEM tier | Either NG-SIEM scope is missing on the API client, or the tenant’s retention is shorter than the alert’s process lifetime — the verification panel and the saved retention horizon will tell you which |
| Older incidents from a few months ago aren’t accessible | The CrowdStrike Alerts / Cases retention has expired for those records on the tenant side |
Tuning the retention horizon
ContraForce does not control your CrowdStrike retention — it’s set by the customer’s NG-SIEM SKU. To change it:- Open the Falcon console
- Navigate to Next-Gen SIEM → Configuration → Settings → Data ingest (path may vary by tenant)
- Adjust the retention policy on the
base_sensorrepository according to your subscription terms - After the change takes effect, run Test Connection on the ContraForce configuration page so the new horizon persists on the workspace
How the Pieces Fit Together
The Detection API client carries the scopes for everything in the top-half (detection ingestion + investigation + case-context resolution + status writeback); the Response API client carries the scopes for the Hosts / ODS gamebook actions in the bottom half.Related Documentation
CrowdStrike Falcon Detection and Response Modules
Step-by-step setup with per-tier scope requirements
What are Gamebooks?
How Gamebook response actions work
Entity Insights
Investigation context for an incident’s entities
Roles and Permissions
Detailed role reference for ContraForce users
Questions about the CrowdStrike Falcon integration? Contact us at support@contraforce.com.