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

September 15, 2023: We are excited to announce that Version 4 of the Falcon Ansible Collection has been officially launched. Version 4 will provide us with numerous advantages that align well with our ongoing automation and cybersecurity strategies. By extending the power of the FalconPy SDK, Version 4 will be instrumental in interacting with and automating the Falcon platform.

• New Branch: Version 3 will be moved to its own dedicated branch v3 to allow for isolated maintenance and bug fixes.
• No New Features: Version 3 will not receive any new features moving forward. We will only release bug fixes to maintain its stability. This is to allow us to focus our development efforts on Version 4.
• Limited Support: Version 3 will continue to receive bug fixes until February 1st, 2024. After that date, we will no longer provide updates or support for Version 3.

We strongly encourage you to upgrade to Version 4 to benefit from new features and ongoing support. Please see the Installing this collection section to get started.

If you encounter any issues or have questions about the migration, please open an issue in this repository.

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

Role Name	Documentation	Build Status Linux	Build Status Windows
crowdstrike.falcon.falcon_install	README
crowdstrike.falcon.falcon_configure	README
crowdstrike.falcon.falcon_uninstall	README

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.

See the license for more information.