feat(info modules): enhance pagination and remove limits (#558)

* feat(info modules): enhance pagination and remove limits

Closes #556

Limits are not consistent within our APIs to offer them modularly.
Instead, you can use native Ansible to further refine and limit the info
modules as needed.

* chore: add doc fragment

changelogs/fragments/info-updates.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- Enhance the info modules with how pagination is handled and clean options (https://github.com/CrowdStrike/ansible_collection_falcon/pull/558)

plugins/module_utils/falconpy_utils.py

@@ -117,29 +117,29 @@ def handle_return_errors(module, result, query_result):
             module.fail_json(msg=msg, **result)
 
 
-def get_paginated_results_info(module, qfilter, limit, method):
+def get_paginated_results_info(module, args, limit, method, list_name):
     """Return paginated results from the Falcon API for info modules."""
     result = dict(
         changed=False,
-        info=[],
+        **{list_name: []},
     )
 
     max_limit = limit
     offset = None
     running = True
     while running:
-        query_result = method(filter=qfilter, offset=offset, limit=max_limit)
+        query_result = method(**args, offset=offset, limit=max_limit)
         if query_result["status_code"] != 200:
             handle_return_errors(module, result, query_result)
 
         if query_result["body"]["resources"]:
-            result["info"].extend(query_result["body"]["resources"])
+            result[list_name].extend(query_result["body"]["resources"])
         else:
             return result
 
         # Check if we need to continue
         offset = query_result["body"]["meta"]["pagination"]["offset"]
-        if query_result["body"]["meta"]["pagination"]["total"] <= len(result["info"]):
+        if query_result["body"]["meta"]["pagination"]["total"] <= len(result[list_name]):
             running = False
 
     return result

plugins/modules/kernel_support_info.py

@@ -199,12 +199,22 @@ def main():
 
     check_falconpy_version(module)
 
-    query_filter = module.params.get("filter")
+    args = {}
+    for key, value in module.params.items():
+        if key in POLICY_ARGS:
+            args[key] = value
+
     max_limit = 500
 
     falcon = authenticate(module, SensorUpdatePolicy)
 
-    result = get_paginated_results_info(module, query_filter, max_limit, falcon.query_combined_kernels)
+    result = get_paginated_results_info(
+        module,
+        args,
+        max_limit,
+        falcon.query_combined_kernels,
+        list_name="info"
+    )
 
     module.exit_json(**result)
 

plugins/modules/sensor_download_info.py

@@ -25,11 +25,6 @@
       - The filter expression that should be used to limit the results using FQL (Falcon Query Language) syntax.
       - See the return values or CrowdStrike docs for more information about the available filters that can be used.
     type: str
-  limit:
-    description:
-      - The maximum number of records to return. [1-500]
-    default: 100
-    type: int
 
 extends_documentation_fragment:
   - crowdstrike.falcon.credentials
@@ -44,14 +39,12 @@
 """
 
 EXAMPLES = r"""
-- name: Get a list of all Linux Sensor Installers
+- name: Get all Linux Sensor Installers
   crowdstrike.falcon.sensor_download_info:
     filter: "platform:'linux'"
-    limit: 200
 
-- name: Get a list of the 2 latest Windows Sensor Installers
+- name: Get all Windows Sensor Installers sorted by version
   crowdstrike.falcon.sensor_download_info:
-    limit: 2
     filter: "platform:'windows'"
     sort: "version|desc"
 
@@ -150,7 +143,6 @@
 
 DOWNLOAD_INFO_ARGS = {
     "filter": {"type": "str", "required": False},
-    "limit": {"type": "int", "required": False, "default": 100},
     "sort": {"type": "str", "required": False},
 }
 
@@ -184,6 +176,7 @@ def main():
 
     falcon = authenticate(module, SensorDownload)
 
+    # Pagination is not supported, so we can just call the API directly
     query_result = falcon.override("GET", "/sensors/combined/installers/v2", parameters={**args})
 
     result = dict(

plugins/modules/sensor_update_policy_info.py

@@ -51,10 +51,6 @@
   crowdstike.falcon.sensor_update_policy_info:
     filter: "platform_name:'Windows'+enabled:'true'"
 
-- name: Get Sensor Policies with a limit of 10
-  crowdstike.falcon.sensor_update_policy_info:
-    limit: 10
-
 - name: Get Sensor Policies and sort assending by platform_name
   crowdstike.falcon.sensor_update_policy_info:
     sort: "platform_name.asc"
@@ -177,15 +173,6 @@
         sample: {
           "build": "n-1|tagged"
         }
-pagination:
-  description: Pagination details for the query.
-  type: dict
-  returned: success
-  sample: {
-    "limit": 5000,
-    "offset": 0,
-    "total": 1
-  }
 """
 
 import traceback
@@ -197,7 +184,7 @@
 from ansible_collections.crowdstrike.falcon.plugins.module_utils.falconpy_utils import (
     authenticate,
     check_falconpy_version,
-    handle_return_errors,
+    get_paginated_results_info,
 )
 
 FALCONPY_IMPORT_ERROR = None
@@ -211,8 +198,6 @@
 
 POLICY_ARGS = {
     "filter": {"type": "str", "required": False},
-    "limit": {"type": "int", "required": False},
-    "offset": {"type": "int", "required": False},
     "sort": {"type": "str", "required": False},
 }
 
@@ -244,22 +229,18 @@ def main():
         if key in POLICY_ARGS:
             args[key] = value
 
-    falcon = authenticate(module, SensorUpdatePolicy)
+    max_limit = 5000
 
-    query_result = falcon.query_combined_policies_v2(**args)
+    falcon = authenticate(module, SensorUpdatePolicy)
 
-    result = dict(
-        changed=False,
+    result = get_paginated_results_info(
+        module,
+        args,
+        max_limit,
+        falcon.query_combined_policies_v2,
+        list_name="policies"
     )
 
-    if query_result["status_code"] == 200:
-        result.update(
-            policies=query_result["body"]["resources"],
-            pagination=query_result["body"]["meta"]["pagination"],
-        )
-
-    handle_return_errors(module, result, query_result)
-
     module.exit_json(**result)