From 9d499f106e46062c23dfc447b358cdfdb04d2b61 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 11 Apr 2024 16:30:14 -0400 Subject: [PATCH 1/4] fix(kernel_support_info): adding new module that supports querying kernel compat info --- .gitignore | 1 + README.md | 1 + plugins/modules/kernel_support_info.py | 244 +++++++++++++++++++++++++ 3 files changed, 246 insertions(+) create mode 100644 plugins/modules/kernel_support_info.py diff --git a/.gitignore b/.gitignore index 0f2097c3..99b46c62 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ changelogs/.plugin-cache.yaml __pycache__/ /**venv /.vscode +html/ diff --git a/README.md b/README.md index 13d67f88..526c5ee1 100644 --- a/README.md +++ b/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 diff --git a/plugins/modules/kernel_support_info.py b/plugins/modules/kernel_support_info.py new file mode 100644 index 00000000..b013876e --- /dev/null +++ b/plugins/modules/kernel_support_info.py @@ -0,0 +1,244 @@ +#!/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. + +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). + +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}, + "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() From 0edc3655e5cf674adbdb5277e32359f9b46940b1 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 11 Apr 2024 16:38:29 -0400 Subject: [PATCH 2/4] fix: update doc fragment to separate sort option --- plugins/doc_fragments/info.py | 6 +++++- plugins/modules/sensor_download_info.py | 1 + plugins/modules/sensor_update_policy_info.py | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/plugins/doc_fragments/info.py b/plugins/doc_fragments/info.py index 13a1a7f5..1054838c 100644 --- a/plugins/doc_fragments/info.py +++ b/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. diff --git a/plugins/modules/sensor_download_info.py b/plugins/modules/sensor_download_info.py index 05f20fc2..43176986 100644 --- a/plugins/modules/sensor_download_info.py +++ b/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 diff --git a/plugins/modules/sensor_update_policy_info.py b/plugins/modules/sensor_update_policy_info.py index 26f575d5..554d6043 100644 --- a/plugins/modules/sensor_update_policy_info.py +++ b/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 From 5ceae44e07433f84b4600353d48ac86877971900 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 11 Apr 2024 16:51:51 -0400 Subject: [PATCH 3/4] fix: fixes ansible-test found issues --- plugins/modules/kernel_support_info.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/modules/kernel_support_info.py b/plugins/modules/kernel_support_info.py index b013876e..17b86252 100644 --- a/plugins/modules/kernel_support_info.py +++ b/plugins/modules/kernel_support_info.py @@ -21,6 +21,7 @@ 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: @@ -41,6 +42,7 @@ - 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 @@ -189,7 +191,7 @@ POLICY_ARGS = { "filter": {"type": "str", "required": False}, - "limit": {"type": "int", "required": False}, + "limit": {"type": "int", "required": False, "default": 100}, "offset": {"type": "int", "required": False}, } From d6829e697f77bc671ce6cbdf177ab9415b448555 Mon Sep 17 00:00:00 2001 From: Carlos Matos Date: Thu, 11 Apr 2024 17:04:11 -0400 Subject: [PATCH 4/4] chore(kernel_support_info): add changelog fragment --- plugins/doc_fragments/kernel_support_info.yml | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 plugins/doc_fragments/kernel_support_info.yml diff --git a/plugins/doc_fragments/kernel_support_info.yml b/plugins/doc_fragments/kernel_support_info.yml new file mode 100644 index 00000000..82e730f9 --- /dev/null +++ b/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)