The Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform.
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.
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.
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.
Please read each role's README to familiarize yourself with the role variables and other requirements.
Role Name | Documentation |
---|---|
crowdstrike.falcon.falcon_install | README |
crowdstrike.falcon.falcon_configure | README |
crowdstrike.falcon.falcon_uninstall | README |
Name | Description |
---|---|
crowdstrike.falcon.falconctl | Configure CrowdStrike Falcon Sensor (Linux) |
crowdstrike.falcon.falconctl_info | Get Values Associated with Falcon Sensor (Linux) |
crowdstrike.falcon.fctl_child_cid_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 |
crowdstrike.falcon.host_info | Get information about Falcon hosts |
crowdstrike.falcon.kernel_support_info | Get information about kernels supported by the Falcon Sensor for Linux |
crowdstrike.falcon.sensor_download | Download Falcon Sensor Installer |
crowdstrike.falcon.sensor_download_info | Get information about Falcon Sensor Installers |
crowdstrike.falcon.sensor_update_builds_info | Get a list of available sensor build versions |
crowdstrike.falcon.sensor_update_policy_info | Get information about Falcon Update Sensor Policies |
Name | Description |
---|---|
crowdstrike.falcon.falcon_discover | Falcon Discover inventory source |
crowdstrike.falcon.falcon_hosts | Falcon Hosts inventory source |
Name | Description |
---|---|
crowdstrike.falcon.fctl_child_cids | Fetch Flight Control child CIDs |
crowdstrike.falcon.host_ids | Fetch host IDs in Falcon |
crowdstrike.falcon.maintenance_token | Fetch maintenance token |
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. |
ansible-galaxy
CLITo install the Falcon Ansible Collection using the command-line interface, execute the following:
ansible-galaxy collection install crowdstrike.falcon
requirements.yml
FileTo include the collection in a requirements.yml
file and install it through ansible-galaxy
, use the following format:
---
collections:
- crowdstrike.falcon
Then run:
ansible-galaxy collection install -r requirements.yml
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:
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:
ansible-galaxy collection install crowdstrike.falcon:==0.1.0
The Python module dependencies are not automatically handled by ansible-galaxy
. To manually install these dependencies, you have the following options:
Utilize the requirements.txt
file to install all required packages:
pip install -r requirements.txt
Alternatively, install the CrowdStrike FalconPy package directly:
pip install crowdstrike-falconpy
[!NOTE] If you intend to use Event-Driven Ansible (EDA), the
aiohttp
package should also be installed.
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.
---
- name: Get a list of the 2 latest Windows Sensor Installers
crowdstrike.falcon.sensor_download_info:
client_id: <FALCON_CLIENT_ID>
client_secret: <FALCON_CLIENT_SECRET>
cloud: us-2
limit: 2
filter: "platform_name:'windows'"
sort: "version|desc"
delegate_to: localhost
Install and configure the CrowdStrike Falcon Sensor at version N-2:
- hosts: all
vars:
falcon_client_id: <FALCON_CLIENT_ID>
falcon_client_secret: <FALCON_CLIENT_SECRET>
roles:
- role: crowdstrike.falcon.falcon_install
vars:
falcon_sensor_version_decrement: 2
- role: crowdstrike.falcon.falcon_configure
vars:
# falcon_cid is autodetected using falcon_client_id|secret vars
falcon_tags: 'falcon,example,tags'
This example requires Ansible EDA to be installed. See the Ansible Rulebook documentation for more information.
ansible-rulebook -i inventory -r crowdstrike.falcon.event_stream_example -E FALCON_CLIENT_ID,FALCON_CLIENT_SECRET
See the changelog for a history of notable changes to this collection.
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.
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.
See the license for more information.