feat: add new sensor update builds info module

.gitignore

@@ -7,3 +7,4 @@ __pycache__/
 /**venv
 /.vscode
 html/
+ansible.cfg

README.md

@@ -47,6 +47,7 @@ Name | Description
 [crowdstrike.falcon.kernel_support_info](https://crowdstrike.github.io/ansible_collection_falcon/kernel_support_info_module.html)|Get information about kernels supported by the Falcon Sensor for Linux
 [crowdstrike.falcon.sensor_download](https://crowdstrike.github.io/ansible_collection_falcon/sensor_download_module.html)|Download Falcon Sensor Installer
 [crowdstrike.falcon.sensor_download_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_download_info_module.html)|Get information about Falcon Sensor Installers
+[crowdstrike.falcon.sensor_update_builds_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_update_builds_info_module.html)|Get a list of available sensor build versions
 [crowdstrike.falcon.sensor_update_policy_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_update_policy_info_module.html)|Get information about Falcon Update Sensor Policies
 
 ### Inventory plugins

changelogs/fragments/sensor_update_builds_info.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - sensor_update_builds_info - adds new module for retrieving sensor build versions (https://github.com/CrowdStrike/ansible_collection_falcon/pull/500)

galaxy.yml

@@ -21,8 +21,8 @@ authors:
 
 # A short summary description of the collection
 description: >
-  A collection of roles developed by CrowdStrike for the
-  installation, configuration, and verification of CrowdStrike's software.
+  The Falcon Ansible Collection serves as a comprehensive toolkit for streamlining your interactions
+  with the CrowdStrike Falcon platform.
 
 # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
 # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'

plugins/modules/sensor_update_builds_info.py

@@ -0,0 +1,178 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2024, CrowdStrike Inc.
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+---
+module: sensor_update_builds_info
+
+short_description: Get a list of available sensor build versions
+
+version_added: "4.4.0"
+
+description:
+  - Returns a list of the available sensor build versions that you can use in your policies.
+
+options:
+  platform:
+    description:
+      - Limit the results to a specific platform.
+      - If not specified, builds for all platforms are returned.
+    type: str
+    choices:
+      - windows
+      - linux
+      - linuxarm64
+      - zlinux
+      - mac
+  stage:
+    description:
+      - Limit the results to a specific stage.
+      - If not specified, only builds in the prod stage are returned.
+    type: str
+    choices:
+      - prod
+      - early_adopter
+    default: prod
+
+extends_documentation_fragment:
+    - crowdstrike.falcon.credentials
+    - crowdstrike.falcon.credentials.auth
+
+requirements:
+  - Sensor update policies [B(READ)] API scope
+
+author:
+  - Carlos Matos (@carlosmmatos)
+"""
+
+EXAMPLES = r"""
+- name: Get all sensor build versions
+  crowdstrike.falcon.sensor_update_builds_info:
+
+- name: Get all sensor build versions for the Windows platform
+  crowdstrike.falcon.sensor_update_builds_info:
+    platform: windows
+"""
+
+RETURN = r"""
+builds:
+    description:
+      - A list of available sensor build versions.
+    type: list
+    returned: success
+    elements: dict
+    contains:
+      build:
+        description:
+          - The complete build version value.
+          - For automatic builds, this can include build stage and tagged identifiers.
+        type: str
+        returned: success
+        sample: "16410|n|tagged|11"
+      platform:
+        description: The platform for which the build is available.
+        type: str
+        returned: success
+        sample: "Windows"
+      sensor_version:
+        description: The version of the sensor associated with the build.
+        type: str
+        returned: success
+        sample: "6.49.16303"
+      stage:
+        description: The stage of the build.
+        type: str
+        returned: success
+        sample: "prod"
+"""
+
+import traceback
+
+from ansible.module_utils.basic import AnsibleModule, missing_required_lib
+from ansible_collections.crowdstrike.falcon.plugins.module_utils.common_args import (
+    falconpy_arg_spec,
+)
+from ansible_collections.crowdstrike.falcon.plugins.module_utils.falconpy_utils import (
+    authenticate,
+    check_falconpy_version,
+    handle_return_errors,
+)
+
+FALCONPY_IMPORT_ERROR = None
+try:
+    from falconpy import SensorUpdatePolicy
+
+    HAS_FALCONPY = True
+except ImportError:
+    HAS_FALCONPY = False
+    FALCONPY_IMPORT_ERROR = traceback.format_exc()
+
+POLICY_ARGS = {
+    "platform": {
+        "type": "str",
+        "required": False,
+        "choices": ["windows", "linux", "linuxarm64", "zlinux", "mac"]
+    },
+    "stage": {
+        "type": "str",
+        "required": False,
+        "choices": ["prod", "early_adopter"],
+        "default": "prod"
+    },
+}
+
+
+def argspec():
+    """Define the module's argument spec."""
+    args = falconpy_arg_spec()
+    args.update(POLICY_ARGS)
+
+    return args
+
+
+def main():
+    """Entry point for module execution."""
+    module = AnsibleModule(
+        argument_spec=argspec(),
+        supports_check_mode=True,
+    )
+
+    if not HAS_FALCONPY:
+        module.fail_json(
+            msg=missing_required_lib("falconpy"), exception=FALCONPY_IMPORT_ERROR
+        )
+
+    check_falconpy_version(module)
+
+    args = {}
+    for key, value in module.params.items():
+        if key in POLICY_ARGS:
+            args[key] = value
+
+    falcon = authenticate(module, SensorUpdatePolicy)
+
+    query_result = falcon.query_combined_builds(**args)
+
+    result = dict(
+        changed=False,
+    )
+
+    if query_result["status_code"] == 200:
+        result.update(
+            builds=query_result["body"]["resources"],
+        )
+
+    handle_return_errors(module, result, query_result)
+
+    module.exit_json(**result)
+
+
+if __name__ == "__main__":
+    main()