crowdstrike.falcon.ngsiem_search module – Execute searches against CrowdStrike Next-Gen SIEM repositories
Note
This module is part of the crowdstrike.falcon collection (version 4.9.1).
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install crowdstrike.falcon.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: crowdstrike.falcon.ngsiem_search.
New in crowdstrike.falcon 4.10.0
Synopsis
Execute CQL (CrowdStrike Query Language) searches against Next-Gen SIEM repositories.
Provides asynchronous job-based searching with automatic polling for results.
Can correlate network connections with process data for incident response.
Supports all available repositories including search-all, investigate_view, and others.
Jobs automatically timeout after 90 seconds of inactivity to prevent resource waste.
Requirements
The below requirements are needed on the host that executes this module.
NGSIEM [READ, WRITE] API scope
crowdstrike-falconpy >= 1.3.0
python >= 3.6
Parameters
Parameter |
Comments |
|---|---|
Dictionary of arguments for variables specified in queries with Values must be simple strings. Explicit values in query like |
|
The registered result of the crowdstrike.falcon.auth module, or a dictionary containing the access_token and cloud keys. If provided, the client_id, client_secret, member_cid, and cloud options are ignored. Useful when needing to make multiple API calls to avoid rate limiting issues. |
|
The OAuth2 access token to use for authentication. |
|
The CrowdStrike cloud region to use. This can differ from the module’s cloud argument due to autodiscovery. |
|
The CrowdStrike API client ID to use. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike API secret that corresponds to the client ID. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike cloud region to use. All clouds are automatically discovered if not specified, except for the The Choices:
|
|
Ending point for search results based on event timestamp. Can use relative time like If start is provided, end must be greater than or equal to start. |
|
Extended headers that are prepended to the default headers dictionary. |
|
The CrowdStrike member CID for MSSP authentication. See the Falcon documentation for more information about API clients. The |
|
Interval in seconds between status checks while waiting for results. Must be at least 5 seconds to avoid rate limiting. Should not exceed 90 seconds to prevent job timeout. Default: |
|
The CQL query to execute against the repository. Use CrowdStrike Query Language syntax for filtering and correlation. Double quotes and backslashes must be escaped in the query string. Can include variables using |
|
The repository to search against.
Choices:
|
|
Starting point for search results based on event timestamp. Can use relative time like If end is provided, start must be less than or equal to end. |
|
Maximum time in seconds to wait for query completion. Query will be canceled if it exceeds this timeout. Set to 0 to disable timeout (use with caution for long-running queries). Default: |
|
Custom User-Agent string to use for requests to the API. The user agent string is prepended to the default user agent string ( See RFC 7231 for more information. The |
Examples
- name: Search for all logs from a specific agent ID in the last 24 hours
crowdstrike.falcon.ngsiem_search:
query_string: "aid=abc123"
start: "1d"
end: "now"
- name: Find processes that initiated connections to a specific IP
crowdstrike.falcon.ngsiem_search:
repository: "investigate_view"
query_string: |
#event_simpleName=ProcessRollup2 ImageFileName=?process_name
| join({{ '{' }}#event_simpleName=NetworkConnectIP4{{ '}' }},
key=ContextProcessId, field=TargetProcessId,
include=[RemoteAddressIP4, RemotePort])
| table([ImageFileName, CommandLine, ParentProcessId, RemoteAddressIP4, RemotePort])
arguments:
process_name: "*"
start: "24h"
- name: Search for network connections between specific IPs
crowdstrike.falcon.ngsiem_search:
query_string: |
#event_simpleName=NetworkConnectIP4 LocalAddressIP4=?source_ip RemoteAddressIP4=?dest_ip
| table([ImageFileName, CommandLine, LocalAddressIP4, RemoteAddressIP4, RemotePort])
arguments:
source_ip: "10.1.1.100"
dest_ip: "192.168.1.50"
timeout: 600
- name: Find authentication events in the last hour
crowdstrike.falcon.ngsiem_search:
repository: "search-all"
query_string: |
#event_simpleName=UserLogon
| head(25)
| table([ComputerName, UserName, LogonType, aid])
start: "1h"
poll_interval: 5
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Whether the query was cancelled before completion. Returned: always Sample: |
|
Whether the query completed successfully. Returned: always Sample: |
|
List of events found by the search query. Returned: success Sample: |
|
Time taken to execute the query in seconds. Returned: success Sample: |
|
The ID of the executed query job. Returned: always Sample: |
|
Total number of events returned by the search. Returned: success Sample: |