Devel pre release updates (#406)

Update devel branch in preparation for v4 release. --------- Co-authored-by: Evan Stoner <[email protected]>
CrowdStrike · Sep 15, 2023 · d9336bd · d9336bd
1 parent 4d67c73
commit d9336bd
Show file tree

Hide file tree

Showing 14 changed files with 287 additions and 56 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,6 +5,41 @@ Ansible CrowdStrike Falcon Collection Release Notes
 .. contents:: Topics
 
 
+v3.3.3
+======
+
+Release Summary
+---------------
+
+| Release Date: 2023-09-14
+| `Release Notes: <https://github.com/CrowdStrike/ansible_collection_falcon/releases/tag/3.3.3>`__
+
+
+Bugfixes
+--------
+
+- update ansible meta information for certifiable requirements (https://github.com/CrowdStrike/ansible_collection_falcon/pull/405)
+
+v3.3.2
+======
+
+Release Summary
+---------------
+
+| Release Date: 2023-09-11
+| `Release Notes: <https://github.com/CrowdStrike/ansible_collection_falcon/releases/tag/3.3.2>`__
+
+
+Minor Changes
+-------------
+
+- falcon_uninstall - Adds hide/remove host functionality (https://github.com/CrowdStrike/ansible_collection_falcon/pull/393)
+
+Bugfixes
+--------
+
+- falcon_configure - add become clause to remove_aid tasks (https://github.com/CrowdStrike/ansible_collection_falcon/pull/392)
+
 v3.3.1
 ======
 

diff --git a/README.md b/README.md
@@ -6,19 +6,45 @@
 
 # Ansible Collection - crowdstrike.falcon
 
-This collection is focused on installing, configuring, and removing CrowdStrike's Falcon sensor on macOS, Linux, and Windows.
+The Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions with the CrowdStrike Falcon platform.
+
+## :mega: Announcements
+
+**September 15, 2023:** We are excited to announce that Version 4 of the Falcon Ansible Collection has been officially launched. Version 4 will provide us with numerous
+advantages that align well with our ongoing automation and cybersecurity strategies. By extending the power of the FalconPy SDK, Version 4 will be instrumental in interacting with
+and automating the Falcon platform.
+
+### Important Notice for Version 3
+
+- **New Branch:** Version 3 will be moved to its own dedicated branch [v3](https://github.com/CrowdStrike/ansible_collection_falcon/tree/v3) to allow for isolated maintenance
+  and bug fixes.
+- **No New Features:** Version 3 will not receive any new features moving forward. We will only release bug fixes to maintain its stability. This is to allow us to focus our
+  development efforts on Version 4.
+- **Limited Support:** Version 3 will continue to receive bug fixes until **February 1st, 2024**. After that date, we will no longer provide updates or support for Version 3.
+
+### How to upgrade
+
+We strongly encourage you to upgrade to Version 4 to benefit from new features and ongoing support. Please see the [Installing this collection](#installing-this-collection) section to get started.
+
+### 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.
 
-<!--start requires_ansible-->
 ## Ansible version compatibility
 
-Tested with the Ansible Core >= 2.12.0 versions, and the current development version of Ansible. Ansible Core versions before 2.12.0 are not supported.
-<!--end requires_ansible-->
+Tested with the Ansible Core >= 2.13.0 versions, and the current development version of Ansible. Ansible Core versions before 2.13.0 are not supported.
+
+## Python version compatibility
+
+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.6` is required for this collection to function properly.
 
 ## Included content
 
 ### Roles
 
-> Please read each role's README to familiarize yourself with the role variables and other requirements.
+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.*
 
 | Role Name | Documentation | Build Status Linux | Build Status Windows |
 | --------- | :-----------: | ------------------ | -------------------- |
@@ -40,61 +66,114 @@ Name | Description
 [crowdstrike.falcon.sensor_download_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_download_info.html#ansible-collections-crowdstrike-falcon-sensor-download-info-module)|Get information about Falcon Sensor Installers
 [crowdstrike.falcon.sensor_update_policy_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_update_policy_info.html#ansible-collections-crowdstrike-falcon-sensor-update-policy-info-module)|Get information about Falcon Update Sensor Policies
 
-
-### Inventory Plugins
+### Inventory plugins
 
 Name | Description
 --- | ---
 [crowdstrike.falcon.falcon_discover](https://crowdstrike.github.io/ansible_collection_falcon/falcon_discover_inventory.html#ansible-collections-crowdstrike-falcon-falcon-discover-inventory-plugin)|Falcon Discover inventory source
 <!--end collection content-->
 
 <!--start eda content-->
-### Event Sources
+### Event sources
 
-> Ansible EDA (Event Driven Ansible) is a new way to connect to sources of events and act on those events using rulebooks. For more information, see the [EDA documentation](https://ansible.readthedocs.io/projects/rulebook/en/latest/introduction.html).
+Ansible EDA (Event Driven Ansible) is a new way to connect to sources of events and act on those events using rulebooks. For more information, see the [EDA documentation](https://ansible.readthedocs.io/projects/rulebook/en/latest/introduction.html).
 
 Name | Description
 --- | ---
 [crowdstrike.falcon.eventstream](./docs/crowdstrike.falcon.eventstream.md) | Receive events from CrowdStrike Falcon Event Stream.
 
 <!--end eda content-->
 
-## Using this collection
+## Installing this collection
 
-Before using the collection, you need to install the collection with the `ansible-galaxy` CLI:
+### Using `ansible-galaxy` CLI
 
-```bash
+To install the Falcon Ansible Collection using the command-line interface, execute the following:
+
+```terminal
 ansible-galaxy collection install crowdstrike.falcon
 ```
 
-You can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml` using the format:
+### Using a `requirements.yml` File
+
+To include the collection in a `requirements.yml` file and install it through `ansible-galaxy`, use the following format:
 
 ```yaml
+---
 collections:
   - crowdstrike.falcon
 ```
 
-**Note** that if you install the collection from Ansible Galaxy, it will not be upgraded automatically when you upgrade the `ansible` package. To upgrade the collection to the latest available version, run the following command:
+Then run:
 
-```bash
-ansible-galaxy collection install crowdstrike.falcon --upgrade
+```terminal
+ansible-galaxy collection install -r requirements.yml
 ```
 
-You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version `0.1.0`:
+### Additional notes
+
+- **Upgrading the Collection**: Note that if you've installed the collection from Ansible Galaxy, it won't automatically update when you upgrade the `ansible` package. To manually upgrade to the latest version, use:
+
+    ```terminal
+    ansible-galaxy collection install crowdstrike.falcon --upgrade
+    ```
 
-```bash
-ansible-galaxy collection install crowdstrike.falcon:==0.1.0
+- **Installing a Specific Version**: If you need to install a particular version of the collection (for example, to downgrade due to an issue), you can specify the version as follows:
+
+    ```terminal
+    ansible-galaxy collection install crowdstrike.falcon:==0.1.0
+    ```
+
+### Python dependencies
+
+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:
+
+    ```terminal
+    pip install -r requirements.txt
+    ```
+
+2. Alternatively, install the CrowdStrike FalconPy package directly:
+
+    ```terminal
+    pip install crowdstrike-falconpy
+    ```
+
+> [!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
+outlining the various authentication mechanisms supported. Check out the [Authentication Guide](docs/authentication.md) for step-by-step instructions.
+
+## Using this collection
+
+### Example using modules
+
+```yaml
+---
+  - name: Get a list of the 2 latest Windows Sensor Installers
+    crowdstrike.falcon.sensor_download_info:
+      client_id: <FALCON_CLIENT_ID>
+      client_secret: <FALCON_CLIENT_SECRET>
+      cloud: us-2
+      limit: 2
+      filter: "platform_name:'windows'"
+      sort: "version|desc"
+    delegate_to: localhost
 ```
 
-### Example Playbook
+### Example using the built-in roles to install Falcon
 
 Install and configure the CrowdStrike Falcon Sensor at version N-2:
 
 ```yaml
 - hosts: all
   vars:
-    falcon_client_id: <Falcon_UI_OAUTH_client_id>
-    falcon_client_secret: <Falcon_UI_OAUTH_client_secret>
+    falcon_client_id: <FALCON_CLIENT_ID>
+    falcon_client_secret: <FALCON_CLIENT_SECRET>
   roles:
   - role: crowdstrike.falcon.falcon_install
     vars:
@@ -105,19 +184,14 @@ Install and configure the CrowdStrike Falcon Sensor at version N-2:
       falcon_tags: 'falcon,example,tags'
 ```
 
-### Example Using the Event Stream EDA Source via Ansible Rulebook
+### Example using the Event Stream EDA source via Ansible Rulebook
 
-> This example requires Ansible EDA to be installed. See the [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html) for more information.
+This example requires Ansible EDA to be installed. See the [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html) for more information.
 
 ```shell
 ansible-rulebook -i inventory -r crowdstrike.falcon.event_stream_example -E FALCON_CLIENT_ID,FALCON_CLIENT_SECRET
 ```
 
-## Installing 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.
-
 ## Release Notes
 
 See the [changelog](./CHANGELOG.rst) for a history of notable changes to this collection.
@@ -131,6 +205,7 @@ See the [changelog](./CHANGELOG.rst) for a history of notable changes to this co
 - [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
 - [Ansible Rulebook Introduction](https://ansible.readthedocs.io/projects/rulebook/en/latest/getting_started.html)
 - [Event Driven Ansible Introduction](https://www.ansible.com/blog/getting-started-with-event-driven-ansible)
+- [CrowdStrike FalconPy SDK](https://www.falconpy.io/)
 
 ## Contributing
 

diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml
@@ -305,3 +305,32 @@ releases:
     - 3.3.1.yml
     - eda-tox.yml
     release_date: '2023-08-17'
+  3.3.2:
+    changes:
+      bugfixes:
+      - falcon_configure - add become clause to remove_aid tasks (https://github.com/CrowdStrike/ansible_collection_falcon/pull/392)
+      minor_changes:
+      - falcon_uninstall - Adds hide/remove host functionality (https://github.com/CrowdStrike/ansible_collection_falcon/pull/393)
+      release_summary: '| Release Date: 2023-09-11
+
+        | `Release Notes: <https://github.com/CrowdStrike/ansible_collection_falcon/releases/tag/3.3.2>`__
+
+        '
+    fragments:
+    - 3.3.2.yml
+    - fix-become-issue-aid.yml
+    - remove-host.yml
+    release_date: '2023-09-11'
+  3.3.3:
+    changes:
+      bugfixes:
+      - update ansible meta information for certifiable requirements (https://github.com/CrowdStrike/ansible_collection_falcon/pull/405)
+      release_summary: '| Release Date: 2023-09-14
+
+        | `Release Notes: <https://github.com/CrowdStrike/ansible_collection_falcon/releases/tag/3.3.3>`__
+
+        '
+    fragments:
+    - 3.3.3.yml
+    - meta-update.yml
+    release_date: '2023-09-14'
diff --git a/changelogs/fragments/fix-become-issue-aid.yml b/changelogs/fragments/fix-become-issue-aid.yml
diff --git a/changelogs/fragments/remove-host.yml b/changelogs/fragments/remove-host.yml
diff --git a/changelogs/fragments/sensor-policy-info.yml b/changelogs/fragments/sensor-policy-info.yml
diff --git a/changelogs/fragments/v4-updates.yml b/changelogs/fragments/v4-updates.yml
@@ -0,0 +1,18 @@
+minor_changes:
+  - sensor_policy_info - adds ``sensor_policy_info`` module to retrieve sensor policy information from the CrowdStrike Falcon API (https://github.com/CrowdStrike/ansible_collection_falcon/pull/251)
+  - auth - adds ``auth`` module to manage authentication with the Falcon API (https://github.com/CrowdStrike/ansible_collection_falcon/pull/384)
+  - cid_info - adds ``cid_info`` module to help retrieve CID with checksum (https://github.com/CrowdStrike/ansible_collection_falcon/pull/395)
+  - sensor_download_info - adds ``sensor_download_info`` module to retrieve sensor installers to download (https://github.com/CrowdStrike/ansible_collection_falcon/pull/396)
+  - sensor_download - adds ``sensor_download`` module to download sensor from the Falcon API (https://github.com/CrowdStrike/ansible_collection_falcon/pull/396)
+  - falcon_install - replaces existing API functionality with new modules (https://github.com/CrowdStrike/ansible_collection_falcon/pull/396)
+  - host_hide - adds ``host_hide`` module to hide/unhide hosts from the Falcon console (https://github.com/CrowdStrike/ansible_collection_falcon/pull/399)
+  - falcon_discover - adds a new dynamic inventory for the Discover service collection (https://github.com/CrowdStrike/ansible_collection_falcon/pull/400)
+
+bugfixes:
+  - falcon_configure - add missing when clause for mac task (https://github.com/CrowdStrike/ansible_collection_falcon/pull/399)
+  - cid_info - return the first element of the array (https://github.com/CrowdStrike/ansible_collection_falcon/pull/396)
+
+breaking_changes:
+  - falconpy - new collection requirements for authenticating with the CrowdStrike Falcon API now require the falconpy sdk. All
+    existing roles within the collection have been ported over and should use the ``./requirements.txt`` file to get started.
+    (https://github.com/CrowdStrike/ansible_collection_falcon/pull/384)
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -0,0 +1,78 @@
+# Authentication Guide
+
+The Falcon Ansible collection requires authenticating against the Falcon API. To do so you will
+need client credentials. For more information see [Falcon API clients documentation](https://falcon.crowdstrike.com/documentation/page/a2a7fc0e/crowdstrike-oauth2-based-apis#mf8226da).
+
+## Passing in credentials
+
+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)
+
+Available module arguments:
+
+```yaml
+- crowdstrike.falcon.example_module:
+    client_id: abcd1234 # required
+    client_secret: abcd5678 # required
+    cloud: us-2 # optional (discovered automatically)
+    member_cid: abcd2468 # optional (only for Flight Control users)
+```
+
+You can use either of these methods for both authentication methods listed below.
+
+## Authenticating with the Falcon API
+
+### 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. 
+(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:
+
+```yaml
+- name: Generate Authentication Object
+  crowdstrike.falcon.auth:
+    # If not using ENV variables, use module args here
+  register: falcon
+```
+
+After obtaining the auth object, you can pass it to other modules to use the same authentication details:
+
+```yaml
+- name: Individually hide hosts with a list from the Falcon console
+  crowdstrike.falcon.host_hide:
+    auth: "{{ falcon.auth }}"
+    hosts: "{{ item }}"
+  loop: "{{ host_ids }}"
+```
+
+For more details on token-based authentication, see documentation for the `crowdstrike.falcon.auth` module.
+
+### Alternative: per-task authentication
+
+If you are only running a small number of tasks against the Falcon API, you can authenticate directly in the task:
+
+```yaml
+- crowdstrike.falcon.cid_info:
+    client_id: "API CLIENT ID"
+    client_secret: "API CLIENT SECRET"
+    # Optional
+    member_cid: "MEMBER CID"
+    cloud: "eu-1"
+  register: cid_info
+```
+
+Per-task authentication also supports environment variables:
+
+```yaml
+# assumes FALCON_CLIENT_ID and FALCON_CLIENT_SECRET have been set
+- crowdstrike.falcon.cid_info:
+  register: cid_info
+```