detects
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 - Triage CrowdStrike Falcon detections
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:
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.
-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
python3 detects_advisor.py -k CLIENT_ID_HERE -s CLIENT_SECRET_HEREExample result
_____ __ __ __
| \.-----.| |_.-----.----.| |_|__|.-----.-----.-----.
| -- | -__|| _| -__| __|| _| || _ | |__ --|
|_____/|_____||____|_____|____||____|__||_____|__|__|_____|
╒════════════════╤════════════════════════════════════════════╤════════════════════════════════╤════════════════════════════════════════════════╤══════════════════════╕
│ Detection │ Hostname / Agent ID │ Tactic │ Technique │ Date occurred │
╞════════════════╪════════════════════════════════════════════╪════════════════════════════════╪════════════════════════════════════════════════╪══════════════════════╡
│ New │ example-host-one │ Custom Intelligence (CSTA0005) │ Indicator of Attack (CST0004) │ 2021-11-23T19:28:48Z │
│ 1272629 │ 12345abc67890de1234fabc5678901de │ │ │ │
├────────────────┼────────────────────────────────────────────┼────────────────────────────────┼────────────────────────────────────────────────┼──────────────────────┤
│ New │ example-host-two │ Defense Evasion (TA0005) │ Masquerading (T1036) │ 2021-12-15T02:33:44Z │
│ 12885047810 │ 1a2bcde34f5a6b789012cd3ef456a7n8 │ │ │ │
├────────────────┼────────────────────────────────────────────┼────────────────────────────────┼────────────────────────────────────────────────┼──────────────────────┤
│ New │ example-host-three │ Execution (TA0002) │ Command and Scripting Interpreter (T1059) │ 2022-01-20T23:19:27Z │
│ 94506534975 │ abc1defabc2d345efa6789012b3456c7 │ Command and Control (TA0011) │ Remote Access Software (T1219) │ 2022-01-20T23:24:30Z │
│ Responder Name │ │ Persistence (TA0003) │ Web Shell (T1505.003) │ 2022-01-20T23:30:30Z │
│ │ │ Command and Control (TA0011) │ Remote Access Software (T1219) │ 2022-01-20T23:30:33Z │
│ │ │ Command and Control (TA0011) │ Remote Access Software (T1219) │ 2022-01-20T23:32:33Z │
│ │ │ Execution (TA0002) │ Command and Scripting Interpreter (T1059) │ 2022-01-20T23:34:42Z │
│ │ │ Execution (TA0002) │ Command and Scripting Interpreter (T1059) │ 2022-01-20T23:37:46Z │
│ │ │ Persistence (TA0003) │ Web Shell (T1505.003) │ 2022-01-20T23:43:49Z │
│ │ │ Command and Control (TA0011) │ Remote Access Software (T1219) │ 2022-01-20T23:43:52Z │
├────────────────┼────────────────────────────────────────────┼────────────────────────────────┼────────────────────────────────────────────────┼──────────────────────┤
│ New │ example-host-three │ Defense Evasion (TA0005) │ Masquerading (T1036) │ 2022-01-20T23:47:52Z │
│ 94521823901 │ abc1defabc2d345efa6789012b3456c7 │ │ │ │
│ Responder Name │ │ │ │ │
├────────────────┼────────────────────────────────────────────┼────────────────────────────────┼────────────────────────────────────────────────┼──────────────────────┤
│ New │ example-host-three │ Machine Learning (CSTA0004) │ Sensor-based ML (CST0007) │ 2022-01-20T23:59:55Z │
│ 94524346061 │ abc1defabc2d345efa6789012b3456c7 │ │ │ │
╘════════════════╧════════════════════════════════════════════╧════════════════════════════════╧════════════════════════════════════════════════╧══════════════════════╛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
python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -f device.hostname:*'*search-string*'Will work
python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -f "device.hostname:*'*search-string*'"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:
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
-iis the equivalent of passing-c view -i.
Example
detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -i 94524346061Example result
_____ __ __ __
| \.-----.| |_.-----.----.| |_|__|.-----.-----.
| -- | -__|| _| -__| __|| _| || _ | |
|_____/|_____||____|_____|____||____|__||_____|__|__|
_______
| __|.--.--.--------.--------.---.-.----.--.--.
|__ || | | | | _ | _| | |
|_______||_____|__|__|__|__|__|__|___._|__| |___ |
|_____|
Detection: ldt:abc1defabc2d345efa6789012b3456c7:94524346061
Status: New
Assigned to: Responder name
Hostname: example-host-three
Agent ID: abc1defabc2d345efa6789012b3456c7
Agent version: 6.33.13005.0
Platform: Linux (CentOS 8)
External IP: 76.111.222.123
Local IP: 192.168.2.42
______ __ __
| __ \.-----.| |--.---.-.--.--.|__|.-----.----.-----.
| __ <| -__|| | _ | | || || _ | _|__ --|
|______/|_____||__|__|___._|\___/ |__||_____|__| |_____|
Tactic: Machine Learning (CSTA0004)
Technique: Sensor-based ML (CST0007)
Occurred: 2022-01-20 at 23:59:55
════════════════════════════════════════════════════════════════════════
This file meets the machine learning-based on-sensor AV protection's
medium confidence threshold for malicious files.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:
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
python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -i ID1,ID2,ID3 -a [email protected] -u in_progress -vResult
Detection ID1 set to visible.
Detection ID2 set to visible.
Detection ID3 set to visible.
Changed ID1 status to In Progress.
Changed ID2 status to In Progress.
Changed ID3 status to In Progress.
Detection ID1 assigned to [email protected].
Detection ID2 assigned to [email protected].
Detection ID3 assigned to [email protected].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:
plainsimplegithubgridfancy_grid(Default)pipeorgtbljiraprestoprettypsqlrstmediawikimoinmoinyoutrackhtmlunsafehtmllatextlatex_rawlatex_booktabslatex_longtabletextiletsv
Command-line help
Command-line help is available via the -h argument.
This content may be easier to review when piped thru
moreorless.
python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -h | less
CrowdStrike Falcon Detects Advisor utility.
@@@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@ @@@@@@
@@@@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@@ @@@@@@@@ @@@@@@@ @@@@@@@
@@! @@@ @@! @@! @@! !@@ @@! !@@
!@! @!@ !@! !@! !@! !@! !@! !@!
@!@ !@! @!!!:! @!! @!!!:! !@! @!! !!@@!!
!@! !!! !!!!!: !!! !!!!!: !!! !!! !!@!!!
!!: !!! !!: !!: !!: :!! !!: !:!
:!: !:! :!: :!: :!: :!: :!: !:!
:::: :: :: :::: :: :: :::: ::: ::: :: :::: ::
:: : : : :: :: : : :: :: :: :: : : :: : :
,
/'/ /'
/' / /'
,/' / _____,/'. , O ____ ____ ____
/`--,/ /' /' | / /' /' )--/' )--)' )--
/' / /' /' | /' /' '---, /' /' /'
(,/' (_,(___,/(__ _|/(__(__(___,/ (___,/' /'
CrowdStrike FalconPy v1.0
02.12.22 - jshcodes@CrowdStrike
This utility returns a list of a detections, which can be customized
by passing a FQL filter (-f) when executed. Results are displayed to
the console or dumped (-d) to a JSON save file. Console displays can
be sorted based upon available display fields. (-o, -r)
More detail regarding specific detections can be retrieved by
specifying the detection ID with the -i argument.
Detection status (-u) and visibility (-x, -v) can be adjusted and
detections can be assigned (-a) to a specified UID. (Email address
of a user already existing within your Falcon tenant.)
Several updates can be performed against multiple detections
simultaneously.
Use the --no-color (-n) argument to disable color console output.
Use the --table_fmt (-t) argument to adjust list display formatting.
optional arguments:
-h, --help show this help message 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, update, 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 Reverse the sort order
-l LIMIT, --limit LIMIT
Total number of detections to display (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 (comma-delimited)
A maximum of 20 IDs may be specified
-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 in 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 documentationFiltering Help
Extended filtering documentation is provided when you use the -q argument.
This content may be easier to review when piped thru
moreorless.
python3 detects_advisor.py -k CLIENT_ID -s CLIENT_SECRET -q | less
_______ _______ ___ ___ ___ __
| _ | _ | | | Y .-----| .-----.
|. 1___|. | |. | |. 1 | -__| | _ |
|. __) |. | |. |___ |. _ |_____|__| __|
|: | |: 1 |: 1 | |: | | |__|
|::.| |::.. |::.. . | |::.|:. |
`---' `----|:.`-------' `--- ---'
`--'
FQL Documentation: https://falconpy.io/Usage/Falcon-Query-Language.html
FILTERS
Filter options are broken out into four categories:
General, Behavioral, Devices and Miscellaneous
Include all provided FQL filters in double quotes in order to preserve formatting!
Wildcards may be used but should also position an asterisk before the first quote.
Example: -f "device.hostname:*'*search-string*'"
General
Example: -f "status:'in_progress'"
adversary_ids date_updated last_behavior max_severity_displayname
assigned_to_name detection_id max_confidence seconds_to_resolved
cid first_behavior max_severity seconds_to_triaged
status
Behavioral - behaviors.filter
Example: -f "behaviors.tactic:'Execution'"
alleged_filetype md5 sha256
behavior_id objective tactic
cmdline parent_details.parent_cmdline technique
confidence parent_details.parent_md5 timestamp
contral_graph_id parent_details.parent_process_id triggering_process_id
device_id parent_details.parent_process_graph_id triggering_process_graph_id
filename parent_details.parent_sha256 user_id
ioc_source pattern_disposition user_name
ioc_type scenario
ioc_value severity
Devices - device.filter
Example: -f "device.platform_name:'Linux'"
agent_load_flags first_seen platform_name
agent_local_time hostname product_type
agent_version last_seen product_type_desc
bios_manufacturer local_ip release_group
bios_version mac_address reduced_functionality_mode
cid machine_domain serial_number
config_id_base major_version site_name
config_id_build minor_version status
config_id_platform modified_timestamp system_product_name
cpu_signature os_version system_manufacturer
device_id ou
external_ip platform_id
Miscellaneous
Example: -f "hostinfo.domain:*'*search-string*'"
hostinfo.domain quarantined_files.id
hostinfo.active_directory_dn_display quarantined_files.paths
quarantined_files.sha256 quarantined_files.stateExample source code
Source code for this example can be found here.
Last updated
Was this helpful?