workflows

Workflows examples

The examples within this folder focus on leveraging CrowdStrike's Falcon Falcon Fusion SOAR API.

Workflow Manager (Terminal version)

This sample demonstrates how to leverage the Workflows API to provide the following functionality:

List all workflows
Execute a workflow
List all executions for a workflow
Print the results of a workflow execution
Import a workflow
Export a workflow

Running the program

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

Service Collection

Scope

Workflows

READ, WRITE

Required packages

In order to run this sample, you will need to have the tabulate and termcolor packages installed.

Execution syntax

This sample leverages simple command-line arguments to implement functionality.

Basic usage

Execute the default example. This will default to listing all workflows discovered in tabular format.

python3 workflow_manager.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET

[!TIP] This sample supports Environment Authentication, meaning you can execute any of the command lines shown below without providing credentials if you have the values FALCON_CLIENT_ID and FALCON_CLIENT_SECRET defined in your environment.

python3 workflow_manager.py

Change the CrowdStrike region with the -b argument.

python3 workflow_manager.py -b usgov1

Execute a workflow using a custom payload.

python3 workflow_manager.py -e -i $WORKFLOW_DEFINITION_ID -p {'key': 'value'}

List all executions of a workflow using the -le argument.

python3 workflow_manager.py -le -i $WORKFLOW_DEFINITION_ID

Retrieve the results of an execution with the -g argument.

python3 workflow_manager.py -g -i $WORKFLOW_EXECUTION_ID

Export a workflow to a local YAML file using the -ex argument.

python3 workflow_manager.py -ex $EXPORT_FILENAME -i $WORKFLOW_DEFINITION_ID

[!NOTE] Exporting to an existing file will overwrite it's contents.

Import a workflow from a local YAML file using the -im argument.

python3 workflow_manager.py -im $IMPORT_FILENAME

[!NOTE] If the workflow name defined within your workflow YAML file exists within your tenant, an error will be thrown. Use the -n argument to import this file as a new workflow with a new name.

python3 workflow_manager.py -im $IMPORT_FILENAME -n $WORKFLOW_NEW_NAME

[!TIP] You can validate this workflow import without saving by providing the -v argument with the above command.

python3 workflow_manager.py -im $IMPORT_FILENAME -n $WORKFLOW_NEW_NAME -v

API debugging can be enabled using the -d argument.

python3 workflow_manager.py -d

Adjust the output table format using the -t argument.

python3 workflow_manager.py -l -t fancy_grid

Swap to JSON output with the -j argument.

python3 workflow_manager.py -l -j

Command-line help

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

usage: workflow_manager.py [-h] [-d] [-i ID] [-p PAYLOAD] [-e] [-g] [-l] [-le] [-ex EXPORT_WORKFLOW] [-im IMPORT_WORKFLOW] [-n WORKFLOW_NAME] [-v] [-j] [-t TABLE_FORMAT] [-k CLIENT_ID]
                           [-s CLIENT_SECRET] [-b BASE_URL]

Falcon Fusion SOAR workflow manager.

 _______                        __ _______ __        __ __
|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
|:  1   |                         |:  1   |
|::.. . |   CROWDSTRIKE FALCON    |::.. . |    FalconPy
`-------'                         `-------'

 ██       ██                 ██       ████  ██
░██      ░██                ░██      ░██░  ░██
░██   █  ░██  ██████  ██████░██  ██ ██████ ░██  ██████  ███     ██
░██  ███ ░██ ██░░░░██░░██░░█░██ ██ ░░░██░  ░██ ██░░░░██░░██  █ ░██
░██ ██░██░██░██   ░██ ░██ ░ ░████    ░██   ░██░██   ░██ ░██ ███░██
░████ ░░████░██   ░██ ░██   ░██░██   ░██   ░██░██   ░██ ░████░████
░██░   ░░░██░░██████ ░███   ░██░░██  ░██   ███░░██████  ███░ ░░░██
░░       ░░  ░░░░░░  ░░░    ░░  ░░   ░░   ░░░  ░░░░░░  ░░░    ░░░
 ████     ████
