diff --git a/README.md b/README.md index dde41592..13d67f88 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,6 @@ The Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform. -## Questions or concerns? - -If you encounter any issues or have questions about the migration, please open an [issue](https://github.com/CrowdStrike/ansible_collection_falcon/issues/new/choose) in this repository. - ## Ansible version compatibility Tested with the Ansible Core >= 2.14.0 versions, and the current development version of Ansible. Ansible Core versions before 2.14.0 are not supported. @@ -202,6 +198,12 @@ All contributions are welcome! As of release > 3.2.18, we will now be following Ansible's development patterns for implementing Ansible's changelog fragments. This will require a changelog fragment to any PR that is not documentation or trivial. Most changelog entries will likely be `bugfixes` or `minor_changes`. Please refer to the documentation for [Ansible's changelog fragments](https://docs.ansible.com/ansible/devel/community/development_process.html#creating-changelog-fragments) to learn more. +## Questions or Support? + +CrowdStrike Ansible Collection is a community-driven, open source project aimed at simplifying the integration and utilization of CrowdStrike's Falcon platform with Ansible automation. While not an official CrowdStrike product, the CrowdStrike Ansible Collection is maintained by CrowdStrike and supported in collaboration with the open source developer community. + +For additional information, please refer to the [SUPPORT.md](./SUPPORT.md) file. + # License See the [license](LICENSE) for more information. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..ca7a0fb9 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,13 @@ +# CrowdStrike Ansible Collection Support + +CrowdStrike Ansible Collection is a community-driven, open source project aimed at simplifying the integration and utilization of CrowdStrike's Falcon platform with Ansible automation. While not an official CrowdStrike product, the CrowdStrike Ansible Collection is maintained by CrowdStrike and supported in collaboration with the open source developer community. + +## Issue Reporting and Questions + +Issues related to the CrowdStrike Ansible Collection can be reported [here](https://github.com/CrowdStrike/ansible_collection_falcon/issues/new/choose). These issues are utilized to track bugs, documentation updates, enhancement requests, and security concerns. + +## Support Escalation + +Our primary objective is to provide support for utilizing the CrowdStrike Ansible Collection within the repository itself. This approach helps to expand our online knowledge base, empowers the community with self-help resources, and potentially reduces the resolution time for queries. + +If you are a CrowdStrike customer and prefer to address your questions or issues directly with the CrowdStrike Support team, you are encouraged to [reach out to the CrowdStrike technical support team](https://supportportal.crowdstrike.com/). diff --git a/roles/falcon_configure/README.md b/roles/falcon_configure/README.md index ad39ef2f..ad7e8384 100644 --- a/roles/falcon_configure/README.md +++ b/roles/falcon_configure/README.md @@ -1,14 +1,13 @@ # crowdstrike.falcon.falcon_configure -This role configures the CrowdStrike Falcon Sensor. For Linux, this role requires the Falcon +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. -## Limitations - -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. +> [!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 @@ -40,6 +39,13 @@ future. - `falcon_windows_become_method` - The way to become a privileged user on Windows (string, default: ***runas***) - `falcon_windows_become_user` - The privileged user to install the sensor on Windows (string, default: ***SYSTEM***) +### macOS Specific Variables + +- `falcon_option_set` - Set True|yes to set options, False|no to delete. (bool, default: ***true***) +- `falcon_cid` - Your Falcon Customer ID (CID) if not using API creds (string, default: ***null***) +- `falcon_provisioning_token` - Falcon Installation Token (string, default: ***null***) +- `falcon_tags` - Sensor grouping tags are optional, user-defined identifiers you can use to group and filter hosts (string, default: ***null***) + ### Falconctl Variables (Linux Only) > This role uses the [crowdstrike.falcon.falconctl](../../plugins/modules/falconctl.py) Ansible Module to configure the Falcon Sensor on Linux. @@ -79,6 +85,11 @@ future. | falcon_tags | S/D | | falcon_backend | S/D | +## Configuring on macOS + +Apple platforms require Mobile Device Management (MDM) software to install kernel extensions without user prompting. +Ansible is only able to run on macOS in an interactive session, which means end-users will receive prompts to accept the CrowdStrike kernel modules without an MDM profile already established. + ## Falcon API Permissions API clients are granted one or more API scopes. Scopes allow access to specific CrowdStrike APIs and describe the actions that an API client can perform. @@ -105,6 +116,8 @@ How to set the Falcon Customer ID (CID) when CID is known: falcon_cid: 1234567890ABCDEF1234567890ABCDEF-12 ``` +---------- + How to set the Falcon Customer ID (CID) using API creds: ```yaml @@ -116,6 +129,8 @@ How to set the Falcon Customer ID (CID) using API creds: falcon_client_secret: ``` +---------- + How to set the Falcon Customer ID (CID) w/ provisioning token: ```yaml @@ -127,6 +142,8 @@ How to set the Falcon Customer ID (CID) w/ provisioning token: falcon_provisioning_token: 12345678 ``` +---------- + How to configure the Falcon Sensor Proxy: ```yaml @@ -139,6 +156,8 @@ How to configure the Falcon Sensor Proxy: falcon_app: 8080 ``` +---------- + This example shows how to set some of the other options: ```yaml @@ -151,6 +170,8 @@ This example shows how to set some of the other options: falcon_message_log: yes ``` +---------- + Examples of deleting options: ```yaml @@ -163,6 +184,8 @@ Examples of deleting options: falcon_tags: "" ``` +---------- + Delete Agent ID to prep Master Image: ```yaml diff --git a/roles/falcon_install/README.md b/roles/falcon_install/README.md index dc32ee54..39027291 100644 --- a/roles/falcon_install/README.md +++ b/roles/falcon_install/README.md @@ -1,7 +1,10 @@ # crowdstrike.falcon.falcon_install -This role installs the CrowdStrike Falcon Sensor. This role also supports installing -the sensor from a local file or remote URL. +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. + +> [!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. + ## Requirements @@ -26,7 +29,6 @@ The following variables are currently supported: - `falcon_allow_downgrade` - Whether or not to allow downgrading the sensor version (bool, default: ***false***) - `falcon_gpg_key_check` - Whether or not to verify the Falcon sensor Linux based package (bool, default: ***true***) -- `falcon_cid` - Specify CrowdStrike Customer ID with Checksum (string, default: ***null***) - :warning: When `falcon_install_method` is set to **api**, this value will be fetched by the API unless specified. - `falcon_install_tmp_dir` - Temporary Linux and MacOS installation directory for the Falson Sensor (string, default: ***/tmp***) - `falcon_retries` - Number of attempts to download the sensor (int, default: ***3***) @@ -63,6 +65,7 @@ The following variables are currently supported: ### Windows Specific Variables +- `falcon_cid` - Specify CrowdStrike Customer ID with Checksum (string, default: ***null***) - `falcon_windows_install_retries` - Number of times to retry sensor install on windows (int, default: ***10***) - `falcon_windows_install_delay` - Number of seconds to wait to retry sensor install on windows in the event of a failure (int, default: ***120***) - `falcon_windows_tmp_dir` - Temporary Windows installation directory for the Falson Sensor (string, default: ***%SYSTEMROOT%\\Temp***) @@ -148,6 +151,8 @@ This example installs the Falcon Sensor using a sensor update policy called "ACM falcon_sensor_update_policy_name: "ACME Policy" ``` +---------- + This example installs the Falcon Sensor from a local file, then removes it. ```yaml @@ -159,13 +164,25 @@ This example installs the Falcon Sensor from a local file, then removes it. falcon_install_method: file falcon_localfile_path: /tmp/falcon.deb falcon_localfile_cleanup: yes - falcon_cid: ``` -## Installing on MacOS +---------- + +This example installs and configures the Falcon Sensor on Windows: -Apple platforms require Mobile Device Management (MDM) software to install kernel extensions without user prompting. -Ansible is only able to run on macOS in an interactive session, which means end-users will receive prompts to accept the CrowdStrike kernel modules. +```yaml +--- +- hosts: all + roles: + - role: crowdstrike.falcon.falcon_install + vars: + falcon_client_id: + falcon_client_secret: + falcon_cid: + falcon_windows_install_args: "/norestart ProvWaitTime=600" + falcon_windows_become_method: runas + falcon_windows_become_user: SYSTEM +``` ## License