Create an incident mapper - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Cloud Documentation

Product
Cortex XSOAR
Version
8
Creation date
2024-03-07
Last date published
2024-11-28
Category
Administrator Guide
Solution
Cloud
Abstract

Create a mapper and apply it to an integration in Cortex XSOAR.

You can create the following incident mappers:

  • Incoming mapper: Maps all fields you pull from the integration to the incident fields.

  • Outgoing mapper: Maps incident fields with fields in the integration to which you are pushing the data. This is useful for mirroring.

You can map your fields to incident types irrespective of the integration or classifier, which means that you can create mapping before defining an instance or ingesting incidents. By doing so, when you do define an instance and apply a mapper, the incidents that come in are already mapped.

When you create a mapper you can select the following incident types, which show the incident fields to map.

  • Common Mapping: Defines how fields associated to all incident types are mapped.

  • Specific mapping: Defines how fields associated with the specific incident type are mapped.

    Specific mapping overrides any mapping done in Common Mapping. When an incident is ingested, common mapping and then specific mapping are applied.

Tip

It is recommended to map all of the fields that are common to all incident types by selecting Common Mapping and then map additional fields that are specific to each incident type.

When mapping a list, we recommend you map to a multi-select field. Short text fields do not support lists. If you do need to map a list to a short text field, add a transformer in the relevant playbook task, to split the data back into a list.

You can also use Auto Map to automatically map fields, based on the same or similar names from the integration instance. For example, Severity can be mapped to Importance.

Some out-of-the-box fields are entirely controlled by Cortex XSOAR, and cannot be mapped, such as:

  • Dbot Status

  • Dbot Closed

  • Dbot Total Time

  • Close Notes

  • Feed Based

Note

Anything that you do not map will be discarded. If you want the data or you are not sure at this stage whether you want to map the data in the future, unmapped data can be placed into labels. Labels are unmapped and unsearchable data that is associated with the incident. Although you can use labels in playbooks, it is recommended that you map the required data, otherwise, all of the raw data goes into labels including both mapped and unmapped data. To turn labels on, go to vertical-elipsis.png SettingsAdvanced and deselect Do not map JSON fields into labels for selected incident type. This means

How to create a mapper
  1. Go to Settings & InfoSettingsObjects SetupIncidentsClassification & Mapping.

  2. Click New and select the mapper that you want to create.

    • Incident Mapper (Incoming)

    • Incident Mapper (Outgoing)

  3. Enter a name for the mapper, so it can be easily identified.

  4. Under Get data, select from where you want to pull the information.

    • Pull from the instance: Select an existing integration instance.

      When classifying or mapping data and using the integration instance to retrieve data, the instance must be configured and enabled. You don't need to fetch incidents.

    • Select the schema: When supported by the integration, this will pull all of the fields for the integration from the database. This enables you to see all of the fields for each given event type that the integration supports. For example, the Palo Alto Networks Cortex XDR - Investigation and Response integration supports a schema.

    • Upload JSON: Upload a formatted JSON file that includes the field you want to map.

      If the instance has nothing to fetch or the integration instance has insufficient data, upload a JSON file containing raw data.

    Note

    If creating an outgoing mapper you can only select a schema or upload a JSON file.

  5. Under Select Instance, select the integration instance from where you want to pull data.

    On the right-hand side, in the Data fetched from [name of integration instance] section, you will see the raw alert data pulled in from the integration instance. In this example, after configuring the XSOAR Engineering Training Instance (from the XSOAR Engineering Training content pack), we have pulled in the following data:

    mapping-data-fetched.png

    Note

    If creating an outgoing mapper, data from the integration schema appears on the left-hand side of the page.

  6. Select the incident type you want to map.

    By default the Incident type is set to Common mapping, which includes fields that are common to all of the incident types. This saves you time having to define these fields individually in each incident type.

    Note

    When using common mapping it shows fields that are relevant for all incident types. If you created incident fields that are specific to incident types, these fields do not appear, and you need to select the relevant type.

  7. (Outgoing mapper only) In the Incident samples section select the incident you want to map.

    If you don't have any ingested incidents, select Playground.

  8. Start mapping the fields.

    • (Optional) Automatically map fields. Click Auto Map for Cortex XSOAR to map fields with common or similar names. For example, Cortex XSOAR can map Importance to Severity or sourceIP to Source IP.

      You can Auto Map at any time. These settings do not override any manual mapping.

    • Manually map fields.

      1. Select the field you want to map and click Choose data path.

      2. On the right-hand side click the relevant key.

        In this example, you can see that we have mapped Event ID and Event Type.

        mapping-fields-events.png

        If creating an outgoing mapper, on the right-hand side, click the relevant incident field to map from.

    Note

    Some fields are automatically mapped when you start defining the mapper if Cortex XSOAR recognizes it has something similar. Although it appears as Show:Unmapped to make sure, map the item.

  9. Add any filters and transformers.

    1. Click the mapped field and then click the curly brackets.

    2. Add the filters and transformers, as required. For more information, see Transformer considerations, categories, and built-in transformers.

    3. Save the filters and transformers.

  10. Repeat this process for the other incident types for which this mapping is relevant.

    When selecting an incident type, you can copy the mapper that you created previously. This is useful if you are mapping to multiple incident types through your classifier, as you will need to perform mapping on each incident type or through common mapping.

  11. Save the mapper.

  12. Go to Settings & InfoSettingsIntegrationsInstances.

    1. Select the integration to add the mapper.

    2. In the integration settings, under Mapper, select the mapper you created and click Done.

      If you can't see the Mapper field, select Fetches Incidents.

      Note

      It is recommended that you turn off Fetches Incidents, as soon as the integration fetches incidents until you have configured a playbook to run on the incident type.

      After the integration instance starts fetching incidents go to the Incidents page to see how the classifier and mapper performed. The incident type should be populated with the correct type. You can also add relevant fields in the incident table to see if they are mapped correctly. You can also view the information including incident and labels in Context Data from (Side panels) when investigating an incident.