░██░██   ██░██                               █████
░██░░██ ██ ░██  ██████   ███████   ██████   ██░░░██  █████  ██████
░██ ░░███  ░██ ░░░░░░██ ░░██░░░██ ░░░░░░██ ░██  ░██ ██░░░██░░██░░█
░██  ░░█   ░██  ███████  ░██  ░██  ███████ ░░██████░███████ ░██ ░
░██   ░    ░██ ██░░░░██  ░██  ░██ ██░░░░██  ░░░░░██░██░░░░  ░██
░██        ░██░░████████ ███  ░██░░████████  █████ ░░██████░███
░░         ░░  ░░░░░░░░ ░░░   ░░  ░░░░░░░░  ░░░░░   ░░░░░░ ░░░

This sample demonstrates how to leverage the Workflows API to provide
the following functionality:
  - List all workflows                            (-l or --list-workflows)
  - Execute a workflow                            (-e or --execute)
  - List all executions for a workflow            (-le or --list-executions)
  - Print the results of a workflow execution     (-g or --get_result)
  - Import a workflow                             (-im {FILENAME} or --import-workflow {FILENAME})
  - Export a workflow                             (-ex {FILENAME} or --export-workflow {FILENAME})

Creation date: 11.06.2024 - jlangdev@CrowdStrike
Modification date: 11.08.2024 - jshcodes@CrowdStrike

This sample requires the following packages:
- crowdstrike-falconpy >= 1.4.1
- tabulate
- termcolor

options:
  -h, --help            show this help message and exit
  -d, --debug           Activate API debugging

workflow arguments:
  -i, --id ID           Workflow definition or execution ID
  -p, --payload PAYLOAD
                        Workflow execution payload

command arguments:
  -e, --execute         Execute the workflow specified
  -g, --get-result      Retrieve a workflow execution result
  -l, --list-workflows  List all workflows
  -le, --list-executions
                        List the executions for the workflow specified
  -ex, --export-workflow EXPORT_WORKFLOW
                        Export a workflow to a local file.
                        Provide a filename for this argument. Example: 'exported.yml'
  -im, --import-workflow IMPORT_WORKFLOW
                        Import a workflow from a local file.
                        Provide a filename for this argument. Example: 'to_import.yml'
  -n, --workflow-name WORKFLOW_NAME
                        Name for the imported workflow
  -v, --validate-only   Validate the workflow only, do not save upon import

formatting arguments:
  -j, --json            Display execution results in JSON format
  -t, --table-format TABLE_FORMAT
                        Tabular display format

authentication arguments (environment authentication supported):
  -k, --falcon-client-id CLIENT_ID
                        CrowdStrike Falcon API ID
  -s, --falcon-client-secret CLIENT_SECRET
                        CrowdStrike Falcon API secret
  -b, --base-url BASE_URL
                        CrowdStrike Region (US1, US2, EU1, USGOV1, USGOV2) 
                        Full URL is also supported.

Example source code

The source code for this example can be found here.

Workflow Manager (GUI version)

Running the program || Authentication || Basic Usage || Advanced Usage || Command-line help || Source Code

Like the sample above, this sample demonstrates how to leverage the Workflows API to provide the following functionality:

List all workflows
Execute a workflow
List all executions for a workflow
Print the results of a workflow execution
Import a workflow
Export a workflow

Additional functionality provided by this sample include:

Full GUI interface
Activity logging (to a local file)
Exporting list results to CSV

Running the program

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

Service Collection

Scope

Workflows

READ, WRITE

This application can be started using a simple command line without arguments.

python3 workflow_manager_gui.py

Required packages

In order to run this sample, you will need to have the Gooey, requests and tabulate packages installed.

Return to Summary

Authentication

