Ansible Collection - crowdstrike.falcon

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

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.

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

Modules

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

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.fctl_child_cids	Fetch Flight Control child CIDs
crowdstrike.falcon.host_ids	Fetch host IDs in Falcon
crowdstrike.falcon.maintenance_token	Fetch maintenance token

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.

Installing this collection

Using `ansible-galaxy` CLI

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

ansible-galaxy collection install crowdstrike.falcon

Using a `requirements.yml` File

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

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

Python dependencies

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.

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.

Using this collection

Example using modules

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

Example using the built-in roles to install Falcon

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'

Example using the Event Stream EDA source via Ansible Rulebook

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

Release Notes

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

More information

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.

Questions or 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.

License

See the license for more information.

CrowdStrike/ansible_collection_falcon