Work with JSON Lists - Administrator Guide - 6.9 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Product
Cortex XSOAR
Version
6.9
Creation date
2022-09-29
Last date published
2024-03-28
End_of_Life
EoL
Category
Administrator Guide
Abstract

Manage JSON lists in Cortex XSOAR that can be accessed by automations, playbooks, etc.

List data can be stored in various structures, including JSON. When you access a valid JSON file from within a playbook, it is automatically parsed as a JSON object (list). Working with JSON files in playbooks typically involves the following activities:

  • Extracting the data from a JSON object

  • Extracting a subset of the data

  • Filtering extracted data

  • Applying transformers to extracted data

See Filters and Transformers for more details.

Extract the Data from a JSON Object in a List

You can access lists from JSON objects similar to how you access incident context, including using automations or playbook tasks.

In this example, you can use the Set automation to extract the data in a list from a parsed JSON object.

  1. Create a list.

    1. Go to Settings → ADVANCED → Lists → Add a List.

    2. In the Name field, type Test1.

    3. Set the Content Type to JSON.

    4. Add the following content.

      {    
          "domain": {
              "name": "mwidomain",
              "prod_mode": "prod",
              "user": "weblogic",
              "admin": {
                  "servername": "AdminServer",
                  "listenport": "8001"
              },
              "machines": [
                  {
                      "refname": "Machine1",
                      "name": "MWINODE01"
                  },
                  {
                      "refname": "Machine2",
                      "name": "MWINODE02"
                  }
              ],
              "clusters": [
                  {
                      "refname": "Cluster1",
                      "name": "App1Cluster",
                      "machine": "Box1"
                  },
                  {
                      "refname": "Cluster1",
                      "name": "App2Cluster",
                      "machine": "Box2"
                  }
              ],
              "servers": [
                  {
                      "name": "ms1",
                      "port": 9001,
                      "machine": "Box1",
                      "clusterrefname": "Cluster1"
                  },
                  {
                      "name": "ms2",
                      "port": 9002,
                      "machine": "Box2",
                      "clusterrefname": "Cluster2"
                  },
                  {
                      "name": "ms3",
                      "port": 9003,
                      "machine": "Box1",
                      "clusterrefname": "Cluster1"
                  },
                  {
                      "name": "ms4",
                      "port": 9004,
                      "machine": "Box2",
                      "clusterrefname": "Cluster2"
                  }
              ]
          }
      }
    5. Save the list.

  2. Create a playbook task to extract the list.

    1. Select Playbooks → New Playbook → Create Task.

    2. In the Automation field, select the Set automation.

      The Set script sets a value in context under the key entered.

    3. In the key field, define a context key name for the data. For example, JSONData.

      work-with-json-lists-context-key-8-x.png
    4. In the value field, set the list you want to extract by clicking the curly brackets.

    5. Click Filters And Transformers.

    6. In the Get field, click the curly brackets, and in the Lists section, select the list you created in step 1.

      work-with-json-lists-filters-transformers-value.png
    7. Click Test.

    8. In the Fetch data field, select Playground.

    9. Click Test.

      work-with-json-lists-retrieve-list-6x.png
    10. When the test completes, click Done Testing.

    11. Save the task and playbook.

  3. Check that all the data is stored in the context key you defined by testing the playbook using the debugger.

    1. Click Run.

    2. Open the Debugger Panel.

      The key you defined (JSONData) holds all the data in context from the JSON object.

      work-with-json-lists-debugger-panel.png
Extract a Subset of the Data

In general, you can extract subsets of context data in a playbook to analyze a specific information set. This also applies to working with lists, for example extracting a subset of the data from a JSON object. In this example, we want to extract server information from the list created in Extract the Data from a JSON Object in a List.

Create a playbook task to extract a subset of the list.
  1. Select Playbooks → New Playbook → Create Task.

  2. In the Automation field, select the Set automation.

    The Set script sets a value in context under the key entered.

  3. In the key field, define a context key name for the data. For example, JSONDataSubset.

  4. In the value field, set the list you want to extract by clicking the curly brackets.

  5. Click Filters And Transformers.

  6. In the Get field, enter lists.Test1.domain.servers.

  7. Click Test.

  8. In the Fetch data field, select Playground.

  9. Click Test.

  10. When the test completes, click Done Testing.

  11. Save the task and playbook.

  12. Check that all the data is stored in the context key you defined by testing the playbook using the debugger.

    1. Click Run.

    2. Open the Debugger Panel.

      The key you defined (JSONDataSubset) holds the subset of the data in context from the JSON object.

      work-with-json-lists-subset-6x.png
Filter Extracted Data

You can filter the data subset you extracted to analyze extracted information on a more granular level. In this example, you want to filter Box1 information from the list created in Extract the Data from a JSON Object in a List.

  1. Re-open the task and click the contents of the value field.

  2. Under Filter, click + Add Filter.

  3. Set the condition you want to filter for. For example, you can retrieve the list of machines named Box1 from the servers in the Test1 list by setting the filter lists.Test1.domain.servers.machine to Equal Box1.

    work-with-json-lists-filter-data.png
  4. Click Test.

  5. In the Fetch data field, select Playground.

  6. Click Test.

  7. Check whether the list was accessed successfully by selecting the list source.

    You can see the results returned machine: Box1

    work-with-json-lists-check-filter.png
  8. You can also run the debugger and view the context data.

Apply Transformers to Extracted Data

In general, in a playbook you can transform (apply changes) to the data you extracted. This also applies for working with lists, for example to transform extracted data from a JSON object. Also, depending on how you store the data, you may need to transform a list into an array. In this example, you want you want to extract the first element in the list and transform the data to upper case from the list created in Extract the Data from a JSON Object in a List.

  1. Re-open the task and click the contents of the value field.

  2. To extract only the list of machines, in the Get type, field, type lists.test1.domain.servers.machine.

  3. Keep the filter created in Filter Extracted Data.

  4. In Apply transformers on the field, click Add transformer.

  5. Set the transformation you want to apply to the extracted data.

    1. Add the Get index (General) transformer to extract a specific machine element.

      Set index: 0 to extract the first element from the list.

    2. Add the To upper case (String) transformer.

      The To upper case (String) transformer does not work on lists, only on individual elements. Therefore, the Get index (General) transformer needs to apply first before adding the To upper case (String) transformer.

    work-with-json-lists-trans.png
  6. Click Test.

  7. In the Fetch data field, select Playground.

  8. Click Test.

  9. Check whether the data subset was accessed successfully by selecting the data source from an alert. You can see the results returned BOX1.

    work-with-json-lists-box1-6x.png
  10. When the test completes, click Done Testing.

  11. Check that all the data is stored in the context key you defined by testing the playbook using the debugger.

    1. Click Run.

    2. Open the Debugger Panel.

      The key you defined (JSONDataSubset) holds the subset of the data in context from the JSON object.