crowdstrike.falcon.falconctl module – Configure CrowdStrike Falcon Sensor

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.

To use it in a playbook, specify: crowdstrike.falcon.falconctl.

New in crowdstrike.falcon 3.2.0

Synopsis

  • Configures CrowdStrike Falcon Sensor on Linux systems

Parameters

Parameter

Comments

aid

boolean

Whether or not you would like to delete the associated Agent ID.

Useful when preparing a host as a master image for cloning or virtualization.

This applies only to state=absent.

Choices:

  • false

  • true

apd

string

Whether to enable or disable the Falcon sensor to use a proxy.

To enable the proxy, set to 'false'.

Valid Options are: 'true'|'false'|''

aph

string

Specifies the application proxy host to use for Falcon sensor proxy configuration.

app

string

Specifies the application proxy port to use for Falcon sensor proxy configuration.

backend

string

Configure the backend for the Falcon sensor. This was introduced to support the BPF backend.

backend is only available in sensor versions that support the --backend option (>6.46.0).

Valid Options are: 'auto'|'bpf'|'kernel'

billing

string

Specify the (Pay-As-You-Go) billing model for Cloud Workloads.

Falcon for Cloud Workloads (Pay-As-You-Go) is a billing model for your hosts that run in Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure.

For ephemeral workloads in these cloud environments, you pay only for the hours that hosts are active each month metered, rather than a full annual contract price per sensor default.

Valid Options are: 'metered'|'default'|''

cid

string

CrowdStrike Falcon Customer ID (CID).

cloud

string

Specify the cloud region for the Falcon sensor to connect to.

cloud is only available in sensor versions 7.28.0 and above with unified installer support.

This parameter helps the sensor connect to the correct cloud region and can resolve AID generation timeouts.

Valid Options are: 'us-1'|'us-2'|'us-3'|'eu-1'|'us-gov-1'|'us-gov-2'

Choices:

  • "us-1"

  • "us-2"

  • "us-3"

  • "eu-1"

  • "us-gov-1"

  • "us-gov-2"

exclusive

boolean

added in crowdstrike.falcon 4.15.0

Whether to remove all sensor tags not listed in tags_list.

Only valid with state=present. Requires tags_list.

Setting exclusive=true with an empty tags_list clears all sensor tags.

Choices:

  • false ← (default)

  • true

feature

list / elements=string

Configure the Falcon sensor feature flags.

Choices:

  • "none"

  • "enableLog"

  • "disableLogBuffer"

maintenance_token

string

Maintenance token required for sensor operations when uninstall and maintenance protection is enabled.

Required for sensor versions 7.20+ when protection is armed.

Used to disable protection before uninstall, upgrade, or configuration changes.

message_log

string

Whether or not you would like to log messages to disk.

Valid Options are: 'true'|'false'|''

This option is deprecated and will be removed in version 5.0.0 of this collection.

Linux sensors 7.21 and later do not support --message-log. On these sensors, the module skips the option with a warning.

provisioning_token

string

Installation tokens prevent unauthorized hosts from being accidentally or maliciously added to your customer ID (CID).

Optional security measure for your CID.

This parameter requires supplying a cid.

state

string / required

Ensures that requested parameters are removed (absent) or added (present) to the Falcon sensor.

Choices:

  • "absent"

  • "present"

tags

string

Sensor grouping tags are optional, user-defined identifiers you can use to group and filter hosts.

To assign multiple tags, separate tags with commas.

Tags can include alphanumerics and these characters /, -, _, ., and @.

The combined length of all tags for a host, including comma separators, cannot exceed 256 characters.

Replaces all existing tags. Use tags_list to add or remove individual tags.

Mutually exclusive with tags_list.

tags_list

list / elements=string

added in crowdstrike.falcon 4.15.0

A list of sensor grouping tags to ensure are present or absent, without affecting other existing tags.

With state=present, the listed tags are added to the existing tags.

With state=absent, only the listed tags are removed from the existing tags. If no tags remain, the sensor’s tags are cleared.

Each tag can include alphanumerics and these characters /, -, _, ., and @.

Tags are case-sensitive. For example, web and WEB are two different tags.

The combined length of all resulting tags, including comma separators, cannot exceed 256 characters.

The tag change runs as a separate falconctl call after any other options in the same task. If that call fails, the other options have already been applied.

Mutually exclusive with tags.

trace

string

Configure the appropriate trace level.

Choices:

  • "none"

  • "err"

  • "warn"

  • "info"

  • "debug"

Examples

- name: Set CrowdStrike Falcon CID
  crowdstrike.falcon.falconctl:
    state: present
    cid: 1234567890ABCDEF1234567890ABCDEF-12

- name: Set CrowdStrike Falcon CID with Provisioning Token
  crowdstrike.falcon.falconctl:
    state: present
    cid: 1234567890ABCDEF1234567890ABCDEF-12
    provisioning_token: 12345678

- name: Set CrowdStrike Falcon CID with Cloud Region (Sensor v7.28+)
  crowdstrike.falcon.falconctl:
    state: present
    cid: 1234567890ABCDEF1234567890ABCDEF-12
    cloud: us-2

- name: Delete CrowdStrike Falcon CID
  crowdstrike.falcon.falconctl:
    state: absent
    cid: ""

- name: Delete Agent ID to Prep Master Image
  crowdstrike.falcon.falconctl:
    state: absent
    aid: true

- name: Configure Falcon Sensor Proxy
  crowdstrike.falcon.falconctl:
    state: present
    apd: false
    aph: example.com
    app: 8080

- name: Set the sensor tags to exactly tag1 and tag2
  crowdstrike.falcon.falconctl:
    state: present
    exclusive: true
    tags_list:
      - tag1
      - tag2

- name: Add tag3 while keeping any existing sensor tags
  crowdstrike.falcon.falconctl:
    state: present
    tags_list:
      - tag3

- name: Remove a legacy tag while keeping the other sensor tags
  crowdstrike.falcon.falconctl:
    state: absent
    tags_list:
      - tagLegacy

Authors

  • Gabriel Alford (@redhatrises)

  • Carlos Matos (@carlosmmatos)