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

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:

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)

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

Example request:

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'].