Update Cortex Xpanse asm-list-external-websites command to include pa… (#40140) (#40707)

* Update Cortex Xpanse asm-list-external-websites command to include pagination support.

* adjust Context Outputs for Command Results to include a new object for ExternalWebsiteReply that contains contextual information about the request for external websites.

* added context path output for the NextPageToken underneath ExternalWebsitReply

* added release notes

* introduced a new CommandResults object for asm-list-external-websites since we are unable to change existing functionality of outputs_prefix of the original CommandResults. The new CommandResults object provides an additional about with context information about the request including next page token for pagination, the total results and the result count from the request.   CommandResults is also using  so that context is overwritten with the most recent command execution per recommended usage of .

* change arg gets to use double quotes

* changes requested to test file and docstring for type checking

* update release note md version to 1_2_11

* modify version in pack_metadata.json

* Apply suggestions from doc review



* Bump version

---------

Co-authored-by: zdrouse <[email protected]>
Co-authored-by: cah-zachary-rouse <[email protected]>
Co-authored-by: Sapir Malka <[email protected]>
Co-authored-by: julieschwartz18 <[email protected]>
Co-authored-by: Sapir Malka <[email protected]>

Author: 5 people

Packs/CortexXpanse/Integrations/CortexXpanse/CortexXpanse.py

@@ -1118,27 +1118,35 @@ def get_incident_command(client: Client, args: dict[str, Any]) -> CommandResults
     return command_results
 
 
-def list_external_websites_command(client: Client, args: Dict[str, Any]) -> CommandResults:
+def list_external_websites_command(client: Client, args: Dict[str, Any]) -> list[CommandResults]:
     """
-    list_external_websites command: Get external websites .
+    asm-list-external-websites command: Get external websites.
 
     Args:
         client (Client): CortexXpanse client to use.
         args (dict): all command arguments, usually passed from ``demisto.args()``.
             ``args['filter']`` Used for filter websites based on authentication type
             ``args['limit']`` Used for limit num of results
+            ``args['use_page_token']`` Boolean value used to specify pagination
+            ``args['next_page_token']`` String value of a page token to get the next page of results
 
     Returns:
-        CommandResults: A ``CommandResults`` object that is then passed to ``return_results``
+        CommandResults: A list of ``CommandResults`` objects that is then passed to ``return_results``
     """
     limit = int(args.get("limit", DEFAULT_SEARCH_LIMIT))
     searchFilter = args.get("authentication")
+    use_page_token = args.get("use_page_token")
+    next_page_token = args.get("next_page_token")
     if limit > 500:
         raise ValueError("Limit cannot be more than 500, please try again")
 
     filters = {"filters": [], "search_to": limit}
     if searchFilter:
         filters["filters"] = [{"field": "authentication", "operator": "contains", "value": searchFilter}]
+    if use_page_token:
+        filters["use_page_token"] = use_page_token
+    if next_page_token:
+        filters["next_page_token"] = next_page_token
 
     response = client.get_external_websites(filters)
 
@@ -1152,12 +1160,30 @@ def list_external_websites_command(client: Client, args: Dict[str, Any]) -> Comm
         if hosts
         else "No Results"
     )
-    command_results = CommandResults(
+
+    command_results = []
+    website_results = CommandResults(
         outputs_prefix="ASM.ExternalWebsite", outputs_key_field="", raw_response=response, readable_output=human_readable
     )
 
     if outputs := response.get("reply", {}).get("websites", None):
-        command_results.outputs = outputs
+        reply_results = CommandResults(
+            outputs_prefix="ASM.ExternalWebsiteReply", outputs_key_field="", readable_output=None, replace_existing=True
+        )
+        reply_outputs = {}
+        if response.get("reply", {}).get("next_page_token", None):
+            reply_outputs["NextPageToken"] = response.get("reply", {}).get("next_page_token")
+        if response.get("reply", {}).get("total_count", None):
+            reply_outputs["TotalCount"] = response.get("reply", {}).get("total_count")
+        if response.get("reply", {}).get("result_count", None):
+            reply_outputs["ResultCount"] = response.get("reply", {}).get("result_count")
+        if reply_outputs:
+            reply_results.outputs = reply_outputs
+            reply_results.raw_response = reply_outputs
+
+        website_results.outputs = outputs
+        command_results.append(website_results)
+        command_results.append(reply_results)
 
     return command_results
 

Packs/CortexXpanse/Integrations/CortexXpanse/CortexXpanse.yml

@@ -965,9 +965,21 @@ script:
     - name: limit
       description: Maximum number of assets to return. The maximum value is 100.
       defaultValue: "100"
+    - name: use_page_token
+      auto: PREDEFINED
+      predefined:
+      - "true"
+      - "false"
+      description: Whether to paginate the response data.  Set to true to paginate and receive a token indicating the location of the next page.
+    - name: next_page_token
+      description: A string representing the next page location when pagination is used.
     outputs:
     - contextPath: ASM.ExternalWebsite
       description: A list of the websites results assets.
+    - contextPath: ASM.ExternalWebsiteReply
+      description: Contextual information about the request including total count, result count, and next page token.
+    - contextPath: ASM.ExternalWebsiteReply.NextPageToken
+      description: The next page token for the request (for pagination).
     description: Get external websites assets.
   - name: asm-reset-last-run
     arguments: []

Packs/CortexXpanse/Integrations/CortexXpanse/CortexXpanse_test.py

@@ -600,8 +600,8 @@ def test_list_external_websites_command(requests_mock):
 
     response = list_external_websites_command(client, args)
 
-    assert response.outputs == EXTERNAL_WEBSITES_RESULTS.get("ExternalWebsite", {}).get("websites")
-    assert response.outputs_prefix == "ASM.ExternalWebsite"
+    assert response[0].outputs == EXTERNAL_WEBSITES_RESULTS.get("ExternalWebsite", {}).get("websites")
+    assert response[0].outputs_prefix == "ASM.ExternalWebsite"
 
 
 @pytest.mark.parametrize("command_name, method_name", [("asm-list-alerts", "list_alerts_command")])

Packs/CortexXpanse/ReleaseNotes/1_2_12.md

@@ -0,0 +1,8 @@
+
+#### Integrations
+
+##### Cortex Xpanse
+
+- Added support for pagination to the ***asm-list-external-websites*** command.
+- Added the *use_page_token* argument for the **asm-list-external-websites** command.
+- Added the *next_page_token* argument for the **asm-list-external-websites** command.

Packs/CortexXpanse/pack_metadata.json

@@ -2,7 +2,7 @@
     "name": "Cortex Xpanse",
     "description": "Content for working with Attack Surface Management (ASM).",
     "support": "xsoar",
-    "currentVersion": "1.2.11",
+    "currentVersion": "1.2.12",
     "author": "Cortex XSOAR",
     "url": "https://www.paloaltonetworks.com/cortex",
     "email": "",