detects

CrowdStrike FalconPy
CrowdStrike FalconPy

CrowdStrike Subreddit

Detects examples

The examples in this folder focus on leveraging CrowdStrike's Detects API to interact with alerts generated by the CrowdStrike Falcon sensor.

Detects Advisor

This solution provides a simple example utility for triaging detections. Returned lists of detections can be customized by passing a FQL filter. Results are displayed to the console or dumped to a JSON save file. Console displays can be sorted based upon available display fields.

More detail regarding specific detections can be retrieved by specifying the detection ID.

Detection status and visibility can be adjusted and detections can be assigned to a specified UID. (Email address of a user already existing within your Falcon tenant.)

Multiple detections can be updated simultaneously.

Running the program

In order to run this demonstration, you will need access to CrowdStrike API keys with the following scopes:

Service Collection
Scope

Detects

READ, WRITE

User Management

READ

Execution syntax

This demonstration was developed to leverage easy to use command-line arguments to perform simple triage tasks with detections.

Command line arguments

This program accepts the following command line arguments.

Argument
Long Argument
Description

-h

--help

Display command line help and exit

-k FALCON_CLIENT_ID

--falcon_client_id FALCON_CLIENT_ID

CrowdStrike Falcon API Client ID

-s FALCON_CLIENT_SECRET

--falcon_client_secret FALCON_CLIENT_SECRET

CrowdStrike Falcon API Client Secret

-c COMMAND

--command COMMAND

Command to perform, one of: list or view.

-t TABLE_FORMAT

--table_format TABLE_FORMAT

Table format to use for display, one of: plain, simple, github, grid, fancy_grid, pipe, orgtbl, jira, presto, pretty, psql, rst, mediawiki, moinmoin, youtrack, html, unsafehtml, latext, latex_raw, latex_booktabs, latex_longtable, textile, or tsv.

-f FILTER

--filter FILTER

FQL filter to use to filter detections

-o SORT

--sort SORT

Field to sort by, one of: id, device_id, status, hostname, tactic, technique, or first_occurrence Defaults to first_occurrence (asc)

-r

--reverse

Reverses the sort order

-l LIMIT

--limit LIMIT

Total number of detections to return. (Max: 1000)

-n

--no_color

Disable color output in result displays

-i DETECTION_ID

--detection_id DETECTION_ID

Detection ID(s) to review or update (supports up to 20 IDs in comma-delimited format)

-a ASSIGN

--assign ASSIGN

UID (email address) of the user to assign the detection

-u UPDATE_STATUS

--update_status UPDATE_STATUS

Status to set for the detection, one of: new, in_progress, true_positive, false_positive, ignored, closed, or reopened

-x

--hide

Hide this detection from the Falcon console

-v

--show

Show this detection from the Falcon console

-d

--dump_to_file

Export results to a file. (JSON format) Exported results contain more complete data than results rendered to the terminal.

-q

--fql_help

Display extended filtering documentation

Basic usage

The only required command line arguments are -k (CrowdStrike Falcon API Client ID) and -s (CrowdStrike Falcon API Client Secret).

The default command is "list" with no filters specified, sorting by first behavior occurrence.

Example

Example result

Dumping results to a file

Detection listings may be dumped to a file using the -d argument.

File format will be in JSON format and can be massaged by leveraging the filtering argument described below. This file will be saved to the same folder the program is executed from and will follow the naming convention of YYYY-MM-DD_detects.json

Filters

Filters can be provided using the -f argument, allowing you to reduce the number of results returned and filter down to just the records of interest to you. Filtering will impact results shown to the console and results dumped to output files. All detection filters supported by FalconPy are available for use here.

Wildcards are supported but will need to specify an asterisk before the first single quote. (See Will work example below.)

Important‼️ You must pass your filter string within double-quotes in most scenarios, as the single-quotes used to specify strings are dropped when they are not provided.

Will not work

Will work

Sorting results

You can sort results for tabular console displays by using the -o argument.

Results can be sorted by any of the following columns:

Column
Field

id

Detection ID

device_id

Device AID

status

Detection status

hostname

Device Hostname

tactic

Behavior Tactic

technique

Behavior Technique

first_occurrence

First behavior timestamp

Sort order can be reversed using the -r argument.

Limiting results

Results can be farther reduced by using the -l argument to pass a limit value.

The maximum limit value allowed is 1000. Can be provided as an integer or a string.

Viewing detection detail

Extended detail for detections can be retrieved by specifying the detection ID using the -i argument.

Multiple IDs can be specified by delimiting with comma (ID1,ID2,ID3). A maximum of 20 IDs may be specified in this manner.

Any operation that is specific to a detection will need to include this argument (assign, update, etc.).

Passing a command line of just -i is the equivalent of passing -c view -i.

Example

Example result

Assigning detections

Using the -a argument will allow you to assign the detection to the UID you provide. Typically this is an email address and must match an existing user within your Falcon tenant. Once provided, this value is used to retrieve the UUID for the user account, which is then assigned to the detection.

You must provide a detection ID using the -i argument in order to assign a detection to a user.

Changing detection status

The status of a detection can be changed using the -u argument.

You may only change status to one of the following allowed values:

Value
Status

new

New

in_progress

In Progress

true_positive

True Positive

false_positive

False Positive

ignored

Ignored

closed

Closed

reopened

Reopened

You must provide a detection ID using the -i argument in order to change status.

Changing detection visibility

Detection visibility can be changed using the -x (hide) and the -v (show) arguments.

You will be asked to confirm if you select to hide a detection.

You must provide a detection ID using the -i argument in order to change visibility.

Once hidden from the console, detections cannot be retrieved using standard lookups. You will have to contact support with the detection ID (provided when hidden) in order to restore this record to your tenant.

Update chaining

Multiple updates may be performed against multiple detections simultaneously as long as provided command line parameters make sense for all operations requested.

Example

Result

Turning off console color output

Console colors can be disable by passing the -n argument.

This argument can be mixed with any other arguments.

Changing table formatting

The table format for listing displays can be adjusted by using the -t argument.

Any of the following table formats are supported:

  • plain

  • simple

  • github

  • grid

  • fancy_grid (Default)

  • pipe

  • orgtbl

  • jira

  • presto

  • pretty

  • psql

  • rst

  • mediawiki

  • moinmoin

  • youtrack

  • html

  • unsafehtml

  • latext

  • latex_raw

  • latex_booktabs

  • latex_longtable

  • textile

  • tsv

Command-line help

Command-line help is available via the -h argument.

This content may be easier to review when piped thru more or less.

python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -h | less

Filtering Help

Extended filtering documentation is provided when you use the -q argument.

This content may be easier to review when piped thru more or less.

python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -q | less

Example source code

Source code for this example can be found here.

Previouscustom_ioaNextdiscover

Last updated

Was this helpful?