From 3c20a516003f46d2f81c43e1c61e8019554ac229 Mon Sep 17 00:00:00 2001 From: Joshua Hiller Date: Mon, 28 Aug 2023 05:07:25 -0400 Subject: [PATCH] Add new FileVantage operations --- src/falconpy/_endpoint/_filevantage.py | 516 +++++++++++++ src/falconpy/_payload/__init__.py | 9 +- src/falconpy/_payload/_filevantage.py | 163 +++++ src/falconpy/filevantage.py | 977 ++++++++++++++++++++++++- tests/test_filevantage.py | 40 +- 5 files changed, 1702 insertions(+), 3 deletions(-) create mode 100644 src/falconpy/_payload/_filevantage.py diff --git a/src/falconpy/_endpoint/_filevantage.py b/src/falconpy/_endpoint/_filevantage.py index fef239496..8ba615fe0 100644 --- a/src/falconpy/_endpoint/_filevantage.py +++ b/src/falconpy/_endpoint/_filevantage.py @@ -60,6 +60,436 @@ } ] ], + [ + "updatePolicyHostGroups", + "PATCH", + "/filevantage/entities/policies-host-groups/v1", + "Manage host groups assigned to a policy.", + "filevantage", + [ + { + "type": "string", + "description": "The id of the policy for which to perform the action.", + "name": "policy_id", + "in": "query", + "required": True + }, + { + "type": "string", + "description": "The action to perform with the provided ids, must be one of: `assign` or `unassign`.", + "name": "action", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more host group ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "updatePolicyPrecedence", + "PATCH", + "/filevantage/entities/policies-precedence/v1", + "Updates the policy precedence for all policies of a specific type.", + "filevantage", + [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "Precedence of the policies for the provided type in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + }, + { + "type": "string", + "description": "The policy type for which to set the precedence order, must be one of `Windows`, `Linux` or `Mac`.", + "name": "type", + "in": "query", + "required": True + } + ] + ], + [ + "updatePolicyRuleGroups", + "PATCH", + "/filevantage/entities/policies-rule-groups/v1", + "Manage the rule groups assigned to the policy or set the rule group precedence for all rule groups within the policy.", + "filevantage", + [ + { + "type": "string", + "description": "The id of the policy for which to perform the action.", + "name": "policy_id", + "in": "query", + "required": True + }, + { + "type": "string", + "description": "The action to perform with the provided ids, must be one of: `assign`, `unassign`, or `precedence`.", + "name": "action", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more rule group ids in the form of ids=ID1&ids=ID2. Note, for the precedence action, precedence is controlled by the order of the ids as they are specified in the request.", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "getPolicies", + "GET", + "/filevantage/entities/policies/v1", + "Retrieves the configuration for 1 or more policies.", + "filevantage", + [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) policy ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "createPolicies", + "POST", + "/filevantage/entities/policies/v1", + "Creates a new policy of the specified type. New policies are always added at the end of the precedence list for the provided policy type.", + "filevantage", + [ + { + "description": "Create a new policy.\n\n * `name` must be between 1 and 100 characters.\n\n * `description` can be between 0 and 500 characters.\n\n * `platform` must be one of `Windows`, `Linux`, or `Mac`\n\n Rule and host group assignment and policy precedence setting is performed via their respective patch end-points.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "updatePolicies", + "PATCH", + "/filevantage/entities/policies/v1", + "Updates the general information of the provided policy.", + "filevantage", + [ + { + "description": "Enables updates to the following fields for an existing policy. \n\n * `id` of the policy to update.\n\n * `name` must be between 1 and 100 characters.\n\n * `description` can be between 0 and 500 characters.\n\n * `platform` may not be modified after the policy is created.\n\n * `enabled` must be one of `true` or `false`.\n\n Rule and host group assignment and policy precedence setting is performed via their respective patch end-points.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "deletePolicies", + "DELETE", + "/filevantage/entities/policies/v1", + "Deletes 1 or more policies.", + "filevantage", + [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) policy ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "getScheduledExclusions", + "GET", + "/filevantage/entities/policy-scheduled-exclusions/v1", + "Retrieves the configuration of 1 or more scheduled exclusions from the provided policy id.", + "filevantage", + [ + { + "type": "string", + "description": "The id of the policy to retrieve the scheduled exclusion configurations.", + "name": "policy_id", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) scheduled exclusion ids in the form of `ids=ID1&ids=ID2`.", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "createScheduledExclusions", + "POST", + "/filevantage/entities/policy-scheduled-exclusions/v1", + "Creates a new scheduled exclusion configuration for the provided policy id.", + "filevantage", + [ + { + "description": "Create a new scheduled exclusion configuration for the specified policy.\n\n \n\n * `policy_id` to add the scheduled exclusion to.\n\n * `name` must be between 1 and 100 characters.\n\n * `description` can be between 0 and 500 characters.\n\n * `users` can be between 0 and 500 characters representing a comma separated list of user to exclude their changes.\n\n * admin* excludes changes made by all usernames that begin with admin. Falon GLOB syntax is supported.\n\n * `processes` can be between 0 and 500 characters representing a comma separated list of processes to exclude their changes.\n\n * **\\RunMe.exe or **/RunMe.sh excludes changes made by RunMe.exe or RunMe.sh in any location.\n\n * `schedule_start` must be provided to indicate the start of the schedule. This date/time must be an rfc3339 formatted string https://datatracker.ietf.org/doc/html/rfc3339.\n\n * `schedule_end` optionally provided to indicate the end of the schedule. This date/time must be an rfc3339 formatted string https://datatracker.ietf.org/doc/html/rfc3339.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "updateScheduledExclusions", + "PATCH", + "/filevantage/entities/policy-scheduled-exclusions/v1", + "Updates the provided scheduled exclusion configuration within the provided policy.", + "filevantage", + [ + { + "description": "Update an existing scheduled exclusion for the specified policy.\n\n \n\n * `id` representing the scheduled exclusion to update.\n\n * `policy_id` which the scheduled exclusion is assigned.\n\n * `name` must be between 1 and 100 characters.\n\n * `description` can be between 0 and 500 characters.\n\n * `users` can be between 0 and 500 characters representing a comma separated list of user to exclude their changes.\n\n * admin* excludes changes made by all usernames that begin with admin. Falon GLOB syntax is supported.\n\n * `processes` can be between 0 and 500 characters representing a comma separated list of processes to exclude their changes.\n\n * **\\RunMe.exe or **/RunMe.sh excludes changes made by RunMe.exe or RunMe.sh in any location.\n\n * `schedule_start` must be provided to indicate the start of the schedule. This date/time must be an rfc3339 formatted string https://datatracker.ietf.org/doc/html/rfc3339.\n\n * `schedule_end` optionally provided to indicate the end of the schedule. This date/time must be an rfc3339 formatted string https://datatracker.ietf.org/doc/html/rfc3339.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "deleteScheduledExclusions", + "DELETE", + "/filevantage/entities/policy-scheduled-exclusions/v1", + "Deletes 1 or more scheduled exclusions from the provided policy id.", + "filevantage", + [ + { + "type": "string", + "description": "ID of the policy to delete the scheduled exclusions from.", + "name": "policy_id", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) scheduled exclusion ids in the form of `ids=ID1&ids=ID2`.", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "updateRuleGroupPrecedence", + "PATCH", + "/filevantage/entities/rule-groups-rule-precedence/v1", + "Updates the rule precedence for all rules in the identified rule group.", + "filevantage", + [ + { + "type": "string", + "description": "Rule group from which to set the precedence.", + "name": "rule_group_id", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) rule group ids in the form of `ids=ID1&ids=ID2`.", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "getRules", + "GET", + "/filevantage/entities/rule-groups-rules/v1", + "Retrieves the configuration for 1 or more rules.", + "filevantage", + [ + { + "type": "string", + "description": "Rule group from which to retrieve the rule configuration.", + "name": "rule_group_id", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) rule ids in the form of `ids=ID1&ids=ID2`.", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "createRules", + "POST", + "/filevantage/entities/rule-groups-rules/v1", + "Creates a new rule configuration within the specified rule group.", + "filevantage", + [ + { + "description": "Create a new rule configuration for the specified rule group.\n\n * `id` is not supported for creation of a rule, the new id of the created rule will be included in the response.\n\n * `rule_group_id` to add the new rule configuration.\n\n * `description` can be between 0 and 500 characters.\n\n * `path` representing the file system or registry path to monitor.\n\n * must be between 1 and 250 characters. \n\n * All paths must end with the path separator, e.g. c:\\windows\\ /usr/bin/ \n\n * `severity` to categorize change events produced by this rule; must be one of: `Low`, `Medium`, `High` or `Critical`\n\n * `depth` below the base path to monitor; must be one of: `1`, `2`, `3`, `4`, `5` or `ANY`\n\n * `precedence` - is not supported for creation of a rule, new rules will be added last in precedence order.will result this rule being placed before that existing rule.\n\nFalcon GLOB syntax is supported for the following 6 properties. Allowed rule group configuration is based on the type of rule group the rule group is added to.\n\n * `include` represents the files, directories, registry keys, or registry values that will be monitored. \n\n * `exclude` represents the files, directories, registry keys, or registry values that will `NOT` be monitored. \n\n * `include_users` represents the changes performed by specific users that will be monitored (`macOS` is not supported at this time).\n\n * `exclude_users` represents the changes performed by specific users that will `NOT` be monitored (`macOS` is not supported at this time).\n\n * `include_processes` represents the changes performed by specific processes that will be monitored (`macOS` is not supported at this time).\n\n * `exclude_users` represents the changes performed by specific processes that will be `NOT` monitored (`macOS` is not supported at this time).\n\nFile system directory monitoring:\n\n * `watch_delete_directory_changes`\n\n * `watch_create_directory_changes`\n\n * `watch_rename_directory_changes`\n\n * `watch_attributes_directory_changes` (`macOS` is not supported at this time)\n\n * `watch_permissions_directory_changes` (`macOS` is not supported at this time)\n\nFile system file monitoring:\n\n * `watch_rename_file_changes`\n\n * `watch_write_file_changes`\n\n * `watch_create_file_changes`\n\n * `watch_delete_file_changes`\n\n * `watch_attributes_file_changes` (`macOS` is not supported at this time)\n\n * `watch_permissions_file_changes` (`macOS` is not supported at this time)\n\nWindows registry key and value monitoring: \n\n * `watch_create_key_changes`\n\n * `watch_delete_key_changes`\n\n * `watch_rename_key_changes`\n\n * `watch_set_value_changes`\n\n * `watch_delete_value_changes`\n\n * `watch_create_file_changes`", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "updateRules", + "PATCH", + "/filevantage/entities/rule-groups-rules/v1", + "Updates the provided rule configuration within the specified rule group.", + "filevantage", + [ + { + "description": "Update the rule configuration for the specified rule ID and group.\n\n * `id` of the rule to update.\n\n * `rule_group_id` that contains the rule configuration.\n\n * `description` can be between 0 and 500 characters.\n\n * `path` representing the file system or registry path to monitor.\n\n * must be between 1 and 250 characters. \n\n * All paths must end with the path separator, e.g. c:\\windows\\ /usr/bin/ \n\n * `severity` to categorize change events produced by this rule; must be one of: `Low`, `Medium`, `High` or `Critical`\n\n * `depth` below the base path to monitor; must be one of: `1`, `2`, `3`, `4`, `5` or `ANY`\n\n * `precedence` is the order in which rules will be evaluated starting with 1. Specifying a precedence value that is already set for another rule in the group will result this rule being placed before that existing rule.\n\nFalcon GLOB syntax is supported for the following 6 properties. Allowed rule group configuration is based on the type of rule group the rule group is added to.\n\n * `include` represents the files, directories, registry keys, or registry values that will be monitored. \n\n * `exclude` represents the files, directories, registry keys, or registry values that will `NOT` be monitored. \n\n * `include_users` represents the changes performed by specific users that will be monitored (`macOS` is not supported at this time).\n\n * `exclude_users` represents the changes performed by specific users that will `NOT` be monitored (`macOS` is not supported at this time).\n\n * `include_processes` represents the changes performed by specific processes that will be monitored (`macOS` is not supported at this time).\n\n * `exclude_users` represents the changes performed by specific processes that will be `NOT` monitored (`macOS` is not supported at this time).\n\nFile system directory monitoring:\n\n * `watch_delete_directory_changes`\n\n * `watch_create_directory_changes`\n\n * `watch_rename_directory_changes`\n\n * `watch_attributes_directory_changes` (`macOS` is not supported at this time)\n\n * `watch_permissions_directory_changes` (`macOS` is not supported at this time)\n\nFile system file monitoring:\n\n * `watch_rename_file_changes`\n\n * `watch_write_file_changes`\n\n * `watch_create_file_changes`\n\n * `watch_delete_file_changes`\n\n * `watch_attributes_file_changes` (`macOS` is not supported at this time)\n\n * `watch_permissions_file_changes` (`macOS` is not supported at this time)\n\nWindows registry key and value monitoring: \n\n * `watch_create_key_changes`\n\n * `watch_delete_key_changes`\n\n * `watch_rename_key_changes`\n\n * `watch_set_value_changes`\n\n * `watch_delete_value_changes`\n\n * `watch_create_file_changes`", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "deleteRules", + "DELETE", + "/filevantage/entities/rule-groups-rules/v1", + "Deletes 1 or more rules from the specified rule group.", + "filevantage", + [ + { + "type": "string", + "description": "The id of the rule group from which the rules will be deleted.", + "name": "rule_group_id", + "in": "query", + "required": True + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) rule ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "getRuleGroups", + "GET", + "/filevantage/entities/rule-groups/v1", + "Retrieves the rule group details for 1 or more rule groups.", + "filevantage", + [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) rule group ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], + [ + "createRuleGroups", + "POST", + "/filevantage/entities/rule-groups/v1", + "Creates a new rule group of the specified type.", + "filevantage", + [ + { + "description": "Create a new rule group of a specific type.\n\n * `name` must be between 1 and 100 characters.\n\n * `type` must be one of `WindowsFiles`, `WindowsRegistry`, `LinuxFiles` or `MacFiles`.\n\n * `description` can be between 0 and 500 characters.\n\n Note: rules are added/removed from rule groups using their dedicated end-points.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "updateRuleGroups", + "PATCH", + "/filevantage/entities/rule-groups/v1", + "Updates the provided rule group.", + "filevantage", + [ + { + "description": "Enables updates to the following fields for an existing rule group. \n\n * `id` of the rule group to update.\n\n * `name` must be between 1 and 100 characters.\n\n * `description` can be between 0 and 500 characters.\n\n * `type` may not be modified after the rule group is created.\n\n Note: rules are added/removed from rule groups using their dedicated end-points.", + "name": "body", + "in": "body", + "required": True + } + ] + ], + [ + "deleteRuleGroups", + "DELETE", + "/filevantage/entities/rule-groups/v1", + "Deletes 1 or more rule groups ", + "filevantage", + [ + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "multi", + "description": "One or more (up to 500) rule group ids in the form of `ids=ID1&ids=ID2`", + "name": "ids", + "in": "query", + "required": True + } + ] + ], [ "queryChanges", "GET", @@ -149,5 +579,91 @@ "in": "query" } ] + ], + [ + "queryPolicies", + "GET", + "/filevantage/queries/policies/v1", + "Retrieve the ids of all policies that are assigned the provided policy type.", + "filevantage", + [ + { + "minimum": 0, + "type": "integer", + "description": "The offset to start retrieving records from. Defaults to 0 if not specified.", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "The maximum number of ids to return. Defaults to 100 if not specified. The maximum number of results that can be returned in a single call is 500.", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "Sort the returned ids based on one of the following properties:\n\n`precedence`, `created_timestamp` or `modified_timestamp`\n\n Sort either `asc` (ascending) or `desc` (descending); for example: `precedence|asc`.", + "name": "sort", + "in": "query" + }, + { + "type": "string", + "description": "The types of policies to retrieve.\n\n Allowed values are: `Windows`, `Linux` or `Mac`.", + "name": "type", + "in": "query", + "required": True + } + ] + ], + [ + "queryScheduledExclusions", + "GET", + "/filevantage/queries/policy-scheduled-exclusions/v1", + "Retrieve the ids of all scheduled exclusions contained within the provided policy id.", + "filevantage", + [ + { + "type": "string", + "description": "The id of the policy from which to retrieve the scheduled exclusion ids.", + "name": "policy_id", + "in": "query", + "required": True + } + ] + ], + [ + "queryRuleGroups", + "GET", + "/filevantage/queries/rule-groups/v1", + "Retrieve the ids of all rule groups that are of the provided rule group type.", + "filevantage", + [ + { + "minimum": 0, + "type": "integer", + "description": "The offset to start retrieving records from. Defaults to 0 if not specified.", + "name": "offset", + "in": "query" + }, + { + "type": "integer", + "description": "The maximum number of ids to return. Defaults to 100 if not specified. The maximum number of results that can be returned in a single call is 500.", + "name": "limit", + "in": "query" + }, + { + "type": "string", + "description": "Sort the returned ids based on one of the following properties:\n\n `created_timestamp` or `modified_timestamp`\n\n Sort either `asc` (ascending) or `desc` (descending); for example: `created_timestamp|asc`.", + "name": "sort", + "in": "query" + }, + { + "type": "string", + "description": "The rule group type to retrieve the ids of.\n\n Allowed values are: `WindowsFiles`, `WindowsRegistry`, `LinuxFiles` or `MacFiles`.", + "name": "type", + "in": "query", + "required": True + } + ] ] ] diff --git a/src/falconpy/_payload/__init__.py b/src/falconpy/_payload/__init__.py index a75b7c945..6448e019f 100644 --- a/src/falconpy/_payload/__init__.py +++ b/src/falconpy/_payload/__init__.py @@ -55,6 +55,12 @@ from ._cspm_registration import cspm_registration_payload, cspm_policy_payload, cspm_scan_payload from ._device_control_policy import device_policy_payload, default_device_policy_config_payload from ._falconx import falconx_payload +from ._filevantage import ( + filevantage_rule_group_payload, + filevantage_rule_payload, + filevantage_policy_payload, + filevantage_scheduled_exclusion_payload + ) from ._mssp import mssp_payload from ._firewall import ( firewall_policy_payload, @@ -91,5 +97,6 @@ "extraction_payload", "simple_action_parameter", "network_locations_metadata_payload", "network_locations_create_payload", "scheduled_scan_payload", "token_settings_payload", "recon_export_job_payload", "default_device_policy_config_payload", "registry_payload", - "gcp_registration_payload" + "gcp_registration_payload", "filevantage_rule_group_payload", "filevantage_rule_payload", + "filevantage_policy_payload", "filevantage_scheduled_exclusion_payload" ] diff --git a/src/falconpy/_payload/_filevantage.py b/src/falconpy/_payload/_filevantage.py new file mode 100644 index 000000000..5dfc09fbc --- /dev/null +++ b/src/falconpy/_payload/_filevantage.py @@ -0,0 +1,163 @@ +"""Internal payload handling library - Falcon X Sandbox. + + _______ __ _______ __ __ __ +| _ .----.-----.--.--.--.--| | _ | |_.----|__| |--.-----. +|. 1___| _| _ | | | | _ | 1___| _| _| | <| -__| +|. |___|__| |_____|________|_____|____ |____|__| |__|__|__|_____| +|: 1 | |: 1 | +|::.. . | CROWDSTRIKE FALCON |::.. . | FalconPy +`-------' `-------' + +OAuth2 API - Customer SDK + +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to +""" + + +def filevantage_rule_group_payload(passed_keywords: dict) -> dict: + """Craft a properly formatted FileVantage rule group body payload. + + { + "description": "string", + "id": "string", + "name": "string", + "type": "string" + } + """ + returned = {} + keys = ["description", "id", "name", "type"] + for key in keys: + if passed_keywords.get(key, None): + returned[key] = passed_keywords.get(key, None) + + return returned + +def filevantage_policy_payload(passed_keywords: dict) -> dict: + """Craft a properly formatted FileVantage policy body payload. + + { + "description": "string", + "id": "string", + "name": "string", + "platform": "string", + "enabled": boolean + } + """ + returned = {} + keys = ["description", "id", "name", "platform"] + for key in keys: + if passed_keywords.get(key, None): + returned[key] = passed_keywords.get(key, None) + + if passed_keywords.get("enabled", None) is not None: + returned[key] = passed_keywords.get("enabled", None) + + return returned + +def filevantage_scheduled_exclusion_payload(passed_keywords: dict) -> dict: + """Craft a properly formatted FileVantage scheduled exclusion body payload. + + { + "description": "string", + "id": "string", + "name": "string", + "policy_id": "string", + "processes": "string", + "schedule_end": "string", + "schedule_start": "string", + "users": "string" + } + """ + returned = {} + keys = ["description", "id", "name", "policy_id", "processes", + "schedule_end", "schedule_start", "users" + ] + for key in keys: + if passed_keywords.get(key, None): + returned[key] = passed_keywords.get(key, None) + + return returned + +def filevantage_rule_payload(passed_keywords: dict) -> dict: + """Craft a properly formatted FileVantage rule body payload. + + { + "created_timestamp": "string", + "depth": "string", + "description": "string", + "exclude": "string", + "exclude_processes": "string", + "exclude_users": "string", + "id": "string", + "include": "string", + "include_processes": "string", + "include_users": "string", + "modified_timestamp": "string", + "path": "string", + "precedence": integer, + "rule_group_id": "string", + "severity": "string", + "type": "string", + "watch_attributes_directory_changes": boolean, + "watch_attributes_file_changes": boolean, + "watch_create_directory_changes": boolean, + "watch_create_file_changes": boolean, + "watch_create_key_changes": boolean, + "watch_delete_directory_changes": boolean, + "watch_delete_file_changes": boolean, + "watch_delete_key_changes": boolean, + "watch_delete_value_changes": boolean, + "watch_permissions_directory_changes": boolean, + "watch_permissions_file_changes": boolean, + "watch_rename_directory_changes": boolean, + "watch_rename_file_changes": boolean, + "watch_rename_key_changes": boolean, + "watch_set_value_changes": boolean, + "watch_write_file_changes": boolean + } + """ + returned = {} + keys = ["created_timestamp", "depth", "description", "exclude", "exclude_processes", + "exclude_users", "id", "include", "include_processes", "include_users", + "modified_timestamp", "path", "rule_group_id", "severity", "type", + ] + bool_int_keys = ["watch_attributes_directory_changes", "watch_attributes_file_changes", + "watch_create_directory_changes", "watch_create_file_changes", + "watch_create_key_changes", "watch_delete_directory_changes", + "watch_delete_file_changes", "watch_delete_key_changes", + "watch_delete_value_changes", "watch_permissions_directory_changes", + "watch_permissions_file_changes", "watch_rename_directory_changes", + "watch_rename_file_changes", "watch_rename_key_changes", + "watch_set_value_changes", "watch_write_file_changes", "precedence" + ] + for key in keys: + if passed_keywords.get(key, None): + returned[key] = passed_keywords.get(key, None) + for key in bool_int_keys: + if passed_keywords.get(key, None) is not None: + returned[key] = passed_keywords.get(key, None) + + return returned diff --git a/src/falconpy/filevantage.py b/src/falconpy/filevantage.py index 9b74e5b06..69e86faaa 100644 --- a/src/falconpy/filevantage.py +++ b/src/falconpy/filevantage.py @@ -35,7 +35,14 @@ For more information, please refer to """ +# pylint: disable=C0302 from typing import Dict, Union +from ._payload import ( + filevantage_rule_group_payload, + filevantage_rule_payload, + filevantage_policy_payload, + filevantage_scheduled_exclusion_payload + ) from ._util import process_service_request, force_default, handle_single_argument from ._service_class import ServiceClass from ._endpoint._filevantage import _filevantage_endpoints as Endpoints @@ -80,6 +87,850 @@ def get_changes(self: object, *args, parameters: dict = None, **kwargs) -> Dict[ params=handle_single_argument(args, parameters, "ids") ) + @force_default(defaults=["parameters"], default_types=["dict"]) + def update_policy_host_groups(self: object, + parameters: dict = None, + **kwargs + ) -> Dict[str, Union[int, dict]]: + """Manage host groups assigned to a policy. + + Keyword arguments: + action -- The action to perform on the provided IDs. (String) + Allowed values: assign or unassign. + policy_id -- The ID of the policy to perform the action on. (String) + ids -- One or more host groups IDs. (String or List of strings) + parameters - full parameters payload, not required if using other keywords. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updatePolicyHostGroups + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updatePolicyHostGroups", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def update_policy_precedence(self: object, + parameters: dict = None, + **kwargs + ) -> Dict[str, Union[int, dict]]: + """Updates the policy precedence for all policies of a specific type. + + Requests that do no represent all IDs of the provided policy type will not be processed. + + Keyword arguments: + type -- The policy type to set the precedence order for. (String) + Allowed values: Windows, Linux, or Mac + ids -- Procedence of the policies for the provided type. (String or List of strings) + parameters - full parameters payload, not required if using other keywords. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updatePolicyPrecedence + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updatePolicyPrecedence", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def update_policy_rule_groups(self: object, + parameters: dict = None, + **kwargs + ) -> Dict[str, Union[int, dict]]: + """Manage the rule groups assigned to the policy or set the rule group precedence. + + Rule groups must be of the same type as the policy they are being added to: + WindowsRegistry and WindowsFiles groups can be added to a Windows policy. + LinuxFiles groups can be added to a Linux policy. + MacFiles groups can be added to a Max policy. + When setting rule group precedence, the prcedence for ALL rule group IDs within the + policy must be provided. + + Keyword arguments: + action -- The action to perform with the provided IDs. (String) + Allowed values: assign, unassign, precedence + policy_id -- The ID of teh policy for which to perform the action. (String) + ids -- One or more rule group IDs. (String or List of strings) + For the precedence action, precedence is controlled by the order of the IDs + in the list provided. + parameters - full parameters payload, not required if using other keywords. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updatePolicyRuleGroups + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updatePolicyRuleGroups", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def get_policies(self: object, *args, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieves the configuration for one or more policies. + + Keyword arguments: + ids -- List of policy IDs to retrieve. String or list of strings. (Max: 500) + parameters -- full parameters payload, not required if ids keyword is provided. + + Arguments: When not specified, the first argument to this method is assumed to be 'ids'. + All others are ignored. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/getPolicies + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="getPolicies", + keywords=kwargs, + params=handle_single_argument(args, parameters, "ids") + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def create_policy(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Creates a new policy of the specified type. + + New policies are always added at the end of the precedence list for the provided policy type. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "name": "string", + "platform": "string", + } + description -- The policy description. (String, 0-500 characters.) + platform -- Policy platform. (String) + Allowed values: Windows, Linux or Mac + name -- Name of the policy. (String, 1-100 characters.) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: POST + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/createPolicies + """ + if not body: + body = filevantage_policy_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="createPolicies", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def delete_policies(self: object, *args, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Deletes one or more policies. Only disabled policies can be deleted. + + Keyword arguments: + ids -- List of policy IDs to delete. String or list of strings. (Max: 500) + parameters -- full parameters payload, not required if other keywords are provided. + + Arguments: When not specified, the first argument to this method is assumed to be 'ids'. + All others are ignored. + + Returns: dict object containing API response. + + HTTP Method: DELETE + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/deletePolicies + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="deletePolicies", + keywords=kwargs, + params=handle_single_argument(args, parameters, "ids") + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def update_policies(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Updates the general information of the provided policy. + + Only name, description, and enabled status of the policy is allowed to be update. + Rule and host group assignment is performed via their respective update end points. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "id": "string", + "name": "string", + "enabled": boolean, + } + description -- The policy description. (String, 0-500 characters.) + id -- ID of the policy to be updated. (String) + name -- Name of the policy. (String, 1-100 characters.) + enabled -- Enablement status of the policy. Boolean. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updatePolicies + """ + if not body: + body = filevantage_policy_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updatePolicies", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def get_scheduled_exclusions(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieves the configuration for one or more scheduled exclusions within the provided policy. + + Scheduled exclusions within the provided policy that match a provided ID will be returned. + + Keyword arguments: + ids -- List of rule IDs to retrieve. String or list of strings. (Max: 500) + parameters -- full parameters payload, not required if ids keyword is provided. + policy_id -- Rule group from which to retrieve the rule configuration. (String) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/getScheduledExclusions + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="getScheduledExclusions", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def create_scheduled_exclusions(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + r"""Creates a new scheduled exclusion within the provided policy. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "name": "string", + "policy_id": "string", + "processes": "string", + "schedule_end": "string", + "schedule_start": "string", + "users": "string" + } + description -- The scheduled exclusion description. (String, 0-500 characters.) + name -- Name of the scheduled exclusion. (String, 1-100 characters.) + policy_id -- ID of the policy the scheduled exclusion is assigned. (String) + users -- Comma delimited list of users to NOT monitor changes. (String, 1-500 characters) + `admin*` excludes changes made by all usernames that begin with admin. + Falcon GLOB syntax is supported. + processes - Comma delimited list of processes to NOT monitor changes. (String, 1-500 characters) + `**\RunMe.exe` or `**/RunMe.sh` excludes changes made by RunMe.exe + or RunMe.sh in any location. + schedule_start - Indicates the start of the schedule. (String, RFC3339 format, Required) + schedule_end - Indicates the end of the schedule. (String, RFC3339 format) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: POST + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/createScheduledExclusions + """ + if not body: + body = filevantage_scheduled_exclusion_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="createScheduledExclusions", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def delete_scheduled_exclusions(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Deletes one or more scheduled exclusions from the specified policy. + + Scheduled exclusions that match the provided ID will be deleted form the provided policy. + + Keyword arguments: + ids -- List of rule group IDs to delete. String or list of strings. (Max: 500 characters) + parameters -- full parameters payload, not required if other keywords are provided. + policy_id -- The ID of the rule group from which the scheduled exclusions will be deleted. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: DELETE + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/deleteScheduledExclusions + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="deleteScheduledExclusions", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def update_scheduled_exclusions(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + r"""Updates the provided scheduled exclusion configuration within the provided policy. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "id": "string", + "name": "string", + "policy_id": "string", + "processes": "string", + "schedule_end": "string", + "schedule_start": "string", + "users": "string" + } + description -- The scheduled exclusion description. (String, 0-500 characters.) + id -- ID of the scheduled exclusion to be updated. (String) + name -- Name of the scheduled exclusion. (String, 1-100 characters.) + policy_id -- ID of the policy the scheduled exclusion is assigned. (String) + users -- Comma delimited list of users to NOT monitor changes. (String, 1-500 characters) + `admin*` excludes changes made by all usernames that begin with admin. + Falcon GLOB syntax is supported. + processes - Comma delimited list of processes to NOT monitor changes. (String, 1-500 characters) + `**\RunMe.exe` or `**/RunMe.sh` excludes changes made by RunMe.exe + or RunMe.sh in any location. + schedule_start - Indicates the start of the schedule. (String, RFC3339 format, Required) + schedule_end - Indicates the end of the schedule. (String, RFC3339 format) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updateScheduledExclusions + """ + if not body: + body = filevantage_scheduled_exclusion_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updateScheduledExclusions", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def update_rule_group_precedence(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Updates the rule precedence for all rules in the identified rule group. + + The IDs for ALL rules contained within the rule group msut be specified in the desired + precedence order. Requests that do not represent all IDs will not be processed. + + Keyword arguments: + ids -- List of rule IDs to retrieve. String or list of strings. (Max: 500) + parameters -- full parameters payload, not required if ids keyword is provided. + rule_group_id -- Rule group from which to retrieve the rule configuration. (String) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updateRuleGroupPrecedence + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updateRuleGroupPrecedence", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def get_rules(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieves the configuration for one or more rules. + + Rules within the provided rule group ID that match a provided ID will be returned. + + Keyword arguments: + ids -- List of rule IDs to retrieve. String or list of strings. (Max: 500) + parameters -- full parameters payload, not required if ids keyword is provided. + rule_group_id -- Rule group from which to retrieve the rule configuration. (String) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/getRules + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="getRules", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def create_rule(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + r"""Creates a new rule configuration within the specified group. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "created_timestamp": "string", + "depth": "string", + "description": "string", + "exclude": "string", + "exclude_processes": "string", + "exclude_users": "string", + "id": "string", + "include": "string", + "include_processes": "string", + "include_users": "string", + "modified_timestamp": "string", + "path": "string", + "precedence": 0, + "rule_group_id": "string", + "severity": "string", + "type": "string", + "watch_attributes_directory_changes": true, + "watch_attributes_file_changes": true, + "watch_create_directory_changes": true, + "watch_create_file_changes": true, + "watch_create_key_changes": true, + "watch_delete_directory_changes": true, + "watch_delete_file_changes": true, + "watch_delete_key_changes": true, + "watch_delete_value_changes": true, + "watch_permissions_directory_changes": true, + "watch_permissions_file_changes": true, + "watch_rename_directory_changes": true, + "watch_rename_file_changes": true, + "watch_rename_key_changes": true, + "watch_set_value_changes": true, + "watch_write_file_changes": true + } + description -- The rule description. (String, 0-500 characters.) + rule_group_id -- Group ID containing the group configuration. (String) + path -- the file system or registry path to monitor. (String, 1-250 characters) + All paths must end with the path separator, e.g. c:\windows\ /usr/bin/ + severity -- to categorize change events produced by this rule. (String) + Allowed values: Low, Medium, High or Critical + depth -- recursion levels below the base path to monitor. (String) + Allowed values: 1, 2, 3, 4, 5 or ANY + precedence -- the order in which rules will be evaluated starting with 1. + Specifying a precedence value that is already set for another rule + in the group will result this rule being placed before that existing rule. + include -- the files, directories, registry keys, or registry values that will be monitored. (String). + Falcon GLOB syntax is supported. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude -- the files, directories, registry keys, or registry values that will NOT be monitored. (String). + Falcon GLOB syntax is supported. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + include_users -- the changes performed by specific users that will be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude_users -- the changes performed by specific users that will NOT be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + include_processes -- the changes performed by specific processes that will be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude_users -- the changes performed by specific processes that will be NOT monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + watch_delete_directory_changes -- File system directory monitoring. Boolean. + watch_create_directory_changes -- File system directory monitoring. Boolean. + watch_rename_directory_changes -- File system directory monitoring. Boolean. + watch_attributes_directory_changes -- File system directory monitoring. Boolean. + macOS is not supported at this time. + watch_permissions_directory_changes -- File system directory monitoring. Boolean. + macOS is not supported at this time. + watch_rename_file_changes -- File system file monitoring. Boolean. + watch_write_file_changes -- File system file monitoring. Boolean. + watch_create_file_changes -- File system file monitoring. Boolean. + watch_delete_file_changes -- File system file monitoring. Boolean. + watch_attributes_file_changes -- File system file monitoring. Boolean. + macOS is not supported at this time. + watch_permissions_file_changes -- File system file monitoring. Boolean. + macOS is not supported at this time. + watch_create_key_changes -- Windows registry key and value monitoring. Boolean. + watch_delete_key_changes -- Windows registry key and value monitoring. Boolean. + watch_rename_key_changes -- Windows registry key and value monitoring. Boolean. + watch_set_value_changes -- Windows registry key and value monitoring. Boolean. + watch_delete_value_changes -- Windows registry key and value monitoring. Boolean. + watch_create_file_changes -- Windows registry key and value monitoring. Boolean. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: POST + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/createRules + """ + if not body: + body = filevantage_rule_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="createRules", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def delete_rules(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Deletes one or more rules from the specified rule group. + + Rules that match a provided ID will be deleted form the provided rule group ID. + + Keyword arguments: + ids -- List of rule group IDs to delete. String or list of strings. + parameters -- full parameters payload, not required if other keywords are provided. + rule_group_id -- The ID of the rule group from which the rules will be deleted. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: DELETE + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/deleteRules + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="deleteRules", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def update_rule(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + r"""Updates the provided rule configuration within the specified rule group. + + The rule must exist within the specified rule group. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "created_timestamp": "string", + "depth": "string", + "description": "string", + "exclude": "string", + "exclude_processes": "string", + "exclude_users": "string", + "id": "string", + "include": "string", + "include_processes": "string", + "include_users": "string", + "modified_timestamp": "string", + "path": "string", + "precedence": 0, + "rule_group_id": "string", + "severity": "string", + "type": "string", + "watch_attributes_directory_changes": true, + "watch_attributes_file_changes": true, + "watch_create_directory_changes": true, + "watch_create_file_changes": true, + "watch_create_key_changes": true, + "watch_delete_directory_changes": true, + "watch_delete_file_changes": true, + "watch_delete_key_changes": true, + "watch_delete_value_changes": true, + "watch_permissions_directory_changes": true, + "watch_permissions_file_changes": true, + "watch_rename_directory_changes": true, + "watch_rename_file_changes": true, + "watch_rename_key_changes": true, + "watch_set_value_changes": true, + "watch_write_file_changes": true + } + description -- The rule description. (String, 0-500 characters.) + id -- ID of the rule to be updated. (String) + rule_group_id -- Group ID containing the group configuration. (String) + path -- the file system or registry path to monitor. (String, 1-250 characters) + All paths must end with the path separator, e.g. c:\windows\ /usr/bin/ + severity -- to categorize change events produced by this rule. (String) + Allowed values: Low, Medium, High or Critical + depth -- recursion levels below the base path to monitor. (String) + Allowed values: 1, 2, 3, 4, 5 or ANY + precedence -- the order in which rules will be evaluated starting with 1. + Specifying a precedence value that is already set for another rule + in the group will result this rule being placed before that existing rule. + include -- the files, directories, registry keys, or registry values that will be monitored. (String). + Falcon GLOB syntax is supported. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude -- the files, directories, registry keys, or registry values that will NOT be monitored. (String). + Falcon GLOB syntax is supported. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + include_users -- the changes performed by specific users that will be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude_users -- the changes performed by specific users that will NOT be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + include_processes -- the changes performed by specific processes that will be monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + exclude_users -- the changes performed by specific processes that will be NOT monitored. (String). + Falcon GLOB syntax is supported. + macOS is not supported at this time. + Allowed rule group configuration is based on the type of rule + the rule group is added to. + watch_delete_directory_changes -- File system directory monitoring. Boolean. + watch_create_directory_changes -- File system directory monitoring. Boolean. + watch_rename_directory_changes -- File system directory monitoring. Boolean. + watch_attributes_directory_changes -- File system directory monitoring. Boolean. + macOS is not supported at this time. + watch_permissions_directory_changes -- File system directory monitoring. Boolean. + macOS is not supported at this time. + watch_rename_file_changes -- File system file monitoring. Boolean. + watch_write_file_changes -- File system file monitoring. Boolean. + watch_create_file_changes -- File system file monitoring. Boolean. + watch_delete_file_changes -- File system file monitoring. Boolean. + watch_attributes_file_changes -- File system file monitoring. Boolean. + macOS is not supported at this time. + watch_permissions_file_changes -- File system file monitoring. Boolean. + macOS is not supported at this time. + watch_create_key_changes -- Windows registry key and value monitoring. Boolean. + watch_delete_key_changes -- Windows registry key and value monitoring. Boolean. + watch_rename_key_changes -- Windows registry key and value monitoring. Boolean. + watch_set_value_changes -- Windows registry key and value monitoring. Boolean. + watch_delete_value_changes -- Windows registry key and value monitoring. Boolean. + watch_create_file_changes -- Windows registry key and value monitoring. Boolean. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updateRules + """ + if not body: + body = filevantage_rule_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updateRules", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def get_rule_groups(self: object, *args, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieves the rule group details for one or more rule groups. + + Full details of each rule group that matches a provided ID will be returned. + + Keyword arguments: + ids -- List of rule group IDs to retrieve. String or list of strings. + parameters -- full parameters payload, not required if ids keyword is provided. + + Arguments: When not specified, the first argument to this method is assumed to be 'ids'. + All others are ignored. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/getRuleGroups + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="getRuleGroups", + keywords=kwargs, + params=handle_single_argument(args, parameters, "ids") + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def create_rule_group(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Creates a new rule group of the specified type. + + Individual rules can be assigned to a rule group after it has been created. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "type": "string", + "name": "string" + } + description -- The rule group description. (String, 0-500 characters.) + type -- The type of rule group. (String) + Allowed values: WindowsFiles, WindowsRegistry, LinuxFiles or MacFiles. + name -- Name of the rule group. (String, 1-100 characters.) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: POST + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/createRuleGroups + """ + if not body: + body = filevantage_rule_group_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="createRuleGroups", + keywords=kwargs, + body=body + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def delete_rule_groups(self: object, *args, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Delete a set of rule groups by specifying their IDs. + + Keyword arguments: + ids -- List of rule group IDs to delete. String or list of strings. + parameters -- full parameters payload, not required if ids keyword is provided. + + Arguments: When not specified, the first argument to this method is assumed to be 'ids'. + All others are ignored. + + Returns: dict object containing API response. + + HTTP Method: DELETE + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/deleteRuleGroups + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="deleteRuleGroups", + keywords=kwargs, + params=handle_single_argument(args, parameters, "ids") + ) + + @force_default(defaults=["body"], default_types=["dict", "dict"]) + def update_rule_group(self: object, body: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Updates the provided rule group. + + Provides the ability to update the name and description of a rule group. + + Keyword arguments: + body - full body payload in JSON format, not required if using other keywords. + { + "description": "string", + "id": "string", + "name": "string" + } + description -- The rule group description. (String, 0-500 characters.) + id -- ID of the rule group to be updated. (String) + name -- Name of the rule group. (String, 1-100 characters.) + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: PATCH + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/updateRuleGroups + """ + if not body: + body = filevantage_rule_group_payload(passed_keywords=kwargs) + + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="updateRuleGroups", + keywords=kwargs, + body=body + ) + @force_default(defaults=["parameters"], default_types=["dict"]) def query_changes(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: """Search for changes within your environment. Returns one or more change IDs. @@ -118,6 +969,9 @@ def query_changes(self: object, parameters: dict = None, **kwargs) -> Dict[str, def query_changes_scroll(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: """Search for changes within your environment. Returns one or more change IDs. + Returns a list of Falcon FileVantage change IDs filtered, sorted and limited by the query + parameters provided. An unlimited number of results can be retrieved using multiple requests. + Keyword arguments: filter -- The filter expression that should be used to limit the results. FQL syntax. Available filters @@ -152,13 +1006,134 @@ def query_changes_scroll(self: object, parameters: dict = None, **kwargs) -> Dic params=parameters ) + @force_default(defaults=["parameters"], default_types=["dict"]) + def query_policies(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieve the IDs of all rule groups that are of the provided rule group type. + + Rule group ids will be returned sorted by created_timestamp order if a sort parameter + is not provided. + + Keyword arguments: + limit -- The maximum number of ids to return. Defaults to 100 if not specified. + (Integer, 1-500) + offset -- The first item to return, where 0 is the latest item. (Integer) + Use with the limit parameter to manage pagination of results. + parameters - full parameters payload, not required if using other keywords. + sort -- The property to sort by. FQL syntax. (String) + Supported options: precedence, created_timestamp or modified_timestamp. + (e.g. created_timestamp|asc, modified_timestamp|desc, etc.) + type -- The type of policies to retrieve. (String) + Allowed values: Windows, Linux, or Mac. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/queryPolicies + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="queryPolicies", + keywords=kwargs, + params=parameters + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def query_scheduled_exclusions(self: object, *args, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieve the IDs of all scheduled exclusions contained within the provided policy ID. + + Use the IDs from this response to fetch the rules with get_rules. + + Keyword arguments: + policy_id -- The ID of the policy to retrieve the scheduled exclusion IDs for. (String) + + Arguments: When not specified, the first argument to this method is assumed to be + 'policy_ids'. All others are ignored. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/queryScheduledExclusions + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="queryScheduledExclusions", + keywords=kwargs, + params=handle_single_argument(args, parameters, "policy_ids") + ) + + @force_default(defaults=["parameters"], default_types=["dict"]) + def query_rule_groups(self: object, parameters: dict = None, **kwargs) -> Dict[str, Union[int, dict]]: + """Retrieve the IDs of all rule groups that are of the provided rule group type. + + Rule group ids will be returned sorted by created_timestamp order if a sort parameter + is not provided. + + Keyword arguments: + limit -- The maximum number of ids to return. Defaults to 100 if not specified. + (Integer, 1-500) + offset -- The first item to return, where 0 is the latest item. (Integer) + Use with the limit parameter to manage pagination of results. + parameters - full parameters payload, not required if using other keywords. + sort -- The property to sort by. FQL syntax. (String) + Supported options: created_timestamp or modified_timestamp. + (e.g. created_timestamp|asc, modified_timestamp|desc, etc.) + type -- The rule group type to retrieve the IDs for. (String) + Allowed values: WindowsFiles, WindowsRegistry, LinuxFiles, or MacFiles. + + This method only supports keywords for providing arguments. + + Returns: dict object containing API response. + + HTTP Method: GET + + Swagger URL + https://assets.falcon.crowdstrike.com/support/api/swagger.html#/filevantage/queryRuleGroups + """ + return process_service_request( + calling_object=self, + endpoints=Endpoints, + operation_id="queryRuleGroups", + keywords=kwargs, + params=parameters + ) + # This method name aligns to the operation ID in the API but # does not conform to snake_case / PEP8 and is defined here # for backwards compatibility / ease of use purposes + updatePolicyHostGroups = update_policy_host_groups + updatePolicyPrecedence = update_policy_precedence + updatePolicyRuleGroups = update_policy_rule_groups + getPolicies = get_policies + createPolicies = create_policy + deletePolicies = delete_policies + updatePolicies = update_policies + getScheduledExclusions = get_scheduled_exclusions + createScheduledExclusions = create_scheduled_exclusions + deleteScheduledExclusions = delete_scheduled_exclusions + updateScheduledExclusions = update_scheduled_exclusions + updateRuleGroupPrecedence = update_rule_group_precedence + getRules = get_rules + createRules = create_rule + deleteRules = delete_rules + updateRules = update_rule + getRuleGroups = get_rule_groups + createRuleGroups = create_rule_group + deleteRuleGroups = delete_rule_groups + updateRuleGroups = update_rule_group getChanges = get_changes queryChanges = query_changes highVolumeQueryChanges = query_changes_scroll - + queryRuleGroups = query_rule_groups + queryScheduledExclusions = query_scheduled_exclusions + queryPolicies = query_policies # The legacy name for this class does not conform to PascalCase / PEP8 # It is defined here for backwards compatibility purposes only. diff --git a/tests/test_filevantage.py b/tests/test_filevantage.py index 370b0797f..9a90af2e0 100644 --- a/tests/test_filevantage.py +++ b/tests/test_filevantage.py @@ -15,7 +15,7 @@ auth = Authorization.TestAuthorization() config = auth.getConfigObject() falcon = FileVantage(auth_object=config) -AllowedResponses = [200, 202, 429] # Adding rate-limiting as an allowed response for now +AllowedResponses = [200, 202, 400, 404, 429] # Adding rate-limiting as an allowed response for now class TestFileVantage: @@ -45,3 +45,41 @@ def test_get_changes(self): assert bool( falcon.get_changes("12345678")["status_code"] in AllowedResponses ) is True + + def service_filevantage_remaining_tests(self): + + error_checks = True + tests = { + "update_policy_host_groups": falcon.update_policy_host_groups(policy_id="12345678", ids="1", action="unassign"), + "update_policy_precedence": falcon.update_policy_precedence(ids="12345678", type="Windows"), + "update_policy_rule_groups": falcon.update_policy_rule_groups(ids="12345678", policy_id="9876543"), + "get_policies": falcon.get_policies(ids="12345678"), + "create_policy": falcon.create_policy(name="whatevers", enabled=False), + "delete_policies": falcon.delete_policies("12345678"), + "update_policies": falcon.update_policies(id="12345678", description="whatevs", name="whatevs"), + "get_scheduled_exclusions": falcon.get_scheduled_exclusions(ids="12345678", policy_id="12345678"), + "create_scheduled_exclusions": falcon.create_scheduled_exclusions(name="whatevers"), + "delete_scheduled_exclusions": falcon.delete_scheduled_exclusions(ids="12345678", policy_id="12345678"), + "update_scheduled_exclusions": falcon.update_scheduled_exclusions(), + "update_rule_group_precedence": falcon.update_rule_group_precedence(ids="1,2,3,4", rule_group_id="12345678"), + "get_rules": falcon.get_rules(ids="12345678", rule_group_id="12345678"), + "create_rule": falcon.create_rule(watch_attributes_directory_changes=True, description="whatevers"), + "delete_rule": falcon.delete_rules(ids="12345678", rule_group_id="12345678"), + "update_rule": falcon.update_rule(), + "get_rule_groups": falcon.get_rule_groups("12345678"), + "create_rule_group": falcon.create_rule_group(name="Whatevers"), + "delete_rule_groups": falcon.delete_rule_groups("12345678"), + "update_rule_group" : falcon.update_rule_group(), + "query_policies": falcon.query_policies(), + "query_scheduled_exclusions": falcon.query_scheduled_exclusions(), + "query_rule_groups": falcon.query_rule_groups(type="WindowsFiles") + } + for key in tests: + if tests[key]["status_code"] not in AllowedResponses: + # print(f"{key}: {tests[key]}") + error_checks = False + + return error_checks + + def test_remaining_functionality(self): + assert self.service_filevantage_remaining_tests() is True \ No newline at end of file