> ## 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 Detection and Response Modules
> Connect the CrowdStrike Falcon Detection and Response modules to a ContraForce workspace to ingest Falcon detections as incidents and enable endpoint response actions.
**Who is this for?** Workspace Admins or Security Engineers who manage a workspace that uses CrowdStrike Falcon. This guide walks you through creating the CrowdStrike API clients, configuring both modules in ContraForce, and verifying that alerts flow end-to-end.
## Before You Begin
### What These Modules Do
CrowdStrike integrates with ContraForce through two separate modules:
**Detection ingestion and investigation**
* Pulls Falcon detections from the CrowdStrike Alerts API
* Surfaces every detection as its own ContraForce incident
* Round-trips status changes and comments back to Falcon
**Gamebook response actions**
* Powers Contain and Lift Containment Gamebooks
* Powers On-Demand Scan Gamebooks
* Required for any Gamebook that acts on a CrowdStrike-managed device
The two modules use separate CrowdStrike API clients so each client has only the scopes it needs.
### Prerequisites
An active CrowdStrike Falcon subscription with at least one product line in scope (EPP, IDP, or any of the product lines listed in **Select Alert Types** below).
Access to **API Clients and Keys** under **Support and resources → Resources and tools** in the Falcon console. This typically requires the Falcon Administrator role.
A ContraForce workspace created for the tenant, with your account assigned the **Workspace Admin** role.
Identify which CrowdStrike cloud your tenant is deployed in. You need this for the **Base URL** field when configuring each module.
### CrowdStrike Cloud Base URLs
CrowdStrike has multiple regional clouds. Use the Base URL that matches your tenant:
| Cloud | Base URL |
| ----------------- | ---------------------------------- |
| US-1 (Commercial) | `https://api.crowdstrike.com` |
| US-2 | `https://api.us-2.crowdstrike.com` |
| EU-1 | `https://api.eu-1.crowdstrike.com` |
ContraForce does not currently support CrowdStrike's US-GOV-1 cloud. Contact [support@contraforce.com](mailto:support@contraforce.com) if you have a GovCloud tenant.
You can confirm which cloud your tenant is in by looking at the URL of your Falcon console. A console URL of `https://falcon.us-2.crowdstrike.com` means you're on US-2.
***
## Step 1 — Create the Detection API Client in Falcon
The scopes you grant on the Detection API client depend on which **Falcon tier** the customer is licensed for. Pick the matching column below — the tier you choose here must match what you select on the ContraForce configuration page in Step 3.
1. Navigate to **Support and resources → Resources and tools → API Clients and Keys** in the Falcon console
2. Click **Create API client**
3. Set **Client name** to `ContraForce Detection`
4. Set **Description** to `ContraForce alert ingestion and status writeback`
5. Under **API scopes**, grant the scopes for the customer's tier, then click **Create**:
For tenants on **Falcon Insight (EDR) only.** Cases workbench is not available on this tier.
| Resource | Permission | Why |
| ----------------------------------- | ------------ | ----------------------------------------- |
| **Alerts** | Read + Write | Ingest detections and update their status |
| **User Management** | Read | Resolve assignee names on detections |
| **Hosts** | Read | Resolve device metadata on detections |
| **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities |
For tenants licensed for **Falcon Insight XDR.** Cases workbench is active.
| Resource | Permission | Why |
| ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Alerts** | Read + Write | Ingest detections and update their status |
| **Cases** | Read + Write | Resolve case context for detections that reference a case (used by detail views and reserved for upcoming Cases features) |
| **User Management** | Read | Resolve assignee names on detections |
| **Hosts** | Read | Resolve device metadata on detections |
| **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities |
For tenants licensed for **NG-SIEM.** Same detection-as-incident shape as the other tiers, plus the LogScale-backed Process Tree ancestor walk and Events Timeline are unlocked.
| Resource | Permission | Why |
| ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Alerts** | Read + Write | Ingest detections and update their status |
| **Cases** | Read + Write | Resolve case context for detections that reference a case (used by detail views and reserved for upcoming Cases features) |
| **User Management** | Read | Resolve assignee names on detections |
| **Hosts** | Read | Resolve device metadata on detections |
| **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities |
| **NGSIEM** | Read + Write | Run LogScale searches for Process Tree and Events Timeline. Write is needed to start search jobs |
Copy the **Client ID** and **Client Secret** to a secure location — the secret is only shown once.
The Client Secret is shown once at creation time and cannot be retrieved later. If you lose it, you must reset the secret from the same API client in Falcon.
***
## Step 2 — Create the Response API Client in Falcon
Repeat the process for a second API client that ContraForce will use for Gamebook response actions.
1. In the same **API Clients and Keys** menu, click **Create API client**
2. Set **Client name** to `ContraForce Response`
3. Set **Description** to `ContraForce Gamebook response actions`
4. Under **API scopes**, grant the scopes listed below, then click **Create**:
| Resource | Permission |
| ------------------------- | ------------ |
| **Hosts** | Read + Write |
| **On-Demand Scans (ODS)** | Read + Write |
Copy the **Client ID** and **Client Secret** for the Response client.
Creating two separate API clients — one for Detection, one for Response — follows the principle of least privilege. The Detection client never needs to contain a device or run a scan, and the Response client never needs to read an alert.
***
## Step 3 — Configure the CrowdStrike Falcon Module in ContraForce
1. In the ContraForce portal, navigate to **Workspaces** → your workspace → **Modules**
2. Locate the **CrowdStrike Falcon** card and click **Configure**
3. Pick the **Falcon licensing tier** that matches the customer's CrowdStrike SKU. The required-scopes list, the incidents-table preview copy, and the verification panel all update based on this selection:
| Tier | When to pick it | Effect on the platform |
| ------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Falcon Insight (EDR)** | Customer is on Falcon Insight (EDR) only — no Cases workbench, no NG-SIEM SKU | Each Falcon detection becomes its own incident in the table |
| **Falcon Insight XDR** | Customer is licensed for XDR with Cases workbench but no NG-SIEM SKU | Each Falcon detection becomes its own incident; case context is resolvable on detections that reference a case |
| **Falcon NG-SIEM** | Customer is licensed for NG-SIEM | Same detection-as-incident shape, plus LogScale-backed Process Tree ancestor walk and Events Timeline are unlocked |
The tier you pick must match the customer's actual Falcon SKU. The required scopes and which advanced features (Process Tree ancestor walk, Events Timeline) unlock depend on the tier — see [CrowdStrike Falcon Integration → Tier Selection](/guides/technical/crowdstrike-falcon-integration#tier-selection-—-what-you-pick-on-the-configuration-page) for the full breakdown.
1. Fill in the following fields:
| Field | Value |
| ----------------- | ----------------------------------------------------------------- |
| **Base URL** | The Base URL for your CrowdStrike cloud (see table above) |
| **Client ID** | The Client ID from the Detection API client you created in Step 1 |
| **Client Secret** | The Client Secret from the Detection API client |
1. Click **Test Connection** to verify the credentials reach CrowdStrike and have the scopes the selected tier requires
2. Review the **Verification panel** that appears below the form:
* ✓ on a row means the API client has that scope and the tenant exposes the corresponding capability
* ✗ on a row means the scope or capability is missing for the tier you picked — fix it in the Falcon console before saving
* ℹ︎ on a row means the API client has more capability than the tier you picked uses (e.g. NG-SIEM is reachable but you picked Falcon Insight XDR) — pick a higher tier to unlock the advanced features
3. Click **Save**
If Test Connection fails with a scope-missing error, return to the Falcon console and verify the scopes listed in Step 1 for the tier you picked.
### What You'll See After Saving
The configuration page surfaces a "What you'll see in the incidents table" preview directly under the tier dropdown, so you can confirm the choice before saving. After Save, the incidents table reflects that preview the next time the poller runs (typically within a few minutes).
### Tune Which Products Are Ingested (Optional)
After the credentials are saved, an **Alert Types** card appears as a sibling to the Configuration Information card. Use it to narrow which CrowdStrike products ContraForce ingests into the analyst queue — useful when you're contracted to triage only a subset of the products the customer's Falcon tenant emits.
| Product | Wire form | Surfaces |
| ------------------------- | ------------ | ------------------------------------------------- |
| **Endpoint (EPP)** | `epp` | Falcon Insight endpoint-protection detections |
| **Identity (IDP)** | `idp` | Falcon Identity Protection alerts |
| **Mobile** | `mobile` | Falcon for Mobile alerts |
| **Data Protection** | `dp` | Falcon Data Protection alerts |
| **NG-SIEM** | `ngsiem` | NG-SIEM correlation alerts |
| **XDR** | `xdr` | Cross-platform correlated detections |
| **Cloud Workload (CWPP)** | `cwpp` | Falcon Cloud Security workload-protection alerts |
| **OverWatch** | `overwatch` | Falcon OverWatch managed-threat-hunting alerts |
| **Third-Party** | `thirdparty` | Alerts ingested from integrated third-party tools |
The card is **tier-aware** by default to cut UI noise:
| Tier | Default checkbox shortlist |
| ------------------------ | -------------------------- |
| **Falcon Insight (EDR)** | EPP |
| **Falcon Insight XDR** | EPP, IDP, XDR |
| **Falcon NG-SIEM** | All products |
Click **Show all products** above the checkbox list (visible on EDR / XDR tiers) to reveal the full catalog when the customer has non-standard add-ons (e.g. EDR with the Mobile add-on). The toggle auto-defaults to "show all" when the persisted selection already includes products outside the tier shortlist.
Saving the Alert Types card is **independent of Test Connection**. Changing the product selection does not require re-validating credentials or re-saving the Detection module — the card has its own Save button.
Leaving every product checked, or unchecking every product, both fall through to "ingest all products." This preserves backwards-compatibility for workspaces created before the per-product filter shipped, and acts as a friendly fallback if you accidentally clear every box.
### Choose a Vendor-Side Service Account (Optional)
By default, when one of your analysts takes a CrowdStrike-sourced incident in ContraForce, the assignment is recorded in the ContraForce audit log only and the underlying Falcon alert stays unassigned. This is the right default for tenants where every analyst already has a Falcon login, but in MSSP topologies most ContraForce analysts have no matching principal in the customer's Falcon tenant.
The **Assignment Writeback** card lets you bind one CrowdStrike user (typically a named service account in the customer's Falcon tenant, e.g. `Stratascale ContraForce`) so that ContraForce mirrors every analyst assignment onto the underlying Falcon alert as that user. The end customer sees someone is actively engaged in their own Falcon console, without you having to provision a per-analyst account in every customer's tenant.
| State | Behavior |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **None (default)** | Assignment is recorded in the ContraForce audit log only. No vendor write. |
| **Bound** | The selected Falcon user is PATCHed onto the alert as the vendor-side assignee on every analyst assignment in ContraForce. Unassigning in ContraForce also clears the assignee on Falcon. |
To bind a service account:
On the Assignment Writeback card, click **Change**. ContraForce queries the customer's Falcon user-management API (this requires the **User Management: Read** scope on the Detection client, already part of every tier in Step 1).
Type a name or email into the search box; the picker filters the live Falcon user list as you type. Pick the user that should appear as the assignee on the customer's Falcon console.
Click **Save Service Account**. Future analyst assignments in ContraForce immediately mirror onto the underlying Falcon alert as the chosen user.
To stop writing back, click **Remove** on the bound state, then **Save Service Account**. The card returns to **None** and the audit-only behavior resumes.
The ContraForce audit log is always the source of truth for who actually picked up an incident, regardless of what shows on the Falcon side. The writeback only controls visibility in the customer's Falcon console.
The writeback only affects detections (alerts that contain a colon-shaped composite ID). Legacy case-shaped IDs continue to behave as audit-only. If the Falcon PATCH fails (network blip, Falcon-side outage, the bound user was deleted), ContraForce records the failure in the trace logs and continues with the audit-only assignment so your queue stays responsive.
***
## Step 4 — Configure the CrowdStrike Falcon Response Module
1. On the same **Modules** page, locate the **CrowdStrike Falcon Response** card and click **Configure**
2. Fill in the following fields:
| Field | Value |
| ----------------- | -------------------------------------------------------------------- |
| **Base URL** | Same Base URL as the Detection module |
| **Client ID** | The Client ID from the **Response** API client you created in Step 2 |
| **Client Secret** | The Client Secret from the **Response** API client |
1. Click **Test Connection** to verify the credentials reach CrowdStrike and have the required scopes
2. Click **Save**
A successful test means Gamebook response actions are ready for CrowdStrike-managed devices.
***
## Step 5 — Verify End-to-End
The Detection module polls CrowdStrike on a short interval. New alerts appear in ContraForce within a few minutes of being generated in Falcon.
Navigate to the **Command Dashboard**. CrowdStrike incidents should appear alongside incidents from other sources.
Click into a CrowdStrike incident and verify that the **Entities** and **Timeline** tabs are populated with alert data.
If the Response module is configured, open a CrowdStrike incident where the affected entity is a device and confirm that **Contain**, **Lift Containment**, and **On-Demand Scan** Gamebook actions are available.
***
## What Each Module Unlocks
| Capability | Requires Detection | Requires Response |
| ----------------------------------------------------- | :----------------: | :---------------: |
| Ingest CrowdStrike Falcon detections as incidents | ✓ | |
| Round-trip status, assignment, and comments to Falcon | ✓ | |
| Receive real-time incident updates in the portal | ✓ | |
| Run Contain and Lift Containment Gamebooks | | ✓ |
| Run On-Demand Scan Gamebooks | | ✓ |
| Trigger Security Delivery Agents on new incidents | ✓ | |
You can configure the Detection module without the Response module if you don't need Gamebook response actions for CrowdStrike devices. Configuring only the Response module without Detection is not a supported configuration — you'd have no incidents for the Gamebooks to run on.
***
## Troubleshooting
| Issue | Likely cause | Fix |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test Connection fails with `missing the 'Alerts: Read' scope` | The Detection API client does not have Alerts: Read granted | Return to **API Clients and Keys** in Falcon, edit the Detection client, enable **Alerts: Read**, and save |
| Test Connection fails with `missing the 'Hosts: Write' scope` | The Response API client does not have Hosts: Write granted | Edit the Response client and enable **Hosts: Write** |
| Test Connection fails with a generic OAuth error | The **Base URL** does not match the tenant's actual CrowdStrike cloud | Verify the Base URL against the cloud table above; cross-check against the Falcon console URL |
| Verification panel shows ✗ on **Cases workbench** for XDR / NG-SIEM tier | The Detection API client does not have **Cases: Read + Write** granted | Edit the Detection client and add Cases: Read + Write, then re-run Test Connection. Without it, ContraForce can ingest detections normally but won't be able to resolve case context on detections that reference a case |
| Verification panel shows ✗ on **NG-SIEM** for the NG-SIEM tier | The Detection API client does not have **NGSIEM: Read + Write** granted, or the tenant does not have the NG-SIEM SKU | Edit the Detection client and add NGSIEM: Read + Write; if the scope still doesn't appear in the Falcon console it means the tenant isn't licensed for NG-SIEM and you should pick the XDR tier instead |
| Process Tree shows only the triggering process (no ancestors) | Tenant tier was set to EDR or XDR, or the NG-SIEM scope is missing | Confirm the customer is licensed for NG-SIEM and the tier dropdown reflects that; verify the NGSIEM scope on the Detection client |
| Detection Events Timeline is empty on the NG-SIEM tier | NG-SIEM scope missing, or the alert's process lifetime predates the `base_sensor` retention horizon | Check the verification panel for ✗ on NG-SIEM; if the scope is fine, the older detection's events have aged out — see the [retention disclosure](/guides/technical/crowdstrike-falcon-integration#crowdstrike-data-retention-—-how-it-affects-the-platform) |
| Incidents table is empty even though detections are firing in Falcon | Time filter or product filter on the queue is excluding everything; or the API client lost its **Alerts: Read** scope | Widen the date filter to a known-detection window, confirm Alerts: Read is still granted, and re-test the connection |
| Gamebook response actions are greyed out | The Response module is not configured | Complete Step 4 to configure the Response module |
| Agent comments do not appear in Falcon | The Detection API client does not have Alerts: Write | Add **Alerts: Write** to the Detection client |
| Incident owner you assigned in ContraForce isn't reflected in Falcon | The Assignment Writeback card is set to **None** (the default), so the assignment is audit-only on the ContraForce side | Bind a Falcon service account on the Assignment Writeback card (see [Choose a Vendor-Side Service Account](#choose-a-vendor-side-service-account-optional)) and re-assign the incident |
| Assignment Writeback card shows "Failed to load Falcon users" | The Detection API client does not have the **User Management: Read** scope | Edit the Detection API client in Falcon, add **User Management: Read**, and re-run Test Connection |
| Bound service account no longer appears as the Falcon-side assignee | The bound user was disabled or deleted in the customer's Falcon tenant | Open the Assignment Writeback card, click **Change**, pick a still-active user, and save |
### Rotating an API Secret
CrowdStrike secrets do not expire automatically, but some organizations rotate them on a schedule.
1. In Falcon, open the affected API client and click **Reset secret**
2. Copy the new secret
3. In ContraForce, reopen the affected module (Detection or Response)
4. Paste the new secret into **Client Secret** and click **Save**
5. Click **Test Connection** to verify
***
## Related Documentation
What the integration does, what each tier unlocks, and how Falcon's retention shapes the data shown in the platform
Learn how Gamebook response actions work
Triage and resolve incidents in ContraForce
Explore investigation context for an incident's entities
Detailed role reference for ContraForce users
***
Questions about connecting CrowdStrike Falcon to ContraForce? Contact us at [support@contraforce.com](mailto:support@contraforce.com).