docs: update docs to reflect min requirements and better explain roles (

#571)

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

* docs: make auto-discovery simpler via examples instead of callout

* docs: updates around privilege escalation and some rearranging

* chore: reverting back min requirements

* docs: k.i.s.s approach to python deps

README.md

@@ -25,6 +25,13 @@ 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.
 
+#### 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
@@ -121,23 +128,20 @@ 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. 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 aiohttp
     ```
 
-2. Alternatively, install the CrowdStrike FalconPy package directly:
+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,21 @@ 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_MEMBER_CID` - optional (only for Flight Control users)
+- `FALCON_CLIENT_ID` - **required**
+- `FALCON_CLIENT_SECRET` - **required**
+- `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:
 
 ```yaml
 - 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)
 ```
 
@@ -29,9 +29,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:

roles/falcon_configure/README.md

@@ -1,13 +1,11 @@
 # 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.
+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.
 
-> [!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.
+> [!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 let this role fetch it from the CrowdStrike API using your
+> API credentials.
 
 ## Requirements
 
@@ -102,8 +100,10 @@ Ensure the following API scopes are enabled (***if applicable***) for this role:
 
 ## Dependencies
 
-- Privilege escalation (sudo) is required for this role to function properly.
-- Falcon Sensor must be installed
+- 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
 

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,7 +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.
+- 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
 

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,7 +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.
+- 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