CrowdStrike Falcon Collection

The CrowdStrike Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform.

Description

This collection streamlines the management of CrowdStrike Falcon deployments by offering pre-defined roles, modules, inventory plugins, and lookup plugins. It enables automated installation, configuration, and removal of the Falcon sensor across multiple platforms including macOS, Linux, and Windows. The collection also provides robust API integration capabilities through the CrowdStrike FalconPy SDK.

Requirements

Ansible version compatibility

Tested with the Ansible Core >= 2.15.0 versions, and the current development version of Ansible. Ansible Core versions before 2.15.0 are not supported.

Python version compatibility

This collection is reliant on the CrowdStrike FalconPy SDK for its Python interface. In line with the Python versions supported by FalconPy, a minimum Python version of 3.7 is required for this collection to function properly.

[!NOTE] As of FalconPy Version 1.4.0, Python 3.6 is no longer supported. If you would like to use FalconPy with Python 3.6, please use FalconPy Version < 1.4.0.

Included content

Roles

Offering pre-defined roles tailored for various platforms—including macOS, Linux, and Windows—this collection simplifies the installation, configuration, and removal processes for CrowdStrike's Falcon sensor.

Privilege Escalation Requirements

When using this collection, it's essential to understand how privilege escalation works. While our roles use privilege escalation internally, you must ensure that it is configured on the target hosts.

[!IMPORTANT] Do not set become: true for the roles. Instead, make sure that the target hosts have privilege escalation (sudo/runas) configured and available. This will allow our roles to use privilege escalation internally.

Please read each role's README to familiarize yourself with the role variables and other requirements.

| Role Name | Documentation | --------- | :-----------: | crowdstrike.falcon.falconinstall | README | crowdstrike.falcon.falconconfigure | README | crowdstrike.falcon.falcon_uninstall | README

Modules

Name | Description --- | --- crowdstrike.falcon.falconctl|Configure CrowdStrike Falcon Sensor (Linux) crowdstrike.falcon.falconctl_info|Get Values Associated with Falcon Sensor (Linux) crowdstrike.falcon.fctlchildcid_info|Retrieve details about Flight Control child CIDs crowdstrike.falcon.auth|Manage Authentication with Falcon API crowdstrike.falcon.cid_info|Get CID with checksum crowdstrike.falcon.host_contain|Network contain hosts in Falcon crowdstrike.falcon.host_hide|Hide/Unhide hosts from the Falcon console. Preference should be given to using Host Retention Policies under Host Management in the Falcon console which provides more flexibility and customization for automatically hiding and deleting hosts instead. crowdstrike.falcon.host_info|Get information about Falcon hosts crowdstrike.falcon.intelruledownload|Download CrowdStrike Falcon Intel rule files crowdstrike.falcon.intelruleinfo|Get information about CrowdStrike Falcon Intel rules crowdstrike.falcon.kernelsupportinfo|Get information about kernels supported by the Falcon Sensor for Linux crowdstrike.falcon.sensor_download|Download Falcon Sensor Installer crowdstrike.falcon.sensordownloadinfo|Get information about Falcon Sensor Installers crowdstrike.falcon.sensorupdatebuilds_info|Get a list of available sensor build versions crowdstrike.falcon.sensorupdatepolicy_info|Get information about Falcon Update Sensor Policies

Inventory plugins

Name | Description --- | --- crowdstrike.falcon.falcon_discover|Falcon Discover inventory source crowdstrike.falcon.falcon_hosts|Falcon Hosts inventory source

Lookup plugins

Name | Description --- | --- crowdstrike.falcon.fctlchildcids|Fetch Flight Control child CIDs crowdstrike.falcon.host_ids|Fetch host IDs in Falcon crowdstrike.falcon.maintenance_token|Fetch maintenance token <!--end collection content-->

Event sources

Ansible EDA (Event Driven Ansible) is a new way to connect to sources of events and act on those events using rulebooks. For more information, see the EDA documentation.

Name | Description --- | --- crowdstrike.falcon.eventstream | Receive events from CrowdStrike Falcon Event Stream.

Installation

Installing the Collection from Ansible Galaxy

Before using this collection, you need to install it with the Ansible Galaxy command-line tool:

terminal ansible-galaxy collection install crowdstrike.falcon

You can also include the collection in a requirements.yml file and install it through ansible-galaxy, use the following format:

```yaml

collections: - crowdstrike.falcon ```

Then run:

terminal ansible-galaxy collection install -r requirements.yml

Additional notes

• Upgrading the Collection: Note that if you've installed the collection from Ansible Galaxy, it won't automatically update when you upgrade the ansible package. To manually upgrade to the latest version, use:

  terminal ansible-galaxy collection install crowdstrike.falcon --upgrade

