> ## 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.
# CrowdStrike Falcon Integration
> How ContraForce integrates with CrowdStrike Falcon — what it ingests, how the tier you declare changes the experience, and how Falcon's retention policy shapes what you see in the platform.
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.
**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](/guides/onboarding/crowdstrike-detection-and-response-modules).
## What the Integration Does
Polls CrowdStrike's unified Alerts API on a continuous loop and surfaces every new Falcon detection in the Command Dashboard as a ContraForce incident.
Hydrates the detection with process tree, events timeline, device, and identity context drawn from CrowdStrike NG-SIEM and the alert payload itself.
Status changes you make in ContraForce (New → In Progress → Closed) PATCH back to CrowdStrike via the Alerts API.
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.
Powers the Contain, Lift Containment, and On-Demand Scan Gamebooks on Falcon-managed devices via the Response API client.
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:
**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 |
**For tenants licensed for Falcon Insight XDR.** Cases workbench is active and used to resolve case context on detections that reference a case (and reserved for upcoming Cases features).
| Behaviour | What you get |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incidents table shape** | Each Falcon detection becomes its own incident (same as EDR) |
| **Case context** | Available — case metadata can be resolved on detections that reference a case. Cases themselves are not surfaced as incidents (see the Detection-first ingestion note above) |
| **Process Tree** | Falls back to the alert payload's 3-level lineage (NG-SIEM SKU is required for the ancestor walk) |
| **Events Timeline** | Falls back to the detection alerts on the device itself |
| **Agents on queue / gamebook auto-run** | Trigger on every detection |
| **"Incidents Detected" metric** | Counts every detection ingested |
**For tenants licensed for NG-SIEM.** Same detection-as-incident shape as the other tiers, plus the LogScale-backed Process Tree ancestor walk and the Events Timeline are unlocked.
| Behaviour | What you get |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incidents table shape** | Each Falcon detection becomes its own incident (same as EDR / XDR) |
| **Case context** | Available — case metadata can be resolved on detections that reference a case. Cases themselves are not surfaced as incidents |
| **Process Tree** | Full NG-SIEM ancestor walk via `ProcessRollup2` events on the `base_sensor` repository — surfaces System / smss.exe / winlogon.exe / userinit.exe / explorer.exe / etc. ancestors of the alerted process |
| **Events Timeline** | Real Falcon EDR telemetry from `base_sensor` (process starts, DLL / library loads, registry / ASEP, file create / new executable / new script, DNS, network in/out, logon) scoped to the alert's process lineage |
| **Agents on queue / gamebook auto-run** | Trigger on every detection |
| **"Incidents Detected" metric** | Counts every detection ingested |
The tier you declare must match the customer's actual Falcon SKU. The ingestion shape is the same on every tier — it's the **scopes** the API client needs and the **advanced investigation surfaces** that change. Picking NG-SIEM on a tenant that doesn't have the NG-SIEM SKU will produce missing-scope errors during Test Connection; picking EDR on an XDR / NG-SIEM tenant will leave the Process Tree ancestor walk and Events Timeline locked.
### 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 |
The tier you declare on the configuration page only changes which scopes the API client needs and which advanced investigation surfaces unlock. It does not change the ingestion shape.
***
## Per-Product Allow-List
Independent of the tier, each workspace can narrow ingestion to a subset of CrowdStrike's `product` 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 |
Detections from products outside the allow-list never reach the pipeline — they are dropped at the retriever / poller layer, not hidden in the UI. Re-enabling a product surfaces its detections from the next poll cycle onward; previously dropped detections are not back-filled.
### 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 |
Changing the allow-list is **independent of credential save**. The Alert Types card has its own Save button and does not require Test Connection or Client Secret re-entry.
### 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) |
A "Show all products" toggle reveals the full catalog for non-standard SKU combos (e.g. EDR + Mobile add-on). The toggle auto-defaults to "show all" when the persisted selection already includes products outside the tier shortlist, so saved selections are never hidden.
The shortlist is a UX hint rather than a hard licensing gate — the source of truth for tier-to-product availability still lives on the CrowdStrike side.
### Why a CF-side filter
CrowdStrike's OAuth scopes don't expose per-product granularity — the only available scope is `alerts.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 |
The verification panel is informational — you can save with a missing-required indicator, but the corresponding feature won't work until you add the scope and re-test.
***
## 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
**The Detection Events Timeline and Process Tree are subsets, not the full Falcon view.** ContraForce surfaces a banner above both surfaces on CrowdStrike incidents to remind you that the data shown is bounded by your tenant's NG-SIEM retention policy. If you need data beyond the retention window — older ancestors in the process tree, older events in the timeline — you must query the Falcon console directly.
| 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:
1. Open the Falcon console
2. Navigate to **Next-Gen SIEM → Configuration → Settings → Data ingest** (path may vary by tenant)
3. Adjust the retention policy on the `base_sensor` repository according to your subscription terms
4. 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
```mermaid theme={null}
flowchart LR
subgraph Falcon["CrowdStrike Falcon"]
AlertsAPI[Alerts API]
CasesAPI[Cases API]
NGSIEM[NG-SIEM
base_sensor]
Hosts[Hosts API]
ODS[On-Demand Scans]
end
subgraph Iris["ContraForce"]
Poller[Detection Poller]
Pipeline[Unified Incident Pipeline]
Dashboard[Command Dashboard]
Insights[Entity Insights]
Gamebooks[Gamebook Engine]
Agents[Agents on Queue]
Audit[Audit Log]
end
AlertsAPI -->|polls detections| Poller
Poller -->|every detection| Pipeline
Pipeline --> Dashboard
Pipeline --> Agents
Pipeline -->|IncidentDetected| Audit
Pipeline -->|on new incident| Gamebooks
Insights -->|process tree, events| NGSIEM
Insights -->|case context| CasesAPI
Gamebooks -->|Contain / Lift / Scan| Hosts
Gamebooks -->|Scan| ODS
Dashboard -->|owner read| Audit
Dashboard -->|status / comments| AlertsAPI
```
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
Step-by-step setup with per-tier scope requirements
How Gamebook response actions work
Investigation context for an incident's entities
Detailed role reference for ContraForce users
***
Questions about the CrowdStrike Falcon integration? Contact us at [support@contraforce.com](mailto:support@contraforce.com).