crowdstrike.falcon.sensor_update_policy module – Manage Falcon sensor update policies

Note

This module is part of the crowdstrike.falcon collection (version 4.9.1).

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.sensor_update_policy.

New in crowdstrike.falcon 4.10.0

Synopsis

  • Create, update, delete, and manage Falcon sensor update policies.

  • Control sensor version updates, uninstall protection, and update schedules.

  • Manage host group assignments for sensor update policies.

  • Provides idempotent operations that only make changes when necessary.

Requirements

The below requirements are needed on the host that executes this module.

  • Sensor update policies [READ, WRITE] API scope

  • crowdstrike-falconpy >= 1.3.0

  • python >= 3.6

Parameters

Parameter

Comments

auth

dictionary

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.

access_token

string

The OAuth2 access token to use for authentication.

cloud

string

The CrowdStrike cloud region to use.

This can differ from the module’s cloud argument due to autodiscovery.

build

string

The sensor version setting for the policy.

Can be a specific sensor build string or version number from the builds API.

Use sensor_update_builds_info module to get available build values for your tenant.

Build format examples: 20008|n-1|tagged|1, 19320|Auto, 17804.

For sensor updates disabled, omit this parameter entirely.

Note: Simple values like n-1, tagged are not supported by the API.

client_id

aliases: falcon_client_id

string

The CrowdStrike API client ID to use.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_ID environment variable can also be used.

client_secret

aliases: falcon_client_secret

string

The CrowdStrike API secret that corresponds to the client ID.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_SECRET environment variable can also be used.

cloud

string

The CrowdStrike cloud region to use.

All clouds are automatically discovered if not specified, except for the us-gov-1 cloud.

The FALCON_CLOUD environment variable can also be used.

Choices:

  • "us-1" ← (default)

  • "us-2"

  • "us-gov-1"

  • "eu-1"

description

string

A description for the sensor update policy.

Only used when state=present.

enabled

boolean

Whether the policy should be enabled.

Policies must be enabled to affect hosts.

New policies are disabled by default.

Choices:

  • false

  • true

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

host_group_action

string

The action to perform with the host groups specified in host_groups.

add assigns host groups to the policy.

remove unassigns host groups from the policy.

Requires host_groups to be specified.

Choices:

  • "add"

  • "remove"

host_groups

list / elements=string

List of host group IDs to add to or remove from the policy.

Use with host_group_action to specify the operation.

Only applicable for existing policies and when state=present.

member_cid

string

The CrowdStrike member CID for MSSP authentication.

See the Falcon documentation for more information about API clients.

The FALCON_MEMBER_CID environment variable can also be used.

name

string

The name of the sensor update policy.

Preferred method for idempotent operations - works for create, update, and delete.

When used with platform_name, provides true Ansible idempotency across the entire policy lifecycle.

Cannot be used to rename existing policies.

platform_name

string

The operating system platform for the policy.

Required when using name for policy identification (create, update, or delete).

Cannot be changed after policy creation.

Choices:

  • "Windows"

  • "Mac"

  • "Linux"

scheduler

dictionary

Time blocks during which to prohibit sensor cloud updates.

Dictionary containing scheduler configuration.

Keys: enabled (bool), timezone (str), schedules (list).

Each schedule contains start, end, and days (0=Sunday, 6=Saturday).

sensor_update_policy

string

The ID of an existing sensor update policy.

Alternative to name + platform_name for identifying existing policies.

Provided for backward compatibility and when the policy ID is already known.

state

string

The desired state of the sensor update policy.

present ensures the sensor update policy exists with the specified configuration.

absent ensures the sensor update policy does not exist.

Choices:

  • "present" ← (default)

  • "absent"

uninstall_protection

string

The uninstall protection setting for hosts with this policy.

ENABLED protects the sensor from unauthorized uninstallation.

DISABLED allows end users to uninstall the sensor.

MAINTENANCE_MODE enables maintenance mode for the sensor.

Choices:

  • "ENABLED"

  • "DISABLED"

  • "MAINTENANCE_MODE"

user_agent

string

Custom User-Agent string to use for requests to the API.

The user agent string is prepended to the default user agent string (crowdstrike-ansible/<version>).

See RFC 7231 for more information.

The FALCON_USER_AGENT environment variable can also be used.

Notes

Note

  • Idempotency: This module is idempotent and will only make changes when the current state differs from the desired state.

  • Preferred Pattern: Use name + platform_name for true Ansible idempotency. The same task definition can handle create, update, and delete operations by changing only the state parameter.

  • Alternative Pattern: Use sensor_update_policy ID for direct policy identification when the policy ID is already known or for backward compatibility.

  • Platform Types: The platform type cannot be changed after creation. To change a policy’s platform, delete the existing policy and create a new one.

  • Policy Deletion: Policies must be disabled before they can be deleted. The module handles this automatically.

  • Host Group Management: Adding or removing host groups only works with existing policies. Host group operations are performed after policy creation/update operations.

Examples

# PREFERRED IDEMPOTENT PATTERNS (using name + platform_name)

