Merge pull request #499 from carlosmmatos/kernel-compat-module

feat(kernel_support_info): adding new module that supports querying kernel compat info

.gitignore

@@ -6,3 +6,4 @@ changelogs/.plugin-cache.yaml
 __pycache__/
 /**venv
 /.vscode
+html/

README.md

@@ -44,6 +44,7 @@ Name | Description
 [crowdstrike.falcon.cid_info](https://crowdstrike.github.io/ansible_collection_falcon/cid_info_module.html)|Get CID with checksum
 [crowdstrike.falcon.host_contain](https://crowdstrike.github.io/ansible_collection_falcon/host_contain_module.html)|Network contain hosts in Falcon
 [crowdstrike.falcon.host_hide](https://crowdstrike.github.io/ansible_collection_falcon/host_hide_module.html)|Hide/Unhide hosts from the Falcon console
+[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_policy_info](https://crowdstrike.github.io/ansible_collection_falcon/sensor_update_policy_info_module.html)|Get information about Falcon Update Sensor Policies

plugins/doc_fragments/info.py

@@ -17,7 +17,7 @@ class ModuleDocFragment(object):
   filter:
     description:
       - The filter expression that should be used to limit the results using FQL (Falcon Query Language) syntax.
-      - See the return values for more information about the available filters that can be used.
+      - See the return values or CrowdStrike docs for more information about the available filters that can be used.
     type: str
   limit:
     description:
@@ -28,6 +28,10 @@ class ModuleDocFragment(object):
     description:
       - The offset to start retrieving records from.
     type: int
+"""
+    # Not all endpoints will have a sort option
+    SORT = r"""
+options:
   sort:
     description:
       - The property to sort by in FQL (Falcon Query Language) syntax.

plugins/doc_fragments/kernel_support_info.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - kernel_support_info - adds new module for kernel support information (https://github.com/CrowdStrike/ansible_collection_falcon/pull/499)

plugins/modules/kernel_support_info.py

@@ -0,0 +1,246 @@
+#!/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: kernel_support_info
+
+short_description: Get information about kernels supported by the Falcon Sensor for Linux
+
+version_added: "4.1.0"
+
+description:
+  - Retrieve details about the kernels supported by the Falcon sensor
+    for Linux (kernel mode), matching the specified filter criteria.
+  - See the L(CrowdStrike documentation,https://falcon.crowdstrike.com/login/?unilogin=true&next=/documentation/page/cf432222/sensor-update-policy-apis#t6a20418)
+    for more information about available filters.
+    # noqa: E501
+
+options:
+  limit:
+    description:
+      - The maximum number of records to return. [1-500]
+      - Use with the offset parameter to manage pagination of results.
+    type: int
+    default: 100
+
+extends_documentation_fragment:
+  - crowdstrike.falcon.credentials
+  - crowdstrike.falcon.credentials.auth
+  - crowdstrike.falcon.info
+
+notes:
+  - This module will return a list of supported kernel information for kernel mode only of the
+    Falcon sensor for Linux. This is not for user mode.
+  - To help with your filters, you can use the kernel and sensor support distinct values API to
+    retrieve a list of distinct values, with proper syntax, for any field. For more info, see
+    L(Retrieving field values for kernel support filters,https://falcon.crowdstrike.com/login/?unilogin=true&next=/documentation/page/cf432222/sensor-update-policy-apis#v3cee3bb).
+    # noqa: E501
+
+requirements:
+  - Sensor update policies [B(READ)] API scope
+
+author:
+  - Carlos Matos (@carlosmmatos)
+"""
+
+EXAMPLES = r"""
+- name: Show support info for all Ubuntu 20 kernels that have a release starting with 5.8
+  crowdstrike.falcon.kernel_support_info:
+    filter: "vendor:'ubuntu'+distro:'ubuntu20'+release:*'5.8.*'"
+
+- name: Show support info for kernels with a release of 5.4.0-1040-gcp and an architecture of x86_64
+  crowdstrike.falcon.kernel_support_info:
+    filter: "release:'5.4.0-1040-gcp'+architecture:'x86_64'"
+
+- name: Show support info using kernel and architecture from ansible_facts
+  crowdstrike.falcon.kernel_support_info:
+    filter: "release:'{{ ansible_facts['kernel'] }}'+architecture:'{{ ansible_facts['architecture'] }}'"
+"""
+
+RETURN = r"""
+info:
+  description: A list of support information for the kernels that match the filter criteria
+  returned: success
+  type: list
+  elements: dict
+  contains:
+    architecture:
+      description: The Linux kernel architecture.
+      returned: success
+      type: str
+      sample: x86_64
+    base_package_supported_sensor_versions:
+      description:
+        - Sensor versions that support the specified kernel in the base sensor package.
+        - These sensor versions support the kernel when they are installed.
+      returned: success
+      type: list
+      elements: str
+      sample: [
+        "X.YY.Z-1101",
+        "X.YY.Z-1102"
+      ]
+    created_timestamp:
+      description: The timestamp when the kernel support information was created.
+      returned: success
+      type: str
+      sample: "2021-01-01 00:00:00"
+    distro:
+      description: The Linux distribution associated with the kernel.
+      returned: success
+      type: str
+      sample: ubuntu20
+    distro_version:
+      description: The Linux distribution version associated with the kernel.
+      returned: success
+      type: str
+      sample: 18.x
+    flavor:
+      description: The Linux kernel flavor.
+      returned: success
+      type: str
+      sample: generic
+    id:
+      description: The unique identifier of the kernel support information.
+      returned: success
+      type: str
+      sample: 8s0t9k3zr2o7h5x1d4g6nqjfywlbepmau
+    modified_timestamp:
+      description: The timestamp when the kernel support information was last modified.
+      returned: success
+      type: str
+      sample: "2021-01-01 00:00:00"
+    release:
+      description: The Linux kernel release version.
+      returned: success
+      type: str
+      sample: 5.4.0-1040-gcp
+    vendor:
+      description: The Linux vendor associated with the kernel.
+      returned: success
+      type: str
+      sample: ubuntu
+    version:
+      description: Full Linux OS version identifier.
+      returned: success
+      type: str
+      sample: "#95-Ubuntu SMP Wed Sep 9 15:51:28 UTC 2020"
+    ztl_module_supported_sensor_versions:
+      description:
+        - Sensor versions that added support using the ZTL module support method.
+        - These updates are generated without source modifications to the deployed sensor
+          and enable the sensor to support the new kernel via offset mapping without having
+          to upgrade to a newer sensor version.
+      returned: success
+      type: list
+      elements: str
+      sample: [
+        "X.YY.Z-1101",
+        "X.YY.Z-1102"
+      ]
+    ztl_supported_sensor_versions:
+      description:
+        - Sensor versions that added support using the Zero Touch Linux (ZTL) support method.
+        - This method adds support for kernels through channel files without requiring a sensor update.
+      returned: success
+      type: list
+      elements: str
+      sample: [
+        "X.YY.Z-1101",
+        "X.YY.Z-1102"
+      ]
+pagination:
+  description: Pagination details for the query.
+  type: dict
+  returned: success
+  sample: {
+    "limit": 5000,
+    "offset": 0,
+    "total": 1
+  }
+"""
+
+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 = {
+    "filter": {"type": "str", "required": False},
+    "limit": {"type": "int", "required": False, "default": 100},
+    "offset": {"type": "int", "required": False},
+}
+
+
+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_kernels(**args)
+
+    result = dict(
+        changed=False,
+    )
+
+    if query_result["status_code"] == 200:
+        result.update(
+            info=query_result["body"]["resources"],
+            pagination=query_result["body"]["meta"]["pagination"],
+        )
+
+    handle_return_errors(module, result, query_result)
+
+    module.exit_json(**result)
+
+
+if __name__ == "__main__":
+    main()

plugins/modules/sensor_download_info.py

@@ -30,6 +30,7 @@
   - crowdstrike.falcon.credentials
   - crowdstrike.falcon.credentials.auth
   - crowdstrike.falcon.info
+  - crowdstrike.falcon.info.sort
 
 requirements:
   - Sensor download [B(READ)] API scope

plugins/modules/sensor_update_policy_info.py

@@ -33,6 +33,7 @@
     - crowdstrike.falcon.credentials
     - crowdstrike.falcon.credentials.auth
     - crowdstrike.falcon.info
+    - crowdstrike.falcon.info.sort
 
 requirements:
   - Sensor update policies [B(READ)] API scope