API credentials can be specified on the Environment tab.

These will be pre-populated if provided by the command line or environment.

[!TIP] These values can be provided on the command line using the -k and -s arguments or the --client_id and --client_secret arguments. This sample also supports Environment Authentication, meaning these values will be pre-populated for you from the variables FALCON_CLIENT_ID and FALCON_CLIENT_SECRET if they are present in the execution environment.

Return to Summary

Basic Usage

The GUI workflow manager application supports all of the same command functionality provided by the terminal version.

Listing workflows

To retrieve a list of all workflows within the tenant, select list_workflows on the Command tab.

Listing all workflows within the tenant requires no additional parameters (beyond authentication).

[!NOTE] This is the default command when no command is specified.

Results will be shown in a console window.

[!TIP] Review advanced configuration options below for more detail regarding table formatting and outputting results to CSV.

Executing a workflow

To execute a workflow, first select the execute action on the Command tab.

Provide the workflow definition ID of the workflow to execute in the id field on the Workflow tab.

If authentication credentials are provided via the command line or detected within the environment, the application will attempt to display a dropdown of all available workflows.

[!TIP] Bypass this behavior by providing the -sk or --skip_preflight command line argument when starting the application.

The dropdown is editable and will accept custom values.

Once your ID has been specified, provide the necessary execution payload for the workflow in the payload field.

Clicking the Start button will execute the options specified and display the results to the console.

Retrieving all executions for a workflow

Select the list_executions option on the Command tab to begin.

Provide the desired workflow definition ID in the id field on the Workflow tab.

Clicking the Start button will execute the search.

Results are displayed to the console.

Getting the results of a workflow execution

To retrieve results for a specific execution, first select the get_result option on the Command tab.

Provide the Workflow execution ID in the execution_id field on the Workflow tab.

To return results in indented JSON format, select the json option on the Environment tab.

Clicking the Start button will execute the request using the specified options and display the results to the console.

[!NOTE] Device IDs were redacted for this screen shot but are typically shown by the application.

Exporting a workflow to a YAML file

Select the workflow_export option on the Command tab.

Provide the desired workflow definition ID in the id field on the Workflow tab.

Use the export_workflow field on the Export tab to specify the save file for the export.

This file will be saved in YAML format.

The Browse button may be used to specify this value.

Clicking the Start button will export the selected workflow to the specified file.

If this file already exists, it will be overwritten.

Importing a workflow from a YAML file

Select the workflow_import option on the Command tab.

On the Import tab, provide the location of the workflow template YAML file in the import_workflow field.

The Browse button can be used to search and select the desired workflow template to import.

If the workflow name defined within the YAML file already exists in your tenant, an error will be thrown.

You can specify a new name for this workflow using the workflow_name field.

Use the validate checkbox to specify that this workflow will be validated for successful import, but no action will be taken.

Clicking the Start button will begin the import as specified.

Results will be displayed to the console upon completion.

Return to Summary

Advanced Usage

There are several advanced options that can be specified on the Environment tab or via the command line.

Formatting output

Specify the json option to output results in formatted JSON.

Different table formats may be selected using the table_format dropdown.

Output can compressed in the console to display when running multiple executions with the compress_output option.

Exporting list results to CSV

Select the csv option in the table_format dropdown field to export list results to CSV for the list_workflows and list_executions commands.

Results will be saved to workflows.csv or workflow_executions.csv depending on the operation selected.

Execution results are still displayed to the console using the simple table format when the Start button is pressed.

Providing configuration via the command line

Configuration options may be specified on the command line when starting the application. These values will be pre-populated on the configuration form. Command line provided configuration options take precedence over values specified as defaults or detected within the running environment.

Specifying the list executions command option and a workflow definition ID

python3 workflow_manager_gui.py -le -i $WORKFLOW_DEFINITION_ID

Importing a workflow using the command line

python3 workflow_manager_gui.py -im -iw $PATH_AND_FILENAME -n $NEW_WORKFLOW_NAME

