# CrowdStrike Falcon Integration

Connect your CrowdStrike Falcon tenant to Capsule Security to discover the AI agents, local LLMs, and vibe-coding tools running on your endpoints.

## Overview

This integration uses CrowdStrike's Falcon platform APIs to sync:

- **Devices** - Host detail from the Falcon Hosts API (hostnames, OS, last-seen user, IP addresses, agent version) for the hosts where Capsule found AI activity
- **Local LLM models** - Ollama, LM Studio, and other local model runtimes detected from process telemetry
- **AI coding agents** - Claude Code, Cursor, GitHub Copilot, Cline, and similar developer agents observed on managed devices
- **Vibe-coding apps** - DNS and network telemetry to surface AI-assisted browser-based coding tools (Lovable, Replit, Bolt, Base44, etc.)
- **Device owners** - Last-login users mapped from Falcon agent telemetry


The integration uses the `xdr` NG-SIEM repository for telemetry queries and the standard Hosts API to resolve detail for the hosts those queries surface.

## Prerequisites

Before you begin, ensure you have:

- An active **CrowdStrike Falcon** subscription with the **Falcon Insight XDR** or **Falcon Complete** module (for Next-Gen SIEM telemetry)
- **Falcon Administrator** role, or another role with permission to create API clients
- The **Falcon cloud region** your tenant is hosted in (US-1, US-2, EU-1, US-GOV-1, or US-GOV-2)


> **Grant both telemetry scopes.** Capsule discovers AI activity through two Falcon surfaces, and each sees things the other cannot:
- **NGSIEM** - process-level telemetry. Local LLMs actually running, including models that never touch the network; AI coding agents and the processes they spawn; command lines; skill usage. Requires Falcon Next-Gen SIEM to be licensed on the tenant.
- **Threatgraph** - network-derived discovery. Which devices contacted known AI / LLM / vibe-coding domains, and the process behind each connection. Runs on baseline Falcon Insight, so it is available on every tenant.

