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