• Installing a Specific Version: If you need to install a particular version of the collection (for example, to downgrade due to an issue), you can specify the version as follows:

  terminal ansible-galaxy collection install crowdstrike.falcon:==0.1.0

• See using Ansible collections for more details.

Required Python dependencies

The Python module dependencies are not automatically handled by ansible-galaxy. To install these dependencies, you have the following options:

1. Install the CrowdStrike FalconPy package directly:

   terminal pip install crowdstrike-falconpy aiohttp

2. Alternatively, if you clone the repository, you can utilize the requirements.txt file to install all required packages:

   terminal pip install -r requirements.txt

Authentication

To use this Ansible collection effectively, you'll need to authenticate with the CrowdStrike Falcon API. We've prepared a detailed guide outlining the various authentication mechanisms supported. Check out the Authentication Guide for step-by-step instructions.

Use Cases

Using the Built-In Roles

Install and configure the CrowdStrike Falcon Sensor at version N-2:

```yaml - hosts: all vars: falconclientid: falconclientsecret: roles: - role: crowdstrike.falcon.falconinstall vars: falconsensorversiondecrement: 2

• role: crowdstrike.falcon.falconconfigure vars: # falconcid is autodetected using falconclientid|secret vars falcon_tags: 'falcon,example,tags' ```

Install the latest sensor and prepare golden image:

```yaml - hosts: target-host vars: falconclientid: falconclientsecret: roles: - role: crowdstrike.falcon.falcon_install

• role: crowdstrike.falcon.falconconfigure vars: falconremove_aid: yes ```

Using Modules and Plugins

```yaml

• name: Get a list of the 2 latest Windows Sensor Installers crowdstrike.falcon.sensordownloadinfo: clientid: <FALCONCLIENTID> clientsecret: cloud: us-2 limit: 2 filter: "platformname:'windows'" sort: "version|desc" delegateto: localhost

• name: Get information about all Windows hosts (using hostids lookup) crowdstrike.falcon.hostinfo: hosts: "{{ lookup('crowdstrike.falcon.hostids', windowshostfilter) }}" vars: windowshostfilter: 'platformname:"Windows"' ```

Using Dynamic Inventories

Get detailed information for all Linux hosts in reduced functionality mode:

```yaml

sample file: linuxrfm.falconhosts.yml

plugin: crowdstrike.falcon.falconhosts filter: "platformname:'Linux' + reducedfunctionalitymode:'yes'" ```

Discover systems in your environment that don't have Falcon installed in the past day:

```yaml

sample file: sketchyhosts.falcondiscover.yml

plugin: crowdstrike.falcon.falcondiscover filter: "entitytype:'unmanaged'+firstseentimestamp:>'now-1d'" ```

React to Security Events with the EDA Event Source

This example requires Ansible EDA to be installed. See the Ansible Rulebook documentation for more information.

shell ansible-rulebook -i inventory -r crowdstrike.falcon.event_stream_example -E FALCON_CLIENT_ID,FALCON_CLIENT_SECRET

Testing

The CrowdStrike Falcon Ansible collection uses automated testing through Molecule integrated with GitHub Actions. Tests are executed automatically every night, ensuring continuous validation of:

• All built-in roles and their functionality
• Multiple deployment scenarios
• Compatibility across supported operating systems

This automated testing pipeline helps maintain collection reliability and quickly identifies potential issues across different environments and use cases.

To learn more about how we use Molecule, check out the molecule directory.

Nightly Results: Actions

Contributing

If you want to develop new content or improve on this collection, please open an issue or create a pull request. All contributions are welcome!

As of release > 3.2.18, we will now be following Ansible's development patterns for implementing Ansible's changelog fragments. This will require a changelog fragment to any PR that is not documentation or trivial. Most changelog entries will likely be bugfixes or minor_changes. Please refer to the documentation for Ansible's changelog fragments to learn more.

Support

CrowdStrike Ansible Collection is a community-driven, open source project aimed at simplifying the integration and utilization of CrowdStrike's Falcon platform with Ansible automation. While not an official CrowdStrike product, the CrowdStrike Ansible Collection is maintained by CrowdStrike and supported in collaboration with the open source developer community.

For additional information, please refer to the SUPPORT.md file.

Release Notes

See the CHANGELOG.rst for a history of notable changes to this collection.

Related information

• Ansible Collection Overview
• Ansible User Guide
• Ansible Using Collections
• Ansible Community Code of Conduct
• Ansible Rulebook Introduction
• Event Driven Ansible Introduction
• CrowdStrike FalconPy SDK

License Information

See the LICENSE for more information.