Skip to main content

CrowdStrike Setup for dfe-fetcher

What a CrowdStrike Falcon administrator needs to configure so dfe-fetcher can read alert data from a Falcon tenant.

Overview​

dfe-fetcher reads CrowdStrike alerts via the Falcon public API. It authenticates with an OAuth2 API client (client ID + secret) using the client_credentials grant against /oauth2/token, then sends the returned bearer token to the data endpoints. Tokens are valid for 30 minutes and the fetcher refreshes them automatically.

The alerts service is a two-stage call against the Alerts API:

  1. GET /alerts/queries/alerts/v2 - returns alert composite IDs for the time window (Falcon Query Language created_timestamp filter).
  2. POST /alerts/entities/alerts/v2 with {"composite_ids": [...]} - returns full alert entities for those IDs, in batches of up to 1000.

Falcon tenants live on different cloud regions, each with its own API host. The admin's only job is to create an OAuth2 API client with the right scope and tell dfe-fetcher which region to use.

The source is the shipped crowdstrike profile (crates/fetcher/profiles/crowdstrike.yaml); the sources.crowdstrike block below maps onto an instance of it at load. The id query walks offset against meta.pagination.total and the entity lookup runs per batch of ids; both calls are reads, so a 429 or 5xx on either is retried with backoff (honouring Retry-After), a refused exchange or a 401 or 403 ends the tick, and a tick that fails does not advance the fetch window. A missing client id or secret is refused at load, naming sources.crowdstrike.

History (2026). CrowdStrike renamed "Detections" to "Alerts" and introduced the Alerts API. The legacy /detects/* endpoints were deprecated 2024-10-01 and decommissioned 2025-09-30. dfe-fetcher uses the Alerts API (/alerts/queries/alerts/v2 + /alerts/entities/alerts/v2), which needs the Alerts: Read scope.

Prerequisites​

  • A CrowdStrike Falcon subscription with the Falcon console.
  • The Falcon Administrator role (required to view, create, or modify OAuth2 API clients and keys).
  • Knowledge of which Falcon cloud region your tenant lives on (shown as the Base URL on the API clients page).

Required Permissions​

ServiceObject/EndpointPermission or ScopeNotes
AlertsGET /alerts/queries/alerts/v2 (stage 1)Alerts: ReadRead-only. Returns alert composite IDs.
AlertsPOST /alerts/entities/alerts/v2 (stage 2)Alerts: ReadRead-only. Returns full alert entities.
OAuth2 tokenPOST /oauth2/token(no scope - the API client itself)client_credentials grant. Always required.

Select only the scope your flow needs (least privilege). No write scope is required.

Source-Side Setup​

  1. Sign in to the Falcon console with a Falcon Administrator account, in the cloud region where your tenant lives.

  2. Open the API clients page. Navigate to Support and resources > Resources and tools > API clients and keys. (Older consoles list this as Support > API clients and keys.)

  3. Create the API client. Under OAuth2 API clients, click Create API client. Enter:

    • Client name: dfe-fetcher
    • Description: e.g. "dfe-fetcher alert pull (read-only)"

  4. Select scopes. In the scopes table, tick Read for Alerts. Leave all Write boxes unchecked.

  5. Save and capture credentials. Click Create. Falcon shows the Client ID, Client Secret, and Base URL once only. Copy all three now - the secret cannot be retrieved later (a reset is required if lost).

  6. Note the Base URL for your region:

    RegionBase URL
    US-1 (default)https://api.crowdstrike.com
    US-2https://api.us-2.crowdstrike.com
    EU-1https://api.eu-1.crowdstrike.com
    US-GOV-1https://api.laggar.gcw.crowdstrike.com

  7. (Optional) Verify the token exchange from a shell:

    curl -s -X POST "https://api.crowdstrike.com/oauth2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "client_id=<CLIENT_ID>" \
      -d "client_secret=<CLIENT_SECRET>"

    A successful response includes access_token and expires_in (1800). Replace the host with your region's Base URL.

dfe-fetcher Configuration​

The CrowdStrike source config fields are: enabled, api_url_override (region base URL), client_id, client_secret, credential_secret, interval_secs, services, connections, topic, filter. The only service is alerts.

Config File​

sources:
  crowdstrike:
    enabled: true
    # Region base URL. Omit for US-1 default (https://api.crowdstrike.com).
    # api_url_override: "https://api.eu-1.crowdstrike.com"
    client_id: "your-oauth2-client-id"
    client_secret: "your-oauth2-client-secret"
    services:
      - name: alerts
        # config:
        #   limit: 100               # query page size, max 1000
        #   filter: "severity:>=70"  # extra Falcon Query Language clause
    topic: "crowdstrike"
    # filter: 'severity >= 70'  # hot-reloaded CEL expression

Environment Variables​

DFE_FETCHER_SOURCES__CROWDSTRIKE__ENABLED="true"
DFE_FETCHER_SOURCES__CROWDSTRIKE__API_URL_OVERRIDE="https://api.eu-1.crowdstrike.com"
DFE_FETCHER_SOURCES__CROWDSTRIKE__CLIENT_ID="your-oauth2-client-id"
DFE_FETCHER_SOURCES__CROWDSTRIKE__CLIENT_SECRET="your-oauth2-client-secret"

Secrets Manager (Production)​

Keep the client secret out of the config file with credential_secret:

sources:
  crowdstrike:
    enabled: true
    # api_url_override: "https://api.us-2.crowdstrike.com"
    client_id: "your-oauth2-client-id"
    credential_secret: "vault:kv/data/dfe/crowdstrike:client_secret"
    services:
      - name: alerts
    topic: "crowdstrike"

credential_secret resolves to the OAuth2 client secret. When set, it takes precedence over an inline client_secret.

Verification​

Health check. The health check is the token exchange (the cheapest valid auth probe). A healthy result means the client ID/secret and region base URL are correct - it does NOT confirm the Alerts: Read scope. A refused exchange is a health error carrying the response.

Live smoke tests. crates/fetcher/tests/e2e/smoke_remote.rs has env-gated, #[ignore]d tests that hit a real tenant. They read these variables (canonical .env-cloud, fallback .env):

  • CROWDSTRIKE_CLIENT_ID
  • CROWDSTRIKE_CLIENT_SECRET
  • CROWDSTRIKE_API_BASE (optional; maps to api_url_override)

Run them:

cargo test -p dfe-fetcher --test e2e crowdstrike_ -- --ignored

Results are tagged crowdstrike.alerts. Zero records is normal on a quiet tenant or a short lookback window.

Common failures.

  • 401/token exchange fails - wrong client ID/secret, or the secret was rotated. Reset the secret in the console and update config.
  • 403 Forbidden on the alert query - the API client lacks the read scope (grant Alerts: Read).
  • Token works but zero records every cycle - check the region base URL and that alerts exist in the lookback window; widen with a longer interval or a filter adjustment.

Cost​

dfe-fetcher only reads. OAuth2 API clients and Alerts API reads are generally included with a Falcon subscription and not expected to carry an additional charge, though this can depend on your CrowdStrike entitlements. Confirm any cost implications against your own CrowdStrike agreement.

References​