Adjusting the console display font size

The font point size for the console display can be adjusted using a positional command line argument. This value should be an integer.

python3 workflow_manager_gui.py 10

[!NOTE] Positional command line arguments may be mixed with named arguments.

python3 workflow_manager_gui.py 14 -i $WORKFLOW_DEFINITION_ID -p {'HostNames': ['example-hostname']} -e

Auto-starting execution via the command line

Execution can be triggered at runtime by providing the go positional argument.

python3 workflow_manager_gui.py go -ex -ew $PATH_AND_FILENAME -i $WORKFLOW_DEFINITION_ID

[!NOTE] The font size and auto-execution positional arguments can be mixed together along with named arguments. When using font size and auto-execution together, the font size should be specified first.

python3 workflow_manager_gui.py 11 go -g -ei $EXECUTION_ID

Debugging API activity

Select the debug option to enable API debugging.

This will show detailed information regarding interactions performed with the CrowdStrike Falcon API, listing endpoints used, payloads provided, and responses received.

Logging results

To keep a separate log file of all results produced by the application, use the logfile field.

The Browse button can be used to select the log file.

[!WARNING] If this file exists, you may be prompted to replace the existing file.
This is a known issue. Log files will not be overwritten. Instead, results will be appended to the bottom of the file regardless of the operating system message.

Return to Summary

Command-line help

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

usage: workflow_manager_gui.py [-h] (-l | -e | -le | -g | -ex | -im) [-i ID] [-ei EXECUTION_ID] [-p PAYLOAD]
                               [-n WORKFLOW_NAME] [-v] [-iw IMPORT_WORKFLOW] [-ew EXPORT_WORKFLOW] [-k CLIENT_ID]
                               [-s CLIENT_SECRET] [-b {auto,us1,us2,eu1,usgov1,usgov2}] [-lf LOGFILE] [-d] [-o] [-sk]
                               (-j |
                                     -t {plain,simple,github,grid,simple_grid,rounded_grid,heavy_grid,mixed_grid,
                                     double_grid,fancy_grid,outline,simple_outline,rounded_outline,heavy_outline,
                                     mixed_outline,double_outline,fancy_outline,pipe,csv,orgtbl,asciidoc,jira,presto,
                                     pretty,psql,rst,mediawiki,moinmoin,youtrack,html,unsafehtml,latex,latex_raw,
                                     latex_booktabs,latex_longtable,textile,tsv})

Falcon Fusion SOAR workflow manager.

 _______                        __ _______ __        __ __
|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
|:  1   |                         |:  1   |
|::.. . |   CROWDSTRIKE FALCON    |::.. . |    FalconPy 1.4.1+
`-------'                         `-------'

 ██       ██                 ██       ████  ██
░██      ░██                ░██      ░██░  ░██
░██   █  ░██  ██████  ██████░██  ██ ██████ ░██  ██████  ███     ██
░██  ███ ░██ ██░░░░██░░██░░█░██ ██ ░░░██░  ░██ ██░░░░██░░██  █ ░██
░██ ██░██░██░██   ░██ ░██ ░ ░████    ░██   ░██░██   ░██ ░██ ███░██
░████ ░░████░██   ░██ ░██   ░██░██   ░██   ░██░██   ░██ ░████░████
░██░   ░░░██░░██████ ░███   ░██░░██  ░██   ███░░██████  ███░ ░░░██
░░       ░░  ░░░░░░  ░░░    ░░  ░░   ░░   ░░░  ░░░░░░  ░░░    ░░░
 ████     ████
