From b1b158c9aa0f73498c919911bf0cb1da3a1ca293 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Wed, 23 Oct 2024 14:44:43 -0400 Subject: [PATCH 1/5] 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. # From 2ed597352181893a65e382cbe61aff8d4e75aa57 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Wed, 23 Oct 2024 15:42:51 -0400 Subject: [PATCH 2/5] docs: make auto-discovery simpler via examples instead of callout --- docs/authentication.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 8bdb718c..944b73be 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -10,11 +10,8 @@ module arguments. Available environment variables: - `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. +- `FALCON_CLOUD` - *optional* for us-1, us-2, and eu-1; **required** for gov clouds +- `FALCON_MEMBER_CID` - *optional* (only for Flight Control users) Available module arguments: @@ -22,7 +19,7 @@ Available module arguments: - crowdstrike.falcon.example_module: client_id: abcd1234 # required client_secret: abcd5678 # required - cloud: us-2 # optional (discovered automatically*) + cloud: us-gov-1 # optional for us-1, us-2, and eu-1; required for gov clouds member_cid: abcd2468 # optional (only for Flight Control users) ``` From 166652392590ed7bc70f29efb5d0f45880aabb52 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 24 Oct 2024 13:52:24 -0400 Subject: [PATCH 3/5] docs: updates around privilege escalation and some rearranging --- README.md | 9 ++++++++- roles/falcon_configure/README.md | 29 ++++++----------------------- roles/falcon_install/README.md | 12 +++++------- roles/falcon_uninstall/README.md | 8 +++----- 4 files changed, 22 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index b3f4a579..9f4d6940 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,14 @@ 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.*** +#### Privilege Escalation Requirements + +When using this collection, it's essential to understand how privilege escalation works. While our roles use privilege escalation internally, you must ensure that it is configured on the target hosts. + +> [!IMPORTANT] +> Do not set `become: true` for the roles. Instead, make sure that the target hosts have privilege escalation (sudo/runas) configured and available. This will allow our roles to use privilege escalation internally. + +*Please read each role's README to familiarize yourself with the role variables and other requirements.* | Role Name | Documentation | --------- | :-----------: diff --git a/roles/falcon_configure/README.md b/roles/falcon_configure/README.md index fda20497..facc12ce 100644 --- a/roles/falcon_configure/README.md +++ b/roles/falcon_configure/README.md @@ -1,19 +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 (see [falcon_install](../falcon_install/README.md)). +Configures the CrowdStrike Falcon Sensor. This role is focused mainly on configuring the Falcon Sensor on Linux and macOS. Windows is supported, but not as much functionality is currently available. The main difference is because a lot of the configuration options can be set during the installation of the sensor on Windows. > [!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 +> You can either pass the CID as a variable (`falcon_cid`) or let this role 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 -> much functionality is currently available. The main difference is because a lot of the configuration options can -> be set during the installation of the sensor on Windows. We do plan to add more functionality to this role in the -> future. - ## Requirements - Ansible Core >= 2.15.0 @@ -105,22 +98,12 @@ 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. -- 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. +- Privilege escalation (sudo/runas) is required for this role to function properly. + > See [Privilege Escalation Requirements](../../README.md#privilege-escalation-requirements) for more information. +- The Falcon Sensor must be installed on the target host + > See the [falcon_install](../falcon_install/README.md) role to learn more about installing the Falcon sensor. ## Example Playbooks diff --git a/roles/falcon_install/README.md b/roles/falcon_install/README.md index 492e8406..a112bc6e 100644 --- a/roles/falcon_install/README.md +++ b/roles/falcon_install/README.md @@ -1,9 +1,9 @@ # crowdstrike.falcon.falcon_install -This role installs the CrowdStrike Falcon Sensor. It provides the flexibility to install the sensor using the CrowdStrike API, a local file, or a remote URL. +Installs the CrowdStrike Falcon Sensor. It provides the flexibility to install the sensor using the CrowdStrike API, a local file, or a remote URL. -> [!NOTE] -> Please note that for Linux and macOS, this role only handles the installation of the sensor. To configure and start the sensor, please use the [falcon_configure](../falcon_configure/) role after the sensor is installed. +> [!IMPORTANT] +> On Linux and macOS systems, running this role alone is insufficient for a fully operational Falcon sensor deployment. To complete the setup, you must also run the [falcon_configure](../falcon_configure/) role after installing the sensor with this role. ## Requirements @@ -93,10 +93,8 @@ Ensure the following API scopes are enabled (***if applicable***) for this role: ## Dependencies -- 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. +- Privilege escalation (sudo/runas) is required for this role to function properly. + > See [Privilege Escalation Requirements](../../README.md#privilege-escalation-requirements) for more information. ## Example Playbooks diff --git a/roles/falcon_uninstall/README.md b/roles/falcon_uninstall/README.md index 932027f6..4319a1e5 100644 --- a/roles/falcon_uninstall/README.md +++ b/roles/falcon_uninstall/README.md @@ -1,6 +1,6 @@ # crowdstrike.falcon.falcon_uninstall -This role uninstalls the CrowdStrike Falcon Sensor. +Uninstalls the CrowdStrike Falcon Sensor. ## Requirements @@ -45,10 +45,8 @@ Ensure the following API scopes are enabled (**if applicable**) for this role: ## Dependencies -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. +- Privilege escalation (sudo/runas) is required for this role to function properly. + > See [Privilege Escalation Requirements](../../README.md#privilege-escalation-requirements) for more information. ## Example Playbooks From b7671d848bc27a4abb5a0967742d07f55bb53368 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Fri, 25 Oct 2024 13:12:59 -0400 Subject: [PATCH 4/5] chore: reverting back min requirements Will move into a subsequent PR to keep this clean/seperate --- README.md | 2 +- 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 | 4 ++-- roles/falcon_install/README.md | 4 ++-- roles/falcon_uninstall/README.md | 4 ++-- tests/config.yml | 2 +- 13 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9f4d6940..4cbd587b 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. Please note this will not be supported by this collection. +> 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 diff --git a/docs/crowdstrike.falcon.eventstream.md b/docs/crowdstrike.falcon.eventstream.md index c013eb24..c7e79d7e 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.7+ +- Python 3.6+ - 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 31dffd81..e0032815 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.7 - - crowdstrike-falconpy >= 1.4.0 + - python >= 3.6 + - crowdstrike-falconpy >= 1.3.0 """ AUTH = r""" diff --git a/plugins/inventory/falcon_discover.py b/plugins/inventory/falcon_discover.py index a5e370b4..bf7660db 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.7 - - crowdstrike-falconpy >= 1.4.0 + - python >= 3.6 + - crowdstrike-falconpy >= 1.3.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.4.0": + if _VERSION < "1.3.0": raise ImportError( - "The crowdstrike.falcon.falcon_discover plugin requires falconpy 1.4.0 or higher." + "The crowdstrike.falcon.falcon_discover plugin requires falconpy 1.3.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 e7d6c41f..03d36d38 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.7 - - crowdstrike-falconpy >= 1.4.0 + - python >= 3.6 + - crowdstrike-falconpy >= 1.3.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.4.0": + if _VERSION < "1.3.0": raise ImportError( - "The crowdstrike.falcon.falcon_hosts plugin requires falconpy 1.4.0 or higher." + "The crowdstrike.falcon.falcon_hosts plugin requires falconpy 1.3.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 c610e22b..ee518776 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.4.0": + if _VERSION < "1.3.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.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 09a8ea89..99d031f6 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.4.0": + if _VERSION < "1.3.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.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 903bd1df..f33c1561 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.4.0": + if _VERSION < "1.3.0": raise AnsibleError( - f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.4.0 or higher." + f"Unsupported FalconPy version: {_VERSION}. Upgrade to 1.3.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 99c6084d..32696bb2 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.4.0" + minumum_version = "1.3.0" if FALCONPY_IMPORT_ERROR: module.fail_json( diff --git a/roles/falcon_configure/README.md b/roles/falcon_configure/README.md index facc12ce..158559a0 100644 --- a/roles/falcon_configure/README.md +++ b/roles/falcon_configure/README.md @@ -9,8 +9,8 @@ Configures the CrowdStrike Falcon Sensor. This role is focused mainly on configu ## Requirements -- Ansible Core >= 2.15.0 -- FalconPy 1.4.0 or higher on Ansible control node +- Ansible 2.13 or higher +- FalconPy 1.3.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. diff --git a/roles/falcon_install/README.md b/roles/falcon_install/README.md index a112bc6e..e6218ad6 100644 --- a/roles/falcon_install/README.md +++ b/roles/falcon_install/README.md @@ -7,8 +7,8 @@ Installs the CrowdStrike Falcon Sensor. It provides the flexibility to install t ## Requirements -- Ansible Core >= 2.15.0 -- FalconPy 1.4.0 or higher on Ansible control node +- Ansible 2.13 or higher +- FalconPy 1.3.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. diff --git a/roles/falcon_uninstall/README.md b/roles/falcon_uninstall/README.md index 4319a1e5..9988faf5 100644 --- a/roles/falcon_uninstall/README.md +++ b/roles/falcon_uninstall/README.md @@ -4,8 +4,8 @@ Uninstalls the CrowdStrike Falcon Sensor. ## Requirements -- Ansible Core >= 2.15.0 -- FalconPy 1.4.0 or higher on Ansible control node +- Ansible 2.13 or higher +- FalconPy 1.3.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. diff --git a/tests/config.yml b/tests/config.yml index 91aedb00..a1d97cea 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.7' + python_requires: '>=3.6' # Python versions supported by modules/module_utils. # This setting is required. # From afaa274a8726b3339215536213b2fbfe20ded5aa Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Fri, 25 Oct 2024 14:17:50 -0400 Subject: [PATCH 5/5] docs: k.i.s.s approach to python deps --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4cbd587b..83ae5208 100644 --- a/README.md +++ b/README.md @@ -128,18 +128,15 @@ ansible-galaxy collection install -r requirements.yml ### Python dependencies -The Python module dependencies are not automatically handled by `ansible-galaxy`. To manually install these dependencies, you have the following options: +The Python module dependencies are not automatically handled by `ansible-galaxy`. To install these dependencies, you have the following options: 1. Install the CrowdStrike FalconPy package directly: ```terminal - pip install crowdstrike-falconpy + pip install crowdstrike-falconpy aiohttp ``` -> [!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: +2. Alternatively, if you clone the repository, you can utilize the `requirements.txt` file to install all required packages: ```terminal pip install -r requirements.txt