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

Tested with the Ansible Core >= 2.14.0 versions, and the current development version of Ansible. Ansible Core versions before 2.14.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.

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.

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.

To install the Falcon Ansible Collection using the command-line interface, execute the following:

ansible-galaxy collection install crowdstrike.falcon

To 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:

1. Utilize the requirements.txt file to install all required packages:

   pip install -r requirements.txt
   

2. Alternatively, install the CrowdStrike FalconPy package directly:

   pip install crowdstrike-falconpy
   

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.

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

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.