# Falcon Query Language

Falcon Query Language (FQL) is the filtering engine used across the CrowdStrike Falcon API. It allows you to query specific data sets—such as hosts, detections, incidents, and vulnerabilities—by applying precise criteria directly at the API level.

For users of our automation platform, using FQL is the most efficient way to reduce data overhead and ensure your workflows only trigger on the exact events you care about.

## 1. Core Syntax

The standard FQL expression follows a **property-operator-value** pattern:

`property_name:operator'value'`

- **Property**: The specific metadata field (e.g., `status`, `hostname`).
- **Operator**: Defines the comparison (e.g., equals, greater than).
- **Value**: The data to match against.

### Key Rules

- **Strings**: Must be enclosed in single quotes: `hostname:'SEC-PROD-01'`.
- **Booleans**: Must be lowercase without quotes: `is_active:true`.
- **Integers**: No quotes required: `confidence:>80`.
- **Dates**: Must be UTC ISO-8601 format in single quotes: `last_seen:>'2024-01-01T00:00:00Z'`.
- **Nulls**: Use the literal `null`: `external_id:null`.

## 2. Operators

FQL supports a robust set of operators for different data types.

| **Operator** | **Meaning**                                  | **Example**                          |
| ------------ | -------------------------------------------- | ------------------------------------ |
| `:`          | **Equals** (Standard Match)                  | `status:'closed'`                    |
| `!:`         | **Not Equals**                               | `platform_name!:'Linux'`             |
| `>`          | **Greater Than**                             | `severity_score:>70`                 |
| `<`          | **Less Than**                                | `limit:<10`                          |
| `>=` / `<=`  | **Greater/Less Than or Equal**               | `last_seen:>='2023-12-01T00:00:00Z'` |
| `~`          | **Text Match** (Case-insensitive, tokenized) | `description:~'suspicious'`          |
| `!~`         | **Does Not Text Match**                      | `command_line!~'powershell'`         |
| `*`          | **Wildcard** (Starts with / Ends with)       | `hostname:'PROD-*'`                  |

## 3. Logical Expressions

You can chain multiple filters together to create complex logic.

### AND (Represented by `+`)

Both conditions must be met.

- **Example**: `platform_name:'Windows'+status:'normal'`
- _Finds Windows hosts that are currently in a normal state._

### OR (Represented by `,`)

Either condition can be met.

- **Example**: `severity_name:'High',severity_name:'Critical'`
- _Finds detections that are either High OR Critical._

### Grouping (Parentheses)

Use `()` to define the order of operations, especially when mixing AND and OR logic.

- **Example**: `platform_name:'Linux',(tags:'Production'+tags:'Web')`
- _Finds Linux hosts that have both the Production and Web tags._

---

## 4. Practical Implementation & Examples

### A. Host Management (Falcon Discover / Hosts)

**Endpoint:** `GET /devices/queries/devices/v1`

**Goal:** Find all Windows Servers that haven't been seen in the last 30 days.

## FQL Filter

`platform_name:'Windows'+product_type_desc:'Server'+last_seen:<'2024-01-15T00:00:00Z'`

## Example request

```bash
GET /devices/queries/devices/v1?filter=platform_name%3A'Windows'%2Bproduct_type_desc%3A'Server'%2Blast_seen%3A%3C'2024-01-01T00:00:00Z' HTTP/1.1
Host: [api.crowdstrike.com](http://api.crowdstrike.com/)
Authorization: Bearer `<YOUR_ACCESS_TOKEN>`
```

### B. Detections Triage

**Endpoint:** `GET /detects/queries/detects/v1`

**Goal:** Retrieve specific High/Critical detections that are still "New" and involve "Credential Access".

## FQL Filter (2)

`status:'new',max_severity_displayname:['High','Critical']+tactic_id:'T1003'`

Example request:

```bash
GET /detects/queries/detects/v1?filter=status%3A'new'%2B(max_severity_displayname%3A'High'%2Cmax_severity_displayname%3A'Critical')%2Bbehaviors.tactic_id%3A'T1003' HTTP/1.1
Host: [api.crowdstrike.com](http://api.crowdstrike.com/)
Authorization: Bearer `<YOUR_ACCESS_TOKEN>`
```

### C. Vulnerability Management (Spotlight)

**Endpoint:** `GET /spotlight/queries/vulnerabilities/v1`

**Goal:** Find open vulnerabilities with a CVSS score higher than 9.0.

## FQL Filter (3)

```json
status:'open'+cve.cvss_v3_base_score:>9.0
```

Example request:

```bash
POST /spotlight/queries/vulnerabilities/v1 HTTP/1.1
Host: [api.crowdstrike.com](http://api.crowdstrike.com/)
Content-Type: application/json
Authorization: Bearer `<YOUR_ACCESS_TOKEN>`

{
"filter": "status:'open'+cve.cvss_v3_base_score:>9.0",
"limit": 50,
"sort": "updated_timestamp.desc"
}
```

## 5. Sorting with FQL

Many endpoints also support a `sort` parameter using FQL syntax.

- **Syntax**: `property_name.asc` or `property_name.desc`
- **Example**: `last_seen.desc` (Shows the most recently active devices first).

## 6. Common Use Cases

| **Objective**                | **FQL String**                                        |
| ---------------------------- | ----------------------------------------------------- |
| **Inactive Hosts**           | `last_seen:<'2023-10-01T00:00:00Z'+status!:'removed'` |
| **High Severity Incidents**  | `status:'open'+(severity:4,severity:5)`               |
| **Naming Convention Search** | `hostname:'*-WEB-*'+platform_name:'Windows'`          |
| **Exclude Specific Tags**    | `tags!:'SensorGrouping/Development'`                  |

## 7. Pro-Tips for Automation Users

1. **URL Encoding**: If you are making raw HTTP requests, remember that `+` (AND) and `:` (Equals) must be URL encoded (e.g., `+` becomes `%2B`).
2. **Case Sensitivity**: While property names are generally lowercase, **values** within single quotes can be case-sensitive depending on the specific API (e.g., `status:'new'` vs `status:'New'`). Always check the specific endpoint documentation.
3. **Substring Match**: To find a string anywhere in a field, use the asterisk on both sides: `hostname:*'test'*`.
4. **Exact Match**: Use square brackets `[]` for an exact match within a list of possible values: `status:['new', 'in_progress']`.