Classification and Mapping
The classification and mapping feature enables you to take the events and event information that Cortex XSOAR ingests from integrations or REST API, and classify the event as a type of Cortex XSOAR incident. For example, Cortex might generate alerts from Traps which you would classify according to the information in those either as dedicated Traps incident types or maybe Authentication or Malware. You might have EWS configured to ingest both phishing and malware alerts which you would want to classify to their respective incident types based on some information in the event. By classifying the events differently, you have more control of the incident type and allowing you to run multiple playbooks for the events coming from one source.
Once you classify the incident, you can map the fields from the 3rd party integration to the fields that you defined in the incident layout. Any fields that you do not map, are automatically mapped to Cortex XSOAR labels. While this information can still be accessed, it is always easier to work with fields.
To get the most benefit out of classification and mapping, make sure that you understand which information will be ingested from the events so you can set up the fields and incident types accordingly.
Classification#
Classification determines the type of incident that is created for events ingested from a specific integration.
You can classify events in one of two ways:
- When defining an integration - Select the incident type that is created. When this is configured, it becomes the default incident type. If you do not classify the event through classification and mapping, it will be set as what you have defined here. For information about defining the incident type within the integration settings, see Integration Configuration.
- By setting a classification key - Use the classification engine to determine the incident type. This overrides whatever you configured in the integration settings.
Classify using a classification key#
When an integration fetches incidents, it populates the rawJSON object in the incident object. The rawJSON object contains all of the attributes for the event. For example, source, when the event was created, the priority that was designated by the integration, and more. When classifying the event, you will want to select an attribute that can determine what the event type is.
- Open the Classification & Mapping window for the Integrations instance:
- In Settings -> Integrations -> Servers & Services click Mapping next to the integration instance.
- In Settings -> Integrations -> Classifications & Mapping select the integration instance from the drop-down menu.
Click Set up a classification rule to open the Classification wizard.
Load event data using one of the following options:
- Pull from integrationName - Cortex XSOAR fetches events from the instance (alerts, notifications etc.)
- Upload JSON file - Upload a file containing the rawJSON object from the integration. The file must be uploaded in JSON format.
- Skip getting samples - Map the attributes without event data. This is not recommended.
- External schema support - Enable the get-mapping-fields command that pulls the remote schema for the different incident types, and their associated incident fields, from the remote system.
Set the classification key.
The event attributes are presented on the right side of the screen. Click on the attribute by which you want to classify the incidents. You can navigate between the fetched events to view all of the attributes in the other events and to ensure that you are selecting a viable attribute. In our example, below, we are classifying by the description attribute.
You can use filters and transformers to make the selection more exact.
Click Done.
Once you select the attribute, the unique values for the attribute that you have selected from the fetched events appear under the Unmapped Values section on the left side of the screen.
Drag an unmapped value to the Values to Identify column for the incident type to which you want to classify. Any unmapped values that you do not classify, an incident type as defined in the integration will be created.
Note: You can map multiple values to an incident type, but you cannot map an unmapped value to multiple incident types.
Map event attributes to fields#
You should map event attributes to the incident fields so the information is indexed. By default, attributes are not mapped to any fields. They are only available in the incident.labels of the incident.
Click Edit Mapping in the incident type.
In the Mapping Wizard, in the left pane click Choose data path.
Click the event attribute to which you want to map. You can further manipulate the field using filters and transformers.
Click Done.
Classifier & Mapper files structure#
Classifier and mapper files structure differs before and after Cortex XSOAR version 6.0.
Up to Cortex XSOAR version 6.0#
The classifier & mapper should be represented in one file, as exported from Cortex XSOAR, with addition of the field toVersion: 5.9.9.
The file should be named classifier-<PACK-NAME>_5_9_9.json, e.g. classifier-CortexXDR_5_9_9.json
Cortex XSOAR version 6.0 and above#
Cortex XSOAR version 6.0 introduces an improved classification & mapping experience, which includes a mirroring functionality by allowing to map outgoing incidents.
note
You can set default classifier and/or mapper for an integration by populating the following keys in the integration YAML file with the classifier and/or mapper IDs:
- For default classifier:
defaultclassifier - For default incoming mapper:
defaultmapperin - For default outgoing mapper:
defaultmapperout
Classifier file:
Filename:
classifier-<PACK-NAME>.json, e.g.classifier-CortexXDR.jsonFile contents:
For example:
Incoming mapper file:
Filename:
classifier-mapper-incoming-<PACK-NAME>.json, e.g.classifier-mapper-incoming--CortexXDR.jsonFile contents:
For example:
For more information about incident classification and mapping, see the Cortex XSOAR Administrator's Guide.