- name: Create a Windows sensor update policy (idempotent)
  crowdstrike.falcon.sensor_update_policy:
    name: "Windows Production Policy"
    platform_name: Windows
    description: "Windows hosts production sensor policy"
    build: "20008|n-1|tagged|1"
    uninstall_protection: ENABLED
    state: present

- name: Update the same policy (same task definition, just different values)
  crowdstrike.falcon.sensor_update_policy:
    name: "Windows Production Policy"
    platform_name: Windows
    description: "UPDATED: Windows hosts production sensor policy"
    build: "19320|Auto"
    uninstall_protection: ENABLED
    enabled: true
    state: present

- name: Delete the same policy (same task definition, just state=absent)
  crowdstrike.falcon.sensor_update_policy:
    name: "Windows Production Policy"
    platform_name: Windows
    state: absent

- name: Create a Linux policy with scheduler (idempotent)
  crowdstrike.falcon.sensor_update_policy:
    name: "Linux Maintenance Policy"
    platform_name: Linux
    description: "Linux hosts with maintenance windows"
    build: "18202|n-1|tagged|5"
    scheduler:
      enabled: true
      timezone: "America/Chicago"
      schedules:
        - start: "08:00"
          end: "14:00"
          days: [1, 2, 3, 4, 5]  # Weekdays
    state: present

- name: Create policy with sensor updates disabled (omit build parameter)
  crowdstrike.falcon.sensor_update_policy:
    name: "No Updates Policy"
    platform_name: "Mac"
    description: "Mac hosts with updates disabled"
    uninstall_protection: ENABLED
    # Omit 'build' parameter to disable sensor updates
    state: present

# ALTERNATIVE PATTERNS (using sensor_update_policy ID)
# These examples show the alternative approach using policy IDs
# for backward compatibility or when the ID is already known.

- name: Update an existing policy by ID
  crowdstrike.falcon.sensor_update_policy:
    sensor_update_policy: "12345678901234567890abcdef123456"
    description: "Updated description for production policy"

- name: Enable a sensor update policy by ID
  crowdstrike.falcon.sensor_update_policy:
    sensor_update_policy: "12345678901234567890abcdef123456"
    enabled: true

- name: Delete a sensor update policy by ID
  crowdstrike.falcon.sensor_update_policy:
    sensor_update_policy: "12345678901234567890abcdef123456"
    state: absent

# HOST GROUP MANAGEMENT
# Host group operations work with both identification patterns

- name: Add host groups to a policy (using name)
  crowdstrike.falcon.sensor_update_policy:
    name: "Windows Production Policy"
    platform_name: Windows
    host_groups:
      - "d78cd791785442a98ec75249d8c385dd"
      - "a1b2c3d4e5f6789012345678901234ab"
    host_group_action: add

- name: Remove host groups from a policy (using ID)
  crowdstrike.falcon.sensor_update_policy:
    sensor_update_policy: "12345678901234567890abcdef123456"
    host_groups:
      - "d78cd791785442a98ec75249d8c385dd"
    host_group_action: remove

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

host_group_results

dictionary

Results of host group add/remove operations.

Returned: when host_group_action is performed

failed_groups

list / elements=dictionary

List of errors for host groups that failed to be processed.

Returned: when there are failures

Sample: [{"code": 404, "message": "Host group not found"}]

successful_groups

list / elements=string

List of host group IDs that were successfully processed.

Returned: success

Sample: ["d78cd791785442a98ec75249d8c385dd"]

sensor_update_policy

dictionary

Information about the sensor update policy that was created, updated, or managed.

Returned: when state=present

created_by

string

The user who created the policy.

Returned: success

Sample: "user@example.com"

created_timestamp

string

The timestamp when the policy was created.

Returned: success

Sample: "2025-01-01T00:00:00Z"

description

string

The description of the sensor update policy.

Returned: success

Sample: "Windows hosts production sensor policy"

enabled

boolean

Whether the policy is enabled.

Returned: success

Sample: true

groups

list / elements=dictionary

The host groups assigned to the policy.

Returned: success

Sample: []

id

string

The unique identifier of the sensor update policy.

Returned: success

Sample: "12345678901234567890abcdef123456"

modified_by

string

The user who last modified the policy.

Returned: success

Sample: "user@example.com"

modified_timestamp

string

The timestamp when the policy was last modified.

Returned: success

Sample: "2025-01-01T00:00:00Z"

name

string

The name of the sensor update policy.

Returned: success

Sample: "Windows Production Policy"

platform_name

string

The operating system platform the policy applies to.

Returned: success

Sample: "Windows"

settings

dictionary

The policy settings configuration.

Returned: success

build

string

The sensor version setting.

Returned: success

Sample: "n-1"

scheduler

dictionary

The update scheduler configuration.

Returned: when configured

Sample: {"enabled": true, "timezone": "America/Chicago"}

uninstall_protection

string

The uninstall protection setting.

Returned: success

Sample: "ENABLED"

Authors

  • Carlos Matos (@carlosmmatos)