░██░██   ██░██                               █████
░██░░██ ██ ░██  ██████   ███████   ██████   ██░░░██  █████  ██████
░██ ░░███  ░██ ░░░░░░██ ░░██░░░██ ░░░░░░██ ░██  ░██ ██░░░██░░██░░█
░██  ░░█   ░██  ███████  ░██  ░██  ███████ ░░██████░███████ ░██ ░
░██   ░    ░██ ██░░░░██  ░██  ░██ ██░░░░██  ░░░░░██░██░░░░  ░██
░██        ░██░░████████ ███  ░██░░████████  █████ ░░██████░███
░░         ░░  ░░░░░░░░ ░░░   ░░  ░░░░░░░░  ░░░░░   ░░░░░░ ░░░

This sample demonstrates how to leverage the Workflows API to provide
the following functionality:
  - List all workflows
    - Results can be exported to CSV
  - Execute a workflow
  - List all executions for a workflow
    - Results can be exported to CSV
  - Print the results of a workflow execution
  - Import a workflow
  - Export a workflow
  - Optional logging of results to a file

This version leverages the Gooey project to implement a simple GUI, command line
arguments are supported but not required to specify execution configuration.

Creation date: 11.06.2024 - Initial version, jlangdev@CrowdStrike
Modification date: 11.08.2024 - Refactoring, jshcodes@CrowdStrike
Modification date: 11.10.2024 - Add graphical interface, jshcodes@CrowdStrike

This sample requires the following packages:
- crowdstrike-falconpy >= 1.4.1
- gooey
- requests
- tabulate

options:
  -h, --help            show this help message and exit

Command:
  Workflow command to perform

  -l, --list_workflows  List all workflows
  -e, --execute         Execute the workflow specified on the Workflow tab
  -le, --list_executions
                        List the executions for the workflow specified
  -g, --get_result      Retrieve a workflow execution result
  -ex, --workflow_export
                        Export a workflow
  -im, --workflow_import
                        Import a workflow

Workflow:
  Workflow or execution ID and workflow payload

  -i, --id ID           Workflow definition ID
  -ei, --execution_id EXECUTION_ID
                        Workflow execution ID
  -p, --payload PAYLOAD
                        Workflow execution payload

Import:
  Import a workflow from a file

  -n, --workflow_name WORKFLOW_NAME
                        Name for the imported workflow
  -v, --validate_only   Validate the workflow only, do not save upon import
  -iw, --import_workflow IMPORT_WORKFLOW
                        Location of the YAML workflow file to import

Export:
  Export a workflow to a file

  -ew, --export_workflow EXPORT_WORKFLOW
                        Location to save the exported workflow (YAML format)
                        Use the Workflow tab to specify the desired workflow ID

Environment:
  Authentication and program execution options

  -k, --client_id CLIENT_ID
                        CrowdStrike Falcon API ID
                        (pre-filled from environment or command line)
  -s, --client_secret CLIENT_SECRET
                        CrowdStrike Falcon API secret
                        (pre-filled from environment or command line)
  -b, --base_url {auto,us1,us2,eu1,usgov1,usgov2}
                        CrowdStrike Region
                        ('auto' not implemented for usgov1 or usgov2)
  -lf, --logfile LOGFILE
                        Log output results to a local file as well as the console
  -d, --debug            Activate API debugging
  -o, --compress_output
                         Compress display output
  -sk, --skip_preflight
                         Skip preflight API lookups
  -j, --json            Display execution results in JSON format
  -t, --table_format {plain,simple,github,grid,simple_grid,rounded_grid,heavy_grid,mixed_grid,double_grid,fancy_grid,outline,simple_outline,rounded_outline,heavy_outline,mixed_outline,double_outline,fancy_outline,pipe,csv,orgtbl,asciidoc,jira,presto,pretty,psql,rst,mediawiki,moinmoin,youtrack,html,unsafehtml,latex,latex_raw,latex_booktabs,latex_longtable,textile,tsv}
                        Tabular display format
                        Selecting CSV format will output to a file and display a table to the console using simple format

Return to Summary

Example source code

The source code for this example can be found here.

Return to Summary

Previoususer_management Nextcorrelation_rules

Last updated 9 months ago

Was this helpful?