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

@@ -17,15 +17,15 @@ 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
 
 ### 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.*
+***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

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:

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]

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

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

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

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)

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)

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)

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(

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
 

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:

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:

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