crowdstrike.falcon.prevention_policy module – Manage Falcon prevention policies
Note
This module is part of the crowdstrike.falcon collection (version 4.15.0).
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install crowdstrike.falcon.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: crowdstrike.falcon.prevention_policy.
New in crowdstrike.falcon 4.15.0
Synopsis
Create, update, enable, disable and delete Falcon prevention policies.
The same task creates the prevention policy when it is missing, updates it when it is different, and deletes it with state=absent.
The module finds a policy by policy_id, or by name and platform_name.
The module does not manage the prevention settings or the IOA rule groups of the policy.
Requirements
The below requirements are needed on the host that executes this module.
Host Groups [READ] API scope, only when host_groups adds host groups
Prevention policies [READ, WRITE] API scope
crowdstrike-falconpy >= 1.5.0
python >= 3.12
Parameters
Parameter |
Comments |
|---|---|
The registered result of the crowdstrike.falcon.auth module, or a dictionary containing the access_token and cloud keys. If provided, the client_id, client_secret, member_cid, and cloud options are ignored. Useful when needing to make multiple API calls to avoid rate limiting issues. |
|
The OAuth2 access token to use for authentication. |
|
The CrowdStrike cloud region to use. This can differ from the module’s cloud argument due to autodiscovery. |
|
The CrowdStrike API client ID to use. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike API secret that corresponds to the client ID. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike cloud region to use. All clouds are automatically discovered if not specified, except for the The Choices:
|
|
The description of the prevention policy. An empty string clears the description. When not set, the module does not change the description. |
|
Whether the prevention policy is enabled. A new policy is disabled unless this is When not set, the module does not change it. Choices:
|
|
Extended headers that are prepended to the default headers dictionary. |
|
The IDs of the host groups to assign the prevention policy to. The IDs are compared without regard to case. An ID that is in the list more than once counts once. The module fails before any change when a host group to add does not exist. When not set, the module does not change the host groups of the policy. Ignored with state=absent. |
|
The CrowdStrike member CID for MSSP authentication. See the Falcon documentation for more information about API clients. The |
|
The name of the prevention policy. The module finds an existing policy by this exact name on the platform in platform_name, without regard to case. The module does not change the name of an existing policy. A name that differs only in case finds the same policy. Requires platform_name. Mutually exclusive with policy_id. |
|
The platform of the prevention policy. The value is case-sensitive. A name is unique only for each platform, so the module uses the platform to find the policy by name. The platform of an existing policy cannot change. Required with name. Choices:
|
|
The ID of an existing prevention policy. The ID is compared without regard to case. With state=present, the module fails when the ID does not exist. Mutually exclusive with name and platform_name. |
|
If purge_host_groups=true and host_groups is set, the module removes the host groups of the policy that are not in host_groups. If host_groups is not set, the module does not change the host groups, even if purge_host_groups=true. With host_groups=[] and purge_host_groups=true, the module removes all the host groups of the policy. Choices:
|
|
The desired state of the prevention policy. With state=absent, the module disables an enabled policy before it deletes it, because the API does not delete an enabled policy. Choices:
|
|
Custom User-Agent string to use for requests to the API. The user agent string is prepended to the default user agent string ( See RFC 7231 for more information. The |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: full |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platforms: all |
Target OS/families that can be operated against |
See Also
See also
- crowdstrike.falcon.prevention_policy_info
Get information about Falcon prevention policies.
- crowdstrike.falcon.host_group
Manage Falcon host groups.
- crowdstrike.falcon.host_group_info
Get information about Falcon host groups.
- Prevention Policy API reference
The CrowdStrike API operations that this module uses.
Examples
- name: Create an enabled Windows prevention policy
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
description: "Managed by Ansible"
enabled: true
- name: Update the description of the policy
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
description: "Updated by Ansible"
- name: Disable the policy
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
enabled: false
- name: Assign the policy to two host groups
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
host_groups:
- "abcdef1234567890abcdef1234567890"
- "1234567890abcdef1234567890abcdef"
- name: Set the exact host groups of the policy and remove the others
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
host_groups:
- "abcdef1234567890abcdef1234567890"
purge_host_groups: true
- name: Delete the policy by name and platform
crowdstrike.falcon.prevention_policy:
name: "Example prevention policy"
platform_name: Windows
state: absent
- name: Delete a prevention policy by ID
crowdstrike.falcon.prevention_policy:
policy_id: "12345678901234567890abcdef123456"
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The prevention policy after the change, read again from the API. In check mode, the current policy, or the wanted values when the policy does not exist. Returned: when state=present |
|
The customer ID that the policy belongs to. Returned: success Sample: |
|
The user who created the prevention policy. Returned: success Sample: |
|
The time when the prevention policy was created. Returned: success Sample: |
|
The description of the prevention policy. Can be empty. Returned: success Sample: |
|
Whether the prevention policy is enabled. Returned: success Sample: |
|
The host groups that the policy is assigned to. Returned: success |
|
The assignment rule of the host group. Returned: success Sample: |
|
The user who created the host group. Returned: success Sample: |
|
The time when the host group was created. Returned: success Sample: |
|
The description of the host group. Returned: success Sample: |
|
The type of the host group. Returned: success Sample: |
|
The ID of the host group. Returned: success Sample: |
|
The user who last changed the host group. Returned: success Sample: |
|
The time when the host group was last changed. Returned: success Sample: |
|
The name of the host group. Returned: success Sample: |
|
The ID of the prevention policy. Returned: success Sample: |
|
The custom IOA rule groups that are assigned to the policy. Returned: success |
|
The comment of the last change to the rule group. Returned: success Sample: |
|
The time when the last change to the rule group was committed. Returned: success Sample: |
|
The user who created the rule group. Returned: success Sample: |
|
The time when the rule group was created. Returned: success Sample: |
|
The customer ID that the rule group belongs to. Returned: success Sample: |
|
Whether the rule group is deleted. Returned: success Sample: |
|
The description of the rule group. Returned: success Sample: |
|
Whether the rule group is enabled. Returned: success Sample: |
|
The ID of the rule group. Returned: success Sample: |
|
The user who last changed the rule group. Returned: success Sample: |
|
The time when the rule group was last changed. Returned: success Sample: |
|
The name of the rule group. Returned: success Sample: |
|
The platform of the rule group. Returned: success Sample: |
|
The IDs of the rules in the rule group. Returned: success Sample: |
|
The version of the rule group. Returned: success Sample: |
|
The user who last changed the prevention policy. Returned: success Sample: |
|
The time when the prevention policy was last changed. Returned: success Sample: |
|
The name of the prevention policy. Returned: success Sample: |
|
The platform of the prevention policy. Returned: success Sample: |
|
The prevention settings of the policy, in categories. Returned: success |
|
The name of the settings category. Returned: success Sample: |
|
The settings in the category. Returned: success |
|
The description of the setting. Returned: success Sample: |
|
The ID of the setting. Returned: success Sample: |
|
The name of the setting. Returned: success Sample: |
|
The type of the setting. Returned: success Sample: |
|
The value of the setting. The keys depend on the type of the setting. A Returned: success Sample: |