crowdstrike.falcon.sensor_download module – Download Falcon Sensor Installer

Note

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

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

New in crowdstrike.falcon 4.0.0

Synopsis

Requirements

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

  • Sensor download [READ] API scope

  • crowdstrike-falconpy >= 1.3.0

  • python >= 3.6

Parameters

Parameter

Comments

attributes

aliases: attr

string

The attributes the resulting filesystem object should have.

To get supported flags look at the man page for chattr on the target system.

This string should contain the attributes in the same order as the one displayed by lsattr.

The = operator is assumed as default, otherwise + or - operators need to be included in the string.

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.

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"

dest

path

The directory path to save the Falcon Sensor Installer.

If not specified, a temporary directory will be created using the system’s default temporary directory.

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

group

string

Name of the group that should own the filesystem object, as would be fed to chown.

When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.

hash

string / required

The SHA256 hash of the Falcon Sensor Installer to download.

This can be obtained from the sha256 return value of the crowdstrike.falcon.sensor_download_info module.

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.

mode

any

The permissions the resulting filesystem object should have.

For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, 0755) works sometimes, but can fail in loops and some other circumstances.

Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results.

As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r).

If mode is not specified and the destination filesystem object does not exist, the default umask on the system will be used when setting the mode for the newly created filesystem object.

If mode is not specified and the destination filesystem object does exist, the mode of the existing filesystem object will be used.

Specifying mode is the best way to ensure filesystem objects are created with the correct permissions. See CVE-2020-1736 for further details.

name

string

The name to save the Falcon Sensor Installer as.

If not specified, it will default to the name of the Falcon Sensor Installer.

Example: falcon-sensor_6.78.9-12345.deb

owner

string

Name of the user that should own the filesystem object, as would be fed to chown.

When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership.

Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.

selevel

string

The level part of the SELinux filesystem object context.

This is the MLS/MCS attribute, sometimes known as the range.

When set to _default, it will use the level portion of the policy if available.

serole

string

The role part of the SELinux filesystem object context.

When set to _default, it will use the role portion of the policy if available.

setype

string

The type part of the SELinux filesystem object context.

When set to _default, it will use the type portion of the policy if available.

seuser

string

The user part of the SELinux filesystem object context.

By default it uses the system policy, where applicable.

When set to _default, it will use the user portion of the policy if available.

unsafe_writes

boolean

Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object.

By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner.

This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes).

IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.

Choices:

  • false ← (default)

  • true

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

  • This module implements file locking to ensure safe concurrent downloads by preventing multiple instances from accessing the same file simultaneously. As a result, a temporary 0-byte .lock file will be created in the same directory as the downloaded file. If needed, this lock file can be safely removed in a subsequent task after the download completes.

Examples

- name: Download the Falcon Sensor Installer
  crowdstrike.falcon.sensor_download:
    hash: "1234567890123456789012345678901234567890123456789012345678901234"

- name: Download Windows Sensor Installer with custom name
  crowdstrike.falcon.sensor_download:
    hash: "1234567890123456789012345678901234567890123456789012345678901234"
    dest: "/tmp/windows"
    name: falcon-sensor.exe

- name: Download the Falcon Sensor Installer to a temporary directory and set permissions
  crowdstrike.falcon.sensor_download:
    hash: "1234567890123456789012345678901234567890123456789012345678901234"
    mode: "0644"
    owner: "root"
    group: "root"

Return Values

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

Key

Description

path

string

The full path of the downloaded Falcon Sensor Installer.

Returned: success

Sample: "/tmp/tmpzy7hn29t/falcon-sensor.deb"

Authors

  • Carlos Matos (@carlosmmatos)