Granting only one narrows what Capsule can show you - [Feature availability by scope](#feature-availability-by-scope) sets out exactly what each covers.
**Note:** When Next-Gen SIEM is licensed, Capsule queries the `xdr` repository by default. If your tenant uses a non-default repository, contact Capsule support before installing.


## Step 1: Create an API Client in the Falcon Console

Capsule authenticates to CrowdStrike using OAuth2 client credentials. You need to create a dedicated API client and grant it the scopes listed below.

### Steps

1. Sign in to the **Falcon Console** for your region:
| Region | Console URL |
|  --- | --- |
| `us-1` | `https://falcon.crowdstrike.com` |
| `us-2` | `https://falcon.us-2.crowdstrike.com` |
| `eu-1` | `https://falcon.eu-1.crowdstrike.com` |
| `us-gov-1` | `https://falcon.laggar.gcw.crowdstrike.com` |
| `us-gov-2` | `https://falcon.us-gov-2.crowdstrike.mil` |
2. From the menu, navigate to **Support and resources → API clients and keys** (sometimes shown as **Support → API Clients and Keys**).
3. Click **Create API client**.
4. Configure the client:
  - **Client name**: Enter a descriptive name (e.g., `Capsule Security Integration`)
  - **Description**: Optional - e.g., `Capsule Security - Hosts, Threatgraph, NGSIEM`
  - **API scopes**: See **Required Scopes** below - grant exactly the permission listed for each scope (**Read** everywhere; **Read and Write** on `NGSIEM`)
5. Click **Create**.
6. **Important**: Copy the **Client ID** and **Client Secret** immediately. The secret is shown only once and cannot be retrieved later.
7. Note your **Base URL / Cloud** value displayed on the same screen - this is the region you'll select in Step 2 (e.g., `US-1`, `US-2`, `EU-1`, `US-GOV-1`, `US-GOV-2`).


### Required Scopes

Every scope is `Read` only, with one exception: **`NGSIEM` needs both `Read` and `Write`**. CrowdStrike gates starting a Next-Gen SIEM search under `NGSIEM: WRITE` and reading its results under `NGSIEM: READ` - see the [`StartSearchV1`](https://developer.crowdstrike.com/api-reference/operations/StartSearchV1.md) and [`GetSearchStatusV1`](https://developer.crowdstrike.com/api-reference/operations/GetSearchStatusV1.md) entries in CrowdStrike's API reference. With `Read` alone, every telemetry query fails on its first call with `403 access denied, scope not permitted`.

Capsule never modifies devices, policies, prevention or response settings, detections, alerts, or any other object in your Falcon tenant. The only write operation it performs is creating a search job.

| Scope | Permission | Why Capsule needs it |
|  --- | --- | --- |
| **Hosts** | `Read` | Resolves host detail via `POST /devices/entities/devices/v2` - hostnames, OS version, agent version, last-seen user, IPs. Only devices that produced AI-related telemetry are looked up; Capsule never enumerates your fleet. |
| **NGSIEM** | `Read` and `Write` | Process-level AI discovery. Runs Next-Gen SIEM (CQL) aggregations against the `xdr` repository - `POST /humio/api/v1/repositories/xdr/queryjobs` to start a search (`Write`), `GET .../queryjobs/{id}` to collect its results (`Read`) - to detect local LLMs actually running, including models that never touch the network, AI coding agents and the processes they spawn, command lines, and skill usage. Requires Falcon Next-Gen SIEM on the tenant. |
| **Threatgraph** | `Read` | Network-derived AI discovery. Pivots a catalog of known AI / LLM / vibe-coding domains into the devices that contacted them (`GET /threatgraph/combined/ran-on/v1`), then resolves the process behind each connection (`GET /threatgraph/combined/{vertex-type}/summary/v1`). Runs on baseline Falcon Insight, so it is available on every tenant. |


> **`NGSIEM` is its own entry.** The API client screen also lists `NGSIEM Dashboards`, `NGSIEM Lookup Files`, `NGSIEM Saved Queries`, `NGSIEM Parsers` and `NGSIEM Data Connections API`. Those are separate scopes covering separate APIs; none of them grants search, and granting all of them does not substitute for the plain **`NGSIEM`** entry. Leave them unchecked.
**Do not see a plain `NGSIEM` entry?** On the tenants we have seen, it is offered only where Falcon Next-Gen SIEM is licensed - tenants without it show the `NGSIEM Dashboards` / `NGSIEM Lookup Files` entries but no plain `NGSIEM`. If that is what you see, grant the other scopes and continue: Capsule will run over Threatgraph with the coverage described in [Without Next-Gen SIEM](#without-next-gen-siem), and the licensing question goes to your CrowdStrike account team. There is nothing to change on the Capsule side. Tell us which `NGSIEM*` entries your console does list, so we can confirm.
Granting the scope is also not by itself sufficient. On a tenant where Next-Gen SIEM is not provisioned, the grant is accepted and calls still return `403 access denied, scope not permitted`; the 403 is identical either way, so it cannot tell you which of the two you are looking at.
**Try the scope before concluding you are not licensed.** Nothing visible elsewhere in the console reliably predicts whether telemetry queries will work - we have seen a tenant with no other sign of Next-Gen SIEM provisioning start returning results the moment `NGSIEM: Write` was added, and go back to `403` when it was removed. If you see a plain `NGSIEM` entry, grant `Read` and `Write` and let Capsule re-test; that answers the question in one step.


### Additional scopes to grant at setup

Grant these at the same time. Capsule does not read them yet - they back enrichments currently in development - but granting them now means the API client will not need to be edited again when those ship. All are **read-only**, and the integration installs and runs normally whether or not they are present.

| Scope | Permission | What it will enable |
|  --- | --- | --- |
| **Detections** | `Read` | Correlating discovered AI agents and local LLMs with existing Falcon EDR detections, so risky tools running on already-flagged hosts surface in Capsule's risk view. |
| **Alerts** | `Read` | Reading from Falcon's unified Alerts API - the modern superset of Detections that CrowdStrike is migrating tenants to - so correlation keeps working as tenants roll off the legacy endpoints. |
| **Apps** | `Read` | Falcon's installed-application inventory, so AI desktop apps (Cursor, Claude Desktop, ChatGPT, Ollama installers, Copilot extensions) can be discovered even when not actively running. |
| **Zero Trust Assessment** | `Read` | Per-device Zero Trust posture scores, so AI tools running on poorly-postured devices can be prioritized in Capsule's risk surfaces. |
| **Vulnerabilities** | `Read` | Falcon Spotlight CVE exposure per device, so an autonomous coding agent running on a critically-vulnerable host can be flagged accordingly. |
| **Identity Protection Entities** | `Read` | User-to-device mapping via Identity Protection's entities API, for accurate attribution on shared or multi-user devices. |


> **Some of these depend on modules you may not license.** `Vulnerabilities` (Spotlight), `Zero Trust Assessment` and `Identity Protection Entities` only appear in the API client UI when the corresponding Falcon module is licensed. If you do not see one, skip it - nothing in Capsule depends on it.


### Do NOT grant

For least-privilege, leave every other scope **disabled**. In particular Capsule does **not** require:

- `Hosts: Write` or `Real Time Response: Write/Admin` - the integration never modifies devices or runs RTR commands
- `Detections: Write` or `Alerts: Write` - Capsule reads detections only; it does not create, assign, or close them
- `NGSIEM Dashboards`, `NGSIEM Lookup Files`, `NGSIEM Saved Queries`, `NGSIEM Parsers`, `NGSIEM Data Connections API` - not used, and not a substitute for `NGSIEM`
- `Sensor Download` - not used
- `Falcon Container`, `IOA Rules`, `Custom IOA`, `Prevention Policies`, `Response Policies`, `Sensor Update Policies` - not used
- `User Management`, `Installation Tokens`, `API Integrations` - not used


### Security notes

- Store the Client Secret in a secrets manager. It cannot be retrieved from the Falcon console after the client is created.
- The Client ID alone is not sensitive, but it should still be treated as restricted information.
- If the secret is ever exposed, **revoke the API client** in the Falcon console and create a new one - there is no in-place rotate.
- Capsule stores the secret encrypted at rest. It is only used to call `/oauth2/token` to obtain short-lived (30-minute) bearer tokens.


## Step 2: Configure the Integration in Capsule

Once you have the **Client ID**, **Client Secret**, and **Cloud Region**, you can install the integration.

### Steps

1. Log in to the **Capsule Security** portal.
2. Click **Integrations** in the left sidebar.
3. Find the **CrowdStrike Falcon** card and click **Set up Integration**.
4. The setup modal asks for three values:
  - **Cloud Region** - select the region matching your Falcon tenant (`US-1`, `US-2`, `EU-1`, `US-GOV-1`, or `US-GOV-2`)
  - **Client ID** - paste the value from Step 1
  - **Client Secret** - paste the secret from Step 1
5. Click **Test connection**. Capsule performs an OAuth2 token exchange against your selected region and then calls the endpoints it will use during sync, so an API client that is missing a required scope fails here rather than after install. If a scope is missing, the error names it - grant it in the Falcon console and click **Test connection** again without re-entering your credentials.
6. Click **Save**.


### After setup

- Initial sync begins automatically.
- The first sync typically completes in **5–20 minutes** depending on host count and the size of the 30-day telemetry window Capsule queries.
- View synced devices in **Inventory → Devices**.
- View detected AI agents and local LLMs in **Discovery → Agents** and **Discovery → Models**.
- View vibe-coding app activity in **Inventory → Apps**.


## Feature Availability by Scope

The integration installs and runs with whichever scopes your API client has. Use this matrix to understand what you'll see in Capsule based on which Falcon modules your tenant has licensed.

| Capsule feature | Required Falcon scope(s) | Required Falcon module |
|  --- | --- | --- |
| **Device detail** (hostnames, OS, agent version, IPs, last-login user) for hosts with AI activity | `Hosts: Read` | Falcon Insight (any tier) |
| **AI activity discovered from network history** (devices that contacted known AI / LLM / vibe-coding domains, plus the process that initiated each connection) | `Threatgraph: Read` + `Hosts: Read` | Falcon Insight (any tier) |
| **Runtime local LLM detection** (Ollama, LM Studio, llama.cpp actively running - **including models that never call out**) | `NGSIEM: Read` + `NGSIEM: Write` | **Falcon Next-Gen SIEM** |
| **Runtime AI coding-agent detection** (Claude Code, Cursor, Cline, Copilot CLI, and the processes they spawn) | `NGSIEM: Read` + `NGSIEM: Write` | **Falcon Next-Gen SIEM** |
| **Full vibe-coding network telemetry** (complete DNS / connection history to Lovable, Replit, Bolt, Base44, etc., with counts over time) | `NGSIEM: Read` + `NGSIEM: Write` | **Falcon Next-Gen SIEM** |
| **Command-line detail and skill usage** | `NGSIEM: Read` + `NGSIEM: Write` | **Falcon Next-Gen SIEM** |


The scopes under [Additional scopes to grant at setup](#additional-scopes-to-grant-at-setup) do not yet drive anything in this matrix. Grant them so the enrichments they back can be switched on without a second API-client change.

### Without Next-Gen SIEM

If your tenant does not license Falcon Next-Gen SIEM, `Threatgraph: Read` still covers network-derived discovery. With it you get:

- ✅ Devices that contacted known AI / LLM / vibe-coding domains
- ✅ The process that initiated each of those connections
- ✅ Device detail and last-login user for those hosts
- ❌ **Nothing that makes no network calls** - a fully offline local LLM is invisible on this path
- ❌ No file events and no skill usage
- ❌ No command lines beyond the single initiating process, and no parent/child process chains
- ❌ Point-in-time observations rather than counts over a window


ThreatGraph is a **pivot, not an open query surface**: you can only ask about a domain or IP that Capsule already knows to look for, so anything outside its catalog cannot be discovered on this path.

> `Threatgraph: Read` is what provides all of the above. Without it, and without `NGSIEM`, Capsule syncs device inventory only - no AI agents, models, or app activity.


To enable full runtime discovery, work with your CrowdStrike account team to add Falcon Next-Gen SIEM, then update the API client to grant `NGSIEM: Read` and `NGSIEM: Write` - no other reconfiguration is needed.

## Troubleshooting

### `401 Unauthorized` on token exchange

- The Client ID or Client Secret is wrong, or the API client has been deleted/disabled in the Falcon console.
- Confirm the **Cloud Region** matches the cloud where the API client was created - credentials are not portable across regions.


### `403 Forbidden` / `access denied, scope not permitted` on Hosts, NGSIEM, or ThreatGraph

- The API client is missing that scope. Re-open the client in **Support and resources → API clients and keys** and confirm **Hosts: Read**, **Threatgraph: Read**, and - where Next-Gen SIEM is licensed - **both `NGSIEM: Read` and `NGSIEM: Write`** are checked.
- **`NGSIEM: Read` alone produces this 403.** Starting a search is the write operation (`StartSearchV1` is gated under `NGSIEM: WRITE`), so a client with only `Read` fails on the very first telemetry call, before any results exist to read. Editing scopes on an existing client preserves the Client ID and secret, so nothing needs to be re-shared with Capsule.
- **An NGSIEM 403 tells you nothing about the repository.** The Falcon API gateway enforces scope *before* it resolves the repository name, so a wrong or non-existent repo returns exactly the same `403 access denied, scope not permitted`. Do not chase the repository name on a 403.
- **A 403 cannot distinguish "Next-Gen SIEM not licensed" from "licensed, scope not granted."** Both return identical responses. If no plain `NGSIEM` scope is offered in the API client at all, that points at the module not being licensed - a conversation with your CrowdStrike account team rather than a configuration change - but tell us which `NGSIEM*` entries you *do* see, because that listing separates the two cases far more reliably than the 403 does.
- **Symptom worth knowing:** when *both* NGSIEM and ThreatGraph are denied, syncs still complete successfully while discovering nothing, and inventory already in Capsule stays visible as it goes stale. An integration that looks healthy while its data stops advancing is the signature of this state.
- A `403` on `Detections`, `Alerts`, `Apps`, `Zero Trust Assessment`, `Vulnerabilities` or `Identity Protection Entities` does not affect the integration - nothing in Capsule reads those APIs yet.


### `Unsupported CrowdStrike Falcon cloud region`

- The region selector in Capsule must be one of `us-1`, `us-2`, `eu-1`, `us-gov-1`, or `us-gov-2`. Custom or commercial-preview regions are not supported.


### `LogScale query failed: 404` on the `xdr` repository

- The scope is granted but the repository is not there: either Next-Gen SIEM is not provisioned, or your tenant uses a non-default repository name. Contact Capsule support if it is non-default. Note this `404` is only reachable *once `NGSIEM: Write` has been granted* - before that the gateway answers `403` instead (see above).
- Network-derived discovery continues to work in this state provided `Threatgraph: Read` is granted - see [Without Next-Gen SIEM](#without-next-gen-siem) for what it does and does not cover.


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your tenant ID, integration status, cloud region, and any error messages from the Capsule portal


For CrowdStrike API client or scope issues:

- **Falcon Console**: **Support and resources → CrowdStrike technical support**
- **Include**: Your CID (Customer ID), API client name, and the scope you are trying to enable