diff --git a/samples/sensor_update_policies/README.md b/samples/sensor_update_policies/README.md index 18323297b..0ae17b545 100644 --- a/samples/sensor_update_policies/README.md +++ b/samples/sensor_update_policies/README.md @@ -3,6 +3,7 @@ # Sensor Update Policies examples The examples in this folder focus on leveraging CrowdStrike's Sensor Update Policies API to adjust sensor update policy settings. +- [Create Host Group and attach to policy](#create-host-group-and-attach-to-sensor-update-policy) - [Sensor Update Policy Cloner](#sensor-update-policy-cloner) - [Policy Wonk](#manage-sensor-update-policies-with-policy-wonk) @@ -108,6 +109,167 @@ The source code for this example can be found [here](clone_update_policy.py). --- +## Create Host Group and attach to sensor update policy +This script will create a host group. If a list of sensor update policy IDs are provided, the newly created host group is added to each policy in the list. This can assist with complex group creation that may be difficult to perform in the console. + +> [!NOTE] +> If you set custom and/or criteria using the API, editing the group in the Falcon console will remove this criteria upon save. + +### 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 | +| :---- | :---- | +| Host Group | __READ__, __WRITE__ | +| Sensor Update Policy | __READ__, __WRITE__ | + +### Execution syntax +This sample leverages simple command-line arguments to implement functionality. + +#### Basic usage +Create a simple host group with no settings. + +```shell +python3 create_attached_group.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -n GROUP_NAME +``` + +> This sample supports [Environment Authentication](https://falconpy.io/Usage/Authenticating-to-the-API.html#environment-authentication), meaning you can execute this program without providing credentials if you have the values `FALCON_CLIENT_ID` and `FALCON_CLIENT_SECRET` defined in your environment. + +```shell +python3 create_attached_group.py -n GROUP_NAME +``` + +Attach the newly created group to two sensor update policies. + +```shell +python3 create_attached_group.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -n GROUP_NAME -p POLICY_ID_1,POLICY_ID_2 +``` + +Create a host group, setting all available parameters. + +```shell +python3 create_attached_group.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -n GROUP_NAME -p POLICY_ID_1,POLICY_ID_2 -e GROUP_DESCRIPTION -t GROUP_TYPE -a ASSIGNMENT_RULE +``` + +> API debugging can be enabled using the `-d` argument. + +```shell +python3 create_attached_group.py -d +``` + +#### Command-line help +Command-line help is available via the `-h` argument. + +```shell +usage: create_group_add_to_update_policy.py [-h] [-d] [-c CHILD] -n GROUP_NAME + [-e GROUP_DESCRIPTION] [-t {dynamic,static}] + [-a ASSIGNMENT_RULE] [-p POLICIES] [-k CLIENT_ID] + [-s CLIENT_SECRET] + +Create Host Groups (and add them to Sensor Update Policies). + + _______ __ _______ __ __ __ +| _ .----.-----.--.--.--.--| | _ | |_.----|__| |--.-----. +|. 1___| _| _ | | | | _ | 1___| _| _| | <| -__| +|. |___|__| |_____|________|_____|____ |____|__| |__|__|__|_____| +|: 1 | |: 1 | +|::.. . | |::.. . | FalconPy +`-------' `-------' + + __ __ . ___ + | | __. ____ _/_ .' \ .___ __. , . \,___, + |___| .' \ ( | | / \ .' \ | | | \ + | | | | `--. | | _ | ' | | | | | | + / / `._.' \___.' \__/ `.___| / `._.' `._/| |`---' + \ + + .----------------. + | .--------------. | + | | _ | | + | | | | | | + | | ___| |___ | | + | | |___ ___| | | + | | | | | | + | | |_| | | + | | | | + | '--------------' | + '----------------' + + _______. _______ .__ __. _______. ______ .______ + / || ____|| \ | | / | / __ \ | _ \ + | (----`| |__ | \| | | (----`| | | | | |_) | + \ \ | __| | . ` | \ \ | | | | | / +.----) | | |____ | |\ | .----) | | `--' | | |\ \----. +|_______/ |_______||__| \__| |_______/ \______/ | _| `._____| + + __ __ .______ _______ ___ .___________. _______ +| | | | | _ \ | \ / \ | || ____| +| | | | | |_) | | .--. | / ^ \ `---| |----`| |__ +| | | | | ___/ | | | | / /_\ \ | | | __| +| `--' | | | | '--' | / _____ \ | | | |____ + \______/ | _| |_______/ /__/ \__\ |__| |_______| + +.______ ______ __ __ ______ __ _______ _______. +| _ \ / __ \ | | | | / || | | ____| / | +| |_) | | | | | | | | | | ,----'| | | |__ | (----` +| ___/ | | | | | | | | | | | | | __| \ \ +| | | `--' | | `----.| | | `----.| | | |____.----) | +| _| \______/ |_______||__| \______||__| |_______|_______/ + +This script will create a host group. If a list of prevention policy IDs +are provided, the newly created host group is added to each policy in the +list. This can assist with complex group creation that may be difficult +to perform in the console. + +Please note: If you set custom and/or criteria using the API, editing the +group in the Falcon console will remove this criteria upon save. + +Developed by Don-Swanson-Adobe + +Dynamic Host group examples with custom and/or criteria + +AND Example (Product is Windows AND Type is Server): + "platform_name:'Windows'+product_type_desc:'Server'" + +OR Example (OS is Win Server 2008 R2 OR OS is Windows 7): +"os_version:'Windows Server 2008 R2',os_version:'Windows 7'" +OR Example (OS is Win Server 2008 R2 OR OS is Windows 7) +"(os_version:'Windows Server 2008 R2',os_version:'Windows 7')" + +Mixed Use Example (Must Have a DEV Sensor Tag and a T1 or T2 Sensor Tag) +"(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/T1),(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/T2')" +"tags:'SensorGroupingTags/DEV'+(tags:'SensorGroupingTags/T1',tags:'SensorGroupingTags/T2')" + +optional arguments: + -h, --help show this help message and exit + -d, --debug Enable API debugging + -c CHILD, --child CHILD + Perform update in a specific child CID (MSSP parents only) + +Group arguments: + -n GROUP_NAME, --group_name GROUP_NAME + Name to use for newly created Host Group + -e GROUP_DESCRIPTION, --group_description GROUP_DESCRIPTION + Description to use for newly created Host Group + -t {dynamic,static}, --group_type {dynamic,static} + Type of Host Group to create (dynamic or static, defaults to dynamic) + -a ASSIGNMENT_RULE, --assignment_rule ASSIGNMENT_RULE + Assignment rule for the newly created Host Group (enclose in double quotes) + -p POLICIES, --policies POLICIES + Prevention Policies IDs to assign this Host Group to (comma delimit) + +Required arguments: + -k CLIENT_ID, --client_id CLIENT_ID + CrowdStrike Falcon API key + -s CLIENT_SECRET, --client_secret CLIENT_SECRET + CrowdStrike Falcon API secret +``` + +### Example source code +The source code for this example can be found [here](create_attached_group.py). + +--- + ## Manage sensor update policies with Policy Wonk Manages CrowdStrike Falcon sensor update policy. Using this tool you can enable and disable policies, and their uninstall protection. You can create and remove policies. Policies can be updated with new host groups and precedence can be reordered. diff --git a/samples/sensor_update_policies/create_attached_group.py b/samples/sensor_update_policies/create_attached_group.py new file mode 100755 index 000000000..417846a1a --- /dev/null +++ b/samples/sensor_update_policies/create_attached_group.py @@ -0,0 +1,182 @@ +#!/usr/bin/env python3 +r"""Create Host Groups (and add them to Sensor Update Policies). + + _______ __ _______ __ __ __ +| _ .----.-----.--.--.--.--| | _ | |_.----|__| |--.-----. +|. 1___| _| _ | | | | _ | 1___| _| _| | <| -__| +|. |___|__| |_____|________|_____|____ |____|__| |__|__|__|_____| +|: 1 | |: 1 | +|::.. . | |::.. . | FalconPy +`-------' `-------' + + __ __ . ___ + | | __. ____ _/_ .' \ .___ __. , . \,___, + |___| .' \ ( | | / \ .' \ | | | \ + | | | | `--. | | _ | ' | | | | | | + / / `._.' \___.' \__/ `.___| / `._.' `._/| |`---' + \ + + .----------------. + | .--------------. | + | | _ | | + | | | | | | + | | ___| |___ | | + | | |___ ___| | | + | | | | | | + | | |_| | | + | | | | + | '--------------' | + '----------------' + + _______. _______ .__ __. _______. ______ .______ + / || ____|| \ | | / | / __ \ | _ \ + | (----`| |__ | \| | | (----`| | | | | |_) | + \ \ | __| | . ` | \ \ | | | | | / +.----) | | |____ | |\ | .----) | | `--' | | |\ \----. +|_______/ |_______||__| \__| |_______/ \______/ | _| `._____| + + __ __ .______ _______ ___ .___________. _______ +| | | | | _ \ | \ / \ | || ____| +| | | | | |_) | | .--. | / ^ \ `---| |----`| |__ +| | | | | ___/ | | | | / /_\ \ | | | __| +| `--' | | | | '--' | / _____ \ | | | |____ + \______/ | _| |_______/ /__/ \__\ |__| |_______| + +.______ ______ __ __ ______ __ _______ _______. +| _ \ / __ \ | | | | / || | | ____| / | +| |_) | | | | | | | | | | ,----'| | | |__ | (----` +| ___/ | | | | | | | | | | | | | __| \ \ +| | | `--' | | `----.| | | `----.| | | |____.----) | +| _| \______/ |_______||__| \______||__| |_______|_______/ + +This script will create a host group. If a list of prevention policy IDs +are provided, the newly created host group is added to each policy in the +list. This can assist with complex group creation that may be difficult +to perform in the console. + +Please note: If you set custom and/or criteria using the API, editing the +group in the Falcon console will remove this criteria upon save. + +Developed by Don-Swanson-Adobe + +Dynamic Host group examples with custom and/or criteria + +AND Example (Product is Windows AND Type is Server): + "platform_name:'Windows'+product_type_desc:'Server'" + +OR Example (OS is Win Server 2008 R2 OR OS is Windows 7): +"os_version:'Windows Server 2008 R2',os_version:'Windows 7'" +OR Example (OS is Win Server 2008 R2 OR OS is Windows 7) +"(os_version:'Windows Server 2008 R2',os_version:'Windows 7')" + +Mixed Use Example (Must Have a DEV Sensor Tag and a T1 or T2 Sensor Tag) +"(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/T1),(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/T2')" +"tags:'SensorGroupingTags/DEV'+(tags:'SensorGroupingTags/T1',tags:'SensorGroupingTags/T2')" +""" +import os +import logging +from argparse import ArgumentParser, RawTextHelpFormatter, Namespace +from falconpy import APIHarnessV2, APIError, Result + + +def consume_arguments() -> Namespace: + """Consume any provided command line arguments.""" + parser = ArgumentParser(description=__doc__, formatter_class=RawTextHelpFormatter) + parser.add_argument("-d", "--debug", + help="Enable API debugging", + action="store_true", + default=False + ) + parser.add_argument("-c", "--child", + help="Perform update in a specific child CID (MSSP parents only)", + default=None + ) + grp = parser.add_argument_group("Group arguments") + grp.add_argument("-n", "--group_name", + help="Name to use for newly created Host Group", + required=True + ) + grp.add_argument("-e", "--group_description", + help="Description to use for newly created Host Group" + ) + grp.add_argument("-t", "--group_type", + help="Type of Host Group to create (dynamic or static, defaults to dynamic)", + choices=["dynamic", "static"], + default="dynamic" + ) + grp.add_argument("-a", "--assignment_rule", + help="Assignment rule for the newly created Host Group (enclose in double quotes)" + ) + grp.add_argument("-p", "--policies", + help="Prevention Policies IDs to assign this Host Group to (comma delimit)" + ) + req = parser.add_argument_group("Required arguments") + req.add_argument("-k", "--client_id", + help="CrowdStrike Falcon API key", + default=os.getenv("FALCON_CLIENT_ID") + ) + req.add_argument("-s", "--client_secret", + help="CrowdStrike Falcon API secret", + default=os.getenv("FALCON_CLIENT_SECRET") + ) + parsed = parser.parse_args() + if not parsed.client_id or not parsed.client_secret: + parser.error( + "You must provide CrowdStrike API credentials using the '-k' and '-s' arguments." + ) + return parsed + + +# Consume any command line arguments +cmd_line = consume_arguments() + +# Activate debugging if requested +if cmd_line.debug: + logging.basicConfig(level=logging.DEBUG) + +# Create our base authentication dictionary (parent / child) +auth = { + "client_id": cmd_line.client_id, + "client_secret": cmd_line.client_secret, + "debug": cmd_line.debug, + "pythonic": True +} +local = APIHarnessV2(**auth) +if cmd_line.child: + # Authenticate to the child if necessary + auth["member_cid"] = cmd_line.child +falcon = APIHarnessV2(**auth) +# Create Host Group +body_payload = { + "resources": [{ + "assignment_rule": cmd_line.assignment_rule, + "description": cmd_line.group_description, + "group_type": cmd_line.group_type, + "name": cmd_line.group_name + }] + } +try: + response = falcon.command("createHostGroups", body=body_payload) +except APIError as api_error: + raise SystemExit(api_error.message) + +print(f"New Group ID: {response.data[0]['id']}") +group_id = response.data[0]["id"] +if cmd_line.policies: + # Attach new group to policy + for policy in cmd_line.policies.split(","): + body_payload = { + "action_parameters": [{ + "name": "group_id", + "value": group_id + }], + "ids": [policy] + } + try: + response: Result = falcon.command("performSensorUpdatePoliciesAction", + action_name="add-host-group", + body=body_payload + ) + print(f"{cmd_line.group_name} successfully added to sensor update policy (ID: {policy})") + except APIError as api_error: + print(api_error.message) diff --git a/samples/sensor_update_policies/create_group_add_to_update_policy.py b/samples/sensor_update_policies/create_group_add_to_update_policy.py deleted file mode 100755 index 298b2430d..000000000 --- a/samples/sensor_update_policies/create_group_add_to_update_policy.py +++ /dev/null @@ -1,57 +0,0 @@ -#!/usr/bin/env python3 -#Please establish an "auth.py" file in the same directory as this script with the "clientid" and "clientsec" variables defined. -#This script was developed to create a new dynamic group based on a specific assignment rule and then add that group to a list of update policies. This is expecially useful when you want to create a dynamic group based on specific and/or criteria that you cannot do via the UI. NOTE: If you do use custom and/or criteria here, editing the group in the UI will remove the custom and/or and destroy the group function. -#You will need to create the Update Policy first and grab it's Policy ID (The last random string in the URL) -#Developed by Don-Swanson-Adobe - -####REPLACE THE FOLLOWING EXAMPLE VARIABLES#### -policies=["098765432109876543210987654321",] #Replace with Update Policies you wish the group to join -group_name= "MacOS Ventura" #Replace with desired group name -group_description = "MacOS Ventura Hosts" #Replace with groups description -group_type = "dynamic" #Replace with group type -assignment_rule = "os_version:'Ventura (13)'" #Replace with the desired assignment rule -############################################### -#Dynamic Host group examples with custom and/or criteria -#AND Example: -#Product is Windows AND Type is Server -# "platform_name:'Windows'+product_type_desc:'Server'" -# -#OR Examples: -#OS is Win Server 2008 R2 OR OS is Windows 7 -# "os_version:'Windows Server 2008 R2',os_version:'Windows 7'" -#OS is Win Server 2008 R2 OR OS is Windows 7 -# "(os_version:'Windows Server 2008 R2',os_version:'Windows 7')" -# -#Mixed Use -#Must Have a DEV Sensor Tag and a Team1 or Team2 Sensor Tag -# "(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/Team1),(tags:'SensorGroupingTags/DEV'+tags:'SensorGroupingTags/Team2')" -# "tags:'SensorGroupingTags/DEV'+(tags:'SensorGroupingTags/Team1',tags:'SensorGroupingTags/Team2')" - -#Import API Harness and Auth File -from falconpy import APIHarness -from auth import * - -#Do the needful for each CID in the auth file -for key, value in cids.items(): - print("\n"+value) - #Auth - falcon = APIHarness(client_id=clientid, client_secret=clientsec, member_cid=key) - - #Create Host Group - BODY = { - "resources": [{ - "assignment_rule": assignment_rule, - "description": group_description, - "group_type": group_type, - "name": group_name}]} - - response = falcon.command("createHostGroups", body=BODY) - print("New Group ID: "+response["body"]["resources"][0]["id"]) - group_id = response["body"]["resources"][0]["id"] - - #Attach new group to policy - for i in policies: - BODY = {"action_parameters": [{"name": "group_id","value": group_id}],"ids": [i]} - response = falcon.command("performSensorUpdatePoliciesAction", action_name="add-host-group", body=BODY) - print("Response Code: " + str(response["status_code"])) - print("Errors: " + str(response["body"]["errors"]))