New Samples - IOC Restore, Workflow Manager

.github/wordlist.txt

@@ -1445,3 +1445,20 @@ LaunchScan
 DeleteScanResult
 QueryScanResults
 GetSensorUsageWeekly
+gethostgroups
+queryhostgroups
+WorkflowExecutionsResults
+gui
+workflowdefinitionscombined
+workflowdefinitionsexport
+workflowdefinitionsimport
+workflowexecute
+workflowexecutionscombined
+workflowexecutionsresults
+YYYY
+dropdown
+YAML
+Prefilling
+Autostarting
+logfile
+termcolor

AUTHORS.md

@@ -101,6 +101,7 @@ This has been a critical element in the development of the FalconPy project.
 + Alexander Moomaw, `@alhumaw`
 + Esha Kumar, `@exk200006`
 + Griffin Ansel, `@gansel51`
++ `@am-cs-se`
 
 
 ## Sponsors

README.md

@@ -31,7 +31,7 @@ The CrowdStrike Falcon SDK for Python completely abstracts token management, whi
 [![Development Installs](https://static.pepy.tech/personalized-badge/crowdstrike-falconpy-dev?left_text=development%20package%20installs/month&left_color=grey&right_color=blue&period=month)](https://pepy.tech/project/crowdstrike-falconpy-dev)
 
 #### Supported versions of Python
-The CrowdStrike Falcon SDK for Python was developed for Python 3. Current versions of FalconPy provide support for Python versions `3.7` - `3.12`. Every commit to the FalconPy code base is unit tested for functionality using all versions of Python the library currently supports.
+The CrowdStrike Falcon SDK for Python was developed for Python 3. Current versions of FalconPy provide support for Python versions `3.7` - `3.13`. Every commit to the FalconPy code base is unit tested for functionality using all versions of Python the library currently supports.
 
 > [!NOTE]
 > Developers working with Python version `3.6` will need to leverage versions of FalconPy less than `1.4.0`.
@@ -135,13 +135,17 @@ from falconpy import Hosts
 # CrowdStrike does not recommend you hardcode credentials within source code.
 # Instead, provide these values as variables that are retrieved from the environment,
 # read from an encrypted file or secrets store, provided at runtime, etc.
-# This example retrieves credentials from the environment as the variables
-# "FALCON_CLIENT_ID" and "FALCON_CLIENT_SECRET".
 
 hosts = Hosts(client_id=os.getenv("FALCON_CLIENT_ID"),
               client_secret=os.getenv("FALCON_CLIENT_SECRET")
               )
 
+# While this example retrieves credentials from the environment as the variables
+# "FALCON_CLIENT_ID" and "FALCON_CLIENT_SECRET". Developers leveraging environment
+# authentication do not need to specify the client_id or client_secret keywords.
+#
+# hosts = Hosts()
+
 SEARCH_FILTER = "hostname-search-string"
 
 # Retrieve a list of hosts that have a hostname that matches our search filter

samples/ioc/README.md

@@ -5,6 +5,7 @@ The examples within this folder focus on leveraging CrowdStrike's Falcon IOC API
 
 - [Create Indicator of Compromise](#create-indicator-of-compromise)
 - [IOC Audit](#ioc-audit)
+- [IOC Restore](#ioc-restore)
 
 ## Create Indicator of Compromise
 Demonstrates the creation of a single IOC using either the Service or Uber Class. 
@@ -196,4 +197,148 @@ Required arguments:
 ```
 
 ### Example source code
-The source code for this example can be found [here](ioc_audit.py).
+The source code for this example can be found [here](ioc_audit.py).
+
+---
+
+## IOC Restore
+This program will restore deleted IOCs based upon specified filter criteria.
+
+### 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 |
+| :---- | :---- |
+| IOC | __READ__, __WRITE__ |
+
+#### Required packages
+In order to run this sample, you will need to have the [`tabulate`](https://pypi.org/project/tabulate/) package installed.
+
+### Execution syntax
+This sample leverages simple command-line arguments to implement functionality.
+
+#### Basic usage
+Execute the default example. This will default to looking for IOCs that were applied globally and deleted as of today's date.
+
+> [!NOTE]
+> Times are in UTC.
+
+```shell
+python3 ioc_restore.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET
+```
+
+> This sample supports [Environment Authentication](https://falconpy.io/Usage/Authenticating-to-the-API.html#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.
+
+```shell
+python3 ioc_restore.py
+```
+
+Change the CrowdStrike region with the `-b` argument.
+
+```shell
+python3 ioc_restore.py -b usgov1
+```
+
+Search for deleted IOCs modified by a specific user with the `-m` argument.
+
+```shell
+python3 ioc_restore.py -m [email protected]
+```
+
+Search for deleted IOCs on a specific day using the `-dt` argument.
+
+> [!TIP]
+> This argument should be in YYYY-mm-dd format.
+
+```shell
+python3 ioc_restore.py -dt 2024-10-27
+```
+
+Search for deleted IOCs targeting a specific Host Group (by ID) using the `-hg` argument.
+
+```shell
+python3 ioc_restore.py -hg $HOST_GROUP_ID
+```
+
+Search for deleted IOCs targeting a specific Host Group (by Host Group name) using the `-g` argument.
+
+```shell
+python3 ioc_restore.py -g $HOST_GROUP_NAME
+```
+
+List all deleted IOCs discovered but take no action with the `-l` argument.
+
+```shell
+python3 ioc_restore.py -l
+```
+
+> [!TIP]
+> Multiple command line parameters may be provided to refine search results.
+
+API debugging can be enabled using the `-d` argument.
+
+```shell
+python3 ioc_restore.py -d
+```
+
+Adjust the output table format using the `-t` argument.
+
+```shell
+python3 ioc_restore.py -l -t fancy_grid
+```
+
+#### Command-line help
+Command-line help is available via the `-h` argument.
+
+```shell
+usage: ioc_restore.py [-h] [-d] [-c CLIENT_ID] [-k CLIENT_SECRET] [-b BASE_URL] [-dt DATE]
+                      [-m MODIFIED_BY] [-hg HOSTGROUP] [-g GROUPNAME] [-l] [-t TABLE_FORMAT]
+
+Restore deleted IOCs.
+
+ _______                        __ _______ __        __ __
+|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
+|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
+|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
+|:  1   |                         |:  1   |
+|::.. . |   CROWDSTRIKE FALCON    |::.. . |    FalconPy
+`-------'                         `-------'
+
+╦╔═╗╔═╗  ╦═╗┌─┐┌─┐┌┬┐┌─┐┬─┐┌─┐
+║║ ║║    ╠╦╝├┤ └─┐ │ │ │├┬┘├┤
+╩╚═╝╚═╝  ╩╚═└─┘└─┘ ┴ └─┘┴└─└─┘
+
+This sample demonstrates restoring previously deleted IOCs.
+
+~~~ API Scope Requirements ~~~
+IOC Management - Read / Write
+IOCs (Indicators of Compromise) - Read / Write
+
+Creation date: 11.06.2024 - am-cs-se@CrowdStrike
+Modification: 11.07.2024 - jshcodes@CrowdStrike
+
+options:
+  -h, --help            show this help message and exit
+  -d, --debug           Enable API debugging
+  -c, --client_id CLIENT_ID
+                        CrowdStrike API client ID
+  -k, --client_secret CLIENT_SECRET
+                        CrowdStrike API client secret
+  -b, --base_url BASE_URL
+                        CrowdStrike Region (US1, US2, EU1, USGOV1, USGOV2) Full URL is also supported.
+  -dt, --date DATE      Date to target (YYYY-MM-DD)
+  -m, --modified_by MODIFIED_BY
+                        User who modified the deleted IOCs
+  -hg, --hostgroup HOSTGROUP
+                        ID of the Host Group associated with the IOC Not required when --groupname is
+                        specified.
+  -g, --groupname GROUPNAME
+                        Name of the Host Group associated with the IOC Not required when --hostgroup is
+                        specified.
+  -l, --list            List deleted IOCs but take no action
+  -t, --table-format TABLE_FORMAT
+                        Tabular display format
+```
+
+### Example source code
+The source code for this example can be found [here](ioc_restore.py).