From b1b158c9aa0f73498c919911bf0cb1da3a1ca293 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Wed, 23 Oct 2024 14:44:43 -0400 Subject: [PATCH] docs: update docs to reflect min requirements and better explain roles Closes #528 This PR introduces doc updates that: - Better explain the core functionality of the falcon_install and falcon_configure roles - Add additional call-outs for more clarification - Update the min requirements for Ansible Core and Python3 --- README.md | 18 +++++++++--------- docs/authentication.md | 19 +++++++++++-------- docs/crowdstrike.falcon.eventstream.md | 2 +- plugins/doc_fragments/credentials.py | 4 ++-- plugins/inventory/falcon_discover.py | 8 ++++---- plugins/inventory/falcon_hosts.py | 8 ++++---- plugins/lookup/fctl_child_cids.py | 4 ++-- plugins/lookup/host_ids.py | 4 ++-- plugins/lookup/maintenance_token.py | 4 ++-- plugins/module_utils/falconpy_utils.py | 2 +- roles/falcon_configure/README.md | 25 +++++++++++++++++++++---- roles/falcon_install/README.md | 7 +++++-- roles/falcon_uninstall/README.md | 7 +++++-- tests/config.yml | 2 +- 14 files changed, 70 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 193d3786..b3f4a579 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Tested with the Ansible Core >= 2.15.0 versions, and the current development ver This collection is reliant on the [CrowdStrike FalconPy SDK](https://www.falconpy.io/) for its Python interface. In line with the [Python versions supported by FalconPy](https://github.com/CrowdStrike/falconpy#supported-versions-of-python), 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. +> 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. Please note this will not be supported by this collection. ## Included content @@ -25,7 +25,7 @@ This collection is reliant on the [CrowdStrike FalconPy SDK](https://www.falconp 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.* +***Please read each role's README to familiarize yourself with the role variables and other requirements.*** | Role Name | Documentation | --------- | :-----------: @@ -123,21 +123,21 @@ ansible-galaxy collection install -r requirements.yml 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: +1. Install the CrowdStrike FalconPy package directly: ```terminal - pip install -r requirements.txt + pip install crowdstrike-falconpy ``` -2. Alternatively, install the CrowdStrike FalconPy package directly: +> [!IMPORTANT] +> If you intend to use Event-Driven Ansible (EDA), the `aiohttp` package should also be installed. + +2. Alternatively, if you clone the repository you can utilize the `requirements.txt` file to install all required packages: ```terminal - pip install crowdstrike-falconpy + pip install -r requirements.txt ``` -> [!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 diff --git a/docs/authentication.md b/docs/authentication.md index de74211f..8bdb718c 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -5,21 +5,24 @@ need client credentials. For more information see [Falcon API clients documentat ## Passing in credentials -You can pass in your Falcon API client credentials using either environment variables or +You can pass in your Falcon API client credentials using either environment variables or module arguments. Available environment variables: -- `FALCON_CLIENT_ID` - required -- `FALCON_CLIENT_SECRET` - required -- `FALCON_CLOUD` - optional (discovered automatically) +- `FALCON_CLIENT_ID` - **required** +- `FALCON_CLIENT_SECRET` - **required** +- `FALCON_CLOUD` - optional (discovered automatically*) - `FALCON_MEMBER_CID` - optional (only for Flight Control users) +> [!IMPORTANT] +> \* Auto-discovery is only available for the [*us-1, us-2, eu-1*] cloud regions. + Available module arguments: ```yaml - crowdstrike.falcon.example_module: client_id: abcd1234 # required client_secret: abcd5678 # required - cloud: us-2 # optional (discovered automatically) + cloud: us-2 # optional (discovered automatically*) member_cid: abcd2468 # optional (only for Flight Control users) ``` @@ -29,9 +32,9 @@ You can use either of these methods for both authentication methods listed below ### Recommended: token-based authentication -Token-based authentication allows you to authenticate once against the Falcon API, then use a -returned temporary token for many subsequent API interactions. This is more efficient -and also mitigates the risk of rate limiting, especially when automating multiple hosts. +Token-based authentication allows you to authenticate once against the Falcon API, then use a +returned temporary token for many subsequent API interactions. This is more efficient +and also mitigates the risk of rate limiting, especially when automating multiple hosts. (For more information: [Falcon API rate limit documentation](https://falcon.crowdstrike.com/documentation/page/a2a7fc0e/crowdstrike-oauth2-based-apis#af41971e).) To use token-based authentication, first use the `crowdstrike.falcon.auth` module to get a new token: diff --git a/docs/crowdstrike.falcon.eventstream.md b/docs/crowdstrike.falcon.eventstream.md index c7e79d7e..c013eb24 100644 --- a/docs/crowdstrike.falcon.eventstream.md +++ b/docs/crowdstrike.falcon.eventstream.md @@ -8,7 +8,7 @@ An ansible-rulebook event source plugin for generating events from the Falcon Ev ## Requirements -- Python 3.6+ +- Python 3.7+ - Python requirements are listed in [requirements.txt](./requirements.txt) - Ensure the following API scopes are enabled: - **Event Streams**: [read] diff --git a/plugins/doc_fragments/credentials.py b/plugins/doc_fragments/credentials.py index e0032815..31dffd81 100644 --- a/plugins/doc_fragments/credentials.py +++ b/plugins/doc_fragments/credentials.py @@ -62,8 +62,8 @@ class ModuleDocFragment(object): - Extended headers that are prepended to the default headers dictionary. type: dict requirements: - - python >= 3.6 - - crowdstrike-falconpy >= 1.3.0 + - python >= 3.7 + - crowdstrike-falconpy >= 1.4.0 """ AUTH = r""" diff --git a/plugins/inventory/falcon_discover.py b/plugins/inventory/falcon_discover.py index bf7660db..a5e370b4 100644 --- a/plugins/inventory/falcon_discover.py +++ b/plugins/inventory/falcon_discover.py @@ -67,8 +67,8 @@ default: false requirements: - Assets [B(READ)] API scope - - python >= 3.6 - - crowdstrike-falconpy >= 1.3.0 + - python >= 3.7 + - crowdstrike-falconpy >= 1.4.0 notes: - If no credentials are provided, FalconPy will attempt to use the API credentials via environment variables. - Hostnames are set to the C(hostname) hostvar if it exists, otherwise the IP address is used. @@ -201,9 +201,9 @@ def parse(self, inventory, loader, path, cache=True): ) # Check FalconPy version - if _VERSION < "1.3.0": + if _VERSION < "1.4.0": raise ImportError( - "The crowdstrike.falcon.falcon_discover plugin requires falconpy 1.3.0 or higher." + "The crowdstrike.falcon.falcon_discover plugin requires falconpy 1.4.0 or higher." ) # cache may be True or False at this point to indicate if the inventory is being refreshed diff --git a/plugins/inventory/falcon_hosts.py b/plugins/inventory/falcon_hosts.py index 03d36d38..e7d6c41f 100644 --- a/plugins/inventory/falcon_hosts.py +++ b/plugins/inventory/falcon_hosts.py @@ -68,8 +68,8 @@ default: ['hostname', 'external_ip', 'local_ip'] requirements: - Hosts [B(READ)] API scope - - python >= 3.6 - - crowdstrike-falconpy >= 1.3.0 + - python >= 3.7 + - crowdstrike-falconpy >= 1.4.0 notes: - By default, Ansible will deduplicate the C(inventory_hostname), so if multiple hosts have the same hostname, only the last one will be used. In this case, consider using the C(device_id) as the first preference in the C(hostnames). @@ -206,9 +206,9 @@ def parse(self, inventory, loader, path, cache=True): ) # Check FalconPy version - if _VERSION < "1.3.0": + if _VERSION < "1.4.0": raise ImportError( - "The crowdstrike.falcon.falcon_hosts plugin requires falconpy 1.3.0 or higher." + "The crowdstrike.falcon.falcon_hosts plugin requires falconpy 1.4.0 or higher." ) # cache may be True or False at this point to indicate if the inventory is being refreshed diff --git a/plugins/lookup/fctl_child_cids.py b/plugins/lookup/fctl_child_cids.py index ee518776..c610e22b 100644 --- a/plugins/lookup/fctl_child_cids.py +++ b/plugins/lookup/fctl_child_cids.py @@ -160,9 +160,9 @@ def run(self, terms, variables=None, **kwargs): ) # Check if the 'falconpy' library is compatible - if _VERSION < "1.3.0": + if _VERSION < "1.4.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." ) self.set_options(var_options=variables, direct=kwargs) diff --git a/plugins/lookup/host_ids.py b/plugins/lookup/host_ids.py index 99d031f6..09a8ea89 100644 --- a/plugins/lookup/host_ids.py +++ b/plugins/lookup/host_ids.py @@ -176,9 +176,9 @@ def run(self, terms, variables=None, **kwargs): ) # Check if the 'falconpy' library is compatible - if _VERSION < "1.3.0": + if _VERSION < "1.4.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." ) self.set_options(var_options=variables, direct=kwargs) diff --git a/plugins/lookup/maintenance_token.py b/plugins/lookup/maintenance_token.py index f33c1561..903bd1df 100644 --- a/plugins/lookup/maintenance_token.py +++ b/plugins/lookup/maintenance_token.py @@ -155,9 +155,9 @@ def run(self, terms, variables=None, **kwargs): ) # Check if the 'falconpy' library is compatible - if _VERSION < "1.3.0": + if _VERSION < "1.4.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." ) self.set_options(var_options=variables, direct=kwargs) diff --git a/plugins/module_utils/falconpy_utils.py b/plugins/module_utils/falconpy_utils.py index 32696bb2..99c6084d 100644 --- a/plugins/module_utils/falconpy_utils.py +++ b/plugins/module_utils/falconpy_utils.py @@ -23,7 +23,7 @@ def check_falconpy_version(module): """Ensure FalconPy version is compatible.""" - minumum_version = "1.3.0" + minumum_version = "1.4.0" if FALCONPY_IMPORT_ERROR: module.fail_json( diff --git a/roles/falcon_configure/README.md b/roles/falcon_configure/README.md index 970067ad..fda20497 100644 --- a/roles/falcon_configure/README.md +++ b/roles/falcon_configure/README.md @@ -1,7 +1,12 @@ # crowdstrike.falcon.falcon_configure This role configures the CrowdStrike Falcon Sensor. For Linux and macOS, this role requires the Falcon -sensor to be installed prior to running this role. +sensor to be installed prior to running this role (see [falcon_install](../falcon_install/README.md)). + +> [!IMPORTANT] +> The Falcon Customer ID (CID) with checksum is ***required*** in order to properly configure and start the Falcon Sensor. +> You can either pass the CID as a variable (`falcon_cid`) or use let Ansible fetch it from the CrowdStrike API using your +> API credentials. > [!NOTE] > This role is focused mainly on configuring the Falcon Sensor on Linux and MacOS. Windows is supported, but not as @@ -11,8 +16,8 @@ sensor to be installed prior to running this role. ## Requirements -- Ansible 2.13 or higher -- FalconPy 1.3.0 or higher on Ansible control node +- Ansible Core >= 2.15.0 +- FalconPy 1.4.0 or higher on Ansible control node > As of version 4.0.0, this role takes full advantage of the FalconPy SDK for interacting with the CrowdStrike API. @@ -100,10 +105,22 @@ Ensure the following API scopes are enabled (***if applicable***) for this role: - When using API credentials `falcon_client_id` and `falcon_client_secret` - **Sensor Download** [read] +## Falcon Sensor Service + +For Linux/macOS, the Falcon Sensor service is automatically started after the sensor is installed (*although it will be in a failed state*). + +> [!WARNING] +> The service will be in a failed state until the CID is set and the sensor is restarted. + +This role will restart the Falcon Sensor service after the CID is set, along with any other configuration options. + ## Dependencies - Privilege escalation (sudo) is required for this role to function properly. -- Falcon Sensor must be installed +- The Falcon Sensor must be installed + +> [!IMPORTANT] +> The role automatically handles privilege escalation so you do not need to set `become: true` in your playbook. ## Example Playbooks diff --git a/roles/falcon_install/README.md b/roles/falcon_install/README.md index a809d56d..492e8406 100644 --- a/roles/falcon_install/README.md +++ b/roles/falcon_install/README.md @@ -7,8 +7,8 @@ This role installs the CrowdStrike Falcon Sensor. It provides the flexibility to ## Requirements -- Ansible 2.13 or higher -- FalconPy 1.3.0 or higher on Ansible control node +- Ansible Core >= 2.15.0 +- FalconPy 1.4.0 or higher on Ansible control node > As of version 4.0.0, this role takes full advantage of the FalconPy SDK for interacting with the CrowdStrike API. @@ -95,6 +95,9 @@ Ensure the following API scopes are enabled (***if applicable***) for this role: - Privilege escalation is required for this role to function properly. +> [!IMPORTANT] +> The role automatically handles privilege escalation so you do not need to set `become: true` in your playbook. + ## Example Playbooks This example installs the latest Falcon Sensor: diff --git a/roles/falcon_uninstall/README.md b/roles/falcon_uninstall/README.md index 34c1174a..932027f6 100644 --- a/roles/falcon_uninstall/README.md +++ b/roles/falcon_uninstall/README.md @@ -4,8 +4,8 @@ This role uninstalls the CrowdStrike Falcon Sensor. ## Requirements -- Ansible 2.13 or higher -- FalconPy 1.3.0 or higher on Ansible control node +- Ansible Core >= 2.15.0 +- FalconPy 1.4.0 or higher on Ansible control node > As of version 4.0.0, this role takes full advantage of the FalconPy SDK for interacting with the CrowdStrike API. @@ -47,6 +47,9 @@ Ensure the following API scopes are enabled (**if applicable**) for this role: Privilege escalation (sudo) is required for this role to function properly. +> [!IMPORTANT] +> The role automatically handles privilege escalation so you do not need to set `become: true` in your playbook. + ## Example Playbooks This example uninstalls the Falcon Sensor: diff --git a/tests/config.yml b/tests/config.yml index a1d97cea..91aedb00 100644 --- a/tests/config.yml +++ b/tests/config.yml @@ -7,7 +7,7 @@ modules: # Configuration for modules/module_utils. # These settings do not apply to other content in the collection. - python_requires: '>=3.6' + python_requires: '>=3.7' # Python versions supported by modules/module_utils. # This setting is required. #