> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CrowdStrike Falcon

> Bi-directional integration between CaseBender and CrowdStrike Falcon for detection ingestion (pull or push) and disposition sync.

## Overview

The CrowdStrike Falcon integration (**INT-008**) ingests Falcon detections into CaseBender
and can push case dispositions back to Falcon when a case is closed.

<CardGroup cols={2}>
  <Card title="Inbound Ingestion" icon="arrow-right-to-bracket">
    Falcon detections are ingested — either **pulled automatically** on a
    schedule (recommended) or **pushed** via a webhook — then normalized,
    enriched with observables and MITRE ATT\&CK techniques, and turned into alerts.
  </Card>

  <Card title="Outbound Disposition Sync" icon="arrow-right-from-bracket">
    When a linked CaseBender case is closed, the Falcon detection status is
    updated with an audit comment.
  </Card>
</CardGroup>

<Tip>
  **Recommended: enable Automatic polling.** CaseBender can pull new detections
  on a schedule using the same Falcon API client — no webhook or SIEM connector
  is required. See [Automatic polling](#inbound-automatic-polling-recommended).
</Tip>

<Note>
  This integration uses the **Falcon Alerts API v2** and authenticates with an
  **OAuth2 API client** (client ID + secret) using the client-credentials flow.
</Note>

## Capabilities

| Capability                   | Direction      | Description                                                                                                   |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
| **Detection polling (pull)** | Inbound        | CaseBender polls the Alerts API on a schedule and ingests new detections automatically — no Falcon-side setup |
| Detection ingestion (push)   | Inbound        | Falcon detections are pushed via webhook and normalized into CaseBender alerts                                |
| Observable extraction        | Inbound        | IPs, file hashes, file names, hostnames, and users are extracted                                              |
| MITRE ATT\&CK correlation    | Inbound        | Technique/tactic IDs are added as tags and TTPs                                                               |
| Disposition sync             | Outbound       | Detection status + comment are pushed on case close                                                           |
| Connection test              | Bi-directional | Validates OAuth2 credentials and API access                                                                   |

## Prerequisites

<Steps>
  <Step title="Falcon API client">
    In the Falcon console, go to **Support and resources → API clients and keys**
    and create an API client. Grant the **Alerts: Read** scope (and **Alerts:
    Write** if you want outbound close-back). Copy the **Client ID** and **Secret**.
  </Step>

  <Step title="Cloud region base URL">
    Note your Falcon cloud base URL (e.g. `https://api.crowdstrike.com`,
    `https://api.us-2.crowdstrike.com`, or `https://api.eu-1.crowdstrike.com`).
  </Step>

  <Step title="Network egress">
    The CaseBender poller service must be able to reach your Falcon API base URL.
  </Step>
</Steps>

## Configure the integration in CaseBender

<Steps>
  <Step title="Open the integration catalog">
    Go to **Settings → Integrations → Create**, then choose **CrowdStrike Falcon**
    from the **EDR/XDR** category.
  </Step>

  <Step title="Enter Falcon API credentials">
    | Field                    | Description                                                   |
    | ------------------------ | ------------------------------------------------------------- |
    | API URL                  | Falcon cloud base URL (default `https://api.crowdstrike.com`) |
    | Falcon API Client ID     | The OAuth2 client ID                                          |
    | Falcon API Client Secret | The OAuth2 client secret                                      |
  </Step>

  <Step title="Enable automatic polling (recommended)">
    In the **Automatic polling** card, turn on **Enable automatic polling** and set:

    | Option                        | Effect                                                                                 |
    | ----------------------------- | -------------------------------------------------------------------------------------- |
    | `pollingEnabled`              | Turn on scheduled pulling of Falcon detections                                         |
    | `pollingIntervalMinutes`      | How often to poll (default `5`, range 1–1440)                                          |
    | `pollingInitialLookbackHours` | On first run, import detections updated within this window (default `24`, range 1–168) |
    | `pollMaxItemsPerRun`          | Safety cap on items ingested per run (default `500`)                                   |
  </Step>

  <Step title="Configure auto-case creation">
    | Option               | Effect                                                                                                                 |
    | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
    | `autoCreateCases`    | Promote each ingested detection to a **Case** (deduped by detection ID). When off, detections stay in the Alerts inbox |
    | `minSeverityForCase` | Only auto-create cases at/above this severity                                                                          |
  </Step>
</Steps>

## Inbound (automatic polling, recommended)

With **Automatic polling** enabled, the CaseBender poller periodically queries the Falcon
Alerts API and ingests new detections on its own.

<Steps>
  <Step title="Scheduled pull">
    On each interval, CaseBender queries the Alerts API v2 for composite IDs updated since the
    last cursor, then fetches the full detection entities. On the first run there is no cursor,
    so detections updated within `pollingInitialLookbackHours` are imported.
  </Step>

  <Step title="Cursor + deduplication">
    CaseBender advances a per-integration cursor to the newest `updated_timestamp` it has seen.
    Detections are **deduplicated by detection ID**, so overlapping polling windows never create
    duplicate alerts.
  </Step>

  <Step title="Normalization">
    Each detection is normalized into a CaseBender alert — mapping severity, building the
    title/description, extracting observables, and generating MITRE TTPs.
  </Step>
</Steps>

<Info>
  Polling runs in CaseBender's background poller service. Ensure that service can reach your
  Falcon API base URL (directly or via your configured proxy).
</Info>

## Inbound (webhook / push)

As an alternative to polling, Falcon (or an intermediary) can push detection payloads to the
CaseBender ingestion endpoint:

```
POST https://<your-casebender-domain>/api/v1/ingest/crowdstrike
```

Requests are authenticated with an integration **API key** in the `x-api-key` header. Falcon
webhook API keys are prefixed with `cbr_crowdstrike_`.

## Outbound: syncing case dispositions to Falcon

When a case is closed, the `case_closed` event is dispatched to the CrowdStrike handler. If the
case is linked to a Falcon detection (the detection ID is stamped onto the ingested alert), the
handler updates the detection status and adds an audit comment. Outbound close-back requires the
**Alerts: Write** scope on the API client.

## Security considerations

* **Least privilege** — grant **Alerts: Read** for inbound only; add **Alerts: Write** only if
  you enable outbound close-back.
* **Secret handling** — the client secret is stored in the integration settings; rotate on your
  organization's schedule.
* **Token caching** — access tokens are cached in memory and refreshed before expiry.
* **Network** — restrict egress to your Falcon API base URL.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test Connection fails with an OAuth2 error">
    Verify the client ID, secret, and API base URL (region). Confirm the API client is enabled
    and has the Alerts scope.
  </Accordion>

  <Accordion title="Polling is enabled but no detections appear">
    Confirm **Enable automatic polling** is on and the API client has the Alerts: Read scope.
    Check the poller can reach your Falcon base URL. On first run only detections within
    `pollingInitialLookbackHours` are imported.

    **Make sure all CaseBender services are running.** Detections are fetched by the background
    processor and turned into alerts (and optionally cases) by the background **worker**. With
    Docker, run `docker compose ps` and confirm the `worker` and `misp-processor` services are
    `Up`.
  </Accordion>

  <Accordion title="Case close doesn't update Falcon">
    Ensure the API client has the Alerts: Write scope and the case is linked to a Falcon
    detection. Check the case timeline for the sync result.
  </Accordion>
</AccordionGroup>

## Related documentation

* [Integrations overview](./introduction.mdx)
* [CrowdStrike Falcon API documentation](https://falcon.crowdstrike.com/documentation/)