> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/tutorials/cortex-xsoar-tutorials/readme/ingest-incidents-from-a-siem-using-qradar.md). # Ingest Incidents from a SIEM Using QRadar The information in this tutorial is intended for Cortex XSOAR (SOC) engineers or architects. The goal of this tutorial is to explain how a Cortex XSOAR architect should design the platform and incident life cycle so that SOC analysts can easily identify and digest critical incident data and quickly and confidently make decisions. The tutorial walks you step-by-step through designing the incident life cycle, starting with configuring your Cortex XSOAR instance through ingesting, processing, and creating the right configuration for investigating, and closing security events. The tutorial uses QRadar as the SIEM, but the general flows are applicable to any SIEM and other data sources. By the end of this tutorial, you will have configured your integration and set up a basic flow, as well as started to ingest incidents from the SIEM to Cortex XSOAR. As you progress through configuring Cortex XSOAR, always have the analyst journey in mind. Your end goal is to make the SOC efficient, which means creating flows that require the analyst to spend the least amount of time on each incident, and ensuring they have all the tools and data to make accurate and confident decisions. By the time an analyst picks up an incident for investigation, a series of actions will already have been taken on the incident, most of which you as the architect will design. Designing flows for an analyst in Cortex XSOAR is a balance between gathering and processing as much relevant data as possible while only displaying the data and suggesting actions that analysts require for resolving incidents. Your goal should be to automate as much of the process as possible and leave the analyst to make accurate and confident decisions when needed. This tutorial includes the following topics: * [Incident Lifecycle](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_id3cfa9bd2-a72b-4b1e-94c5-0d9195bc40cb) * [Architect Flow](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_idd785f98e-3850-46d7-94e6-3545b8912188) * [Analyst Flow](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_id77058cac-6dc8-4186-a3c5-d3886570097b) * [Prerequisites](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_idcd9ae27c-2a2a-4338-89f7-3addeb7c4f37) * [Set up Your IBM QRadar Integration Instance](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_id661cac59-0d4b-444a-ba11-dc7cbd8bcbb3) * [Run a Playbook](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_id9cd8954e-f4ef-45e5-a02e-abbe1aa73d9f) * [Analyze Incident Data](#UUID-b33a2ced-0913-20a1-d306-a1cbc0e647c7_id6c4fc618-4e1b-4129-a642-855c61e3a20d) ### Incident Lifecycle Using Cortex XSOAR, you can set up integrations with your security products, security services, and any other component that make up your security operations environments. You can then ingest events from these integrations and transform them into incidents in Cortex XSOAR. After the incidents are created, you can run playbooks on these incidents to enrich them with information from other products and services, which helps optimize investigation and response. You can also use scripts to determine if an incident requires further investigation or can be closed based on the findings. This enables your analysts to focus on the minority of incidents that require further investigation. Understanding the stages of the incident lifecycle will help you design your use case, including the requirements for customizing or building your own playbook. The following is an example of an incident lifecycle flow. 1. Plan the incident process per incident type (full-automated, manual, or hybrid). Analyze the SOCs current workflows and categorize the incident types you expect to handle. 2. Define how incidents will be classified (assigned to an incident type) in Cortex XSOAR. Classification is the way to determine what incidents are going to be included in this flow. 3. Pre-processing: Apply scripts to incidents before they are ingested to eliminate false positives and duplicate incidents. This keeps a clean set of active incidents for analysts to concentrate on. 4. Run playbooks to analyze the incidents. 5. Define analyst intervention in the incident (in the playbook with communication tasks, ad-hoc tasks, and manual tasks, and also in the dashboards). 6. Display data in Cortex XSOAR for analysts to view. This involves how the incident data is going to be presented (mapping), and how the incident details are presented to the analyst in layouts and dashboards. 7. Remediate the investigation, including [post-processing](https://app.gitbook.com/s/OHlpKeFtqCLUYKuYyccd/customize-and-configure-cortex-xsoar/incidents/post-processing-for-incidents) and closing incidents. These are actions to take when the incident is over (for example, close incident and force or encourage the analyst to specify a close reason). ### Architect Flow To explain the architect flow we will use QRadar to define and design the incident life cycle for the analyst. The process is similar for any security event source (e.g., Splunk). **Define the Incident Type** The first step in planning your incident identification and response posture is to create a basic outline of the flows that your SOC will handle. Start by listing the main steps of an incident starting with the first alert all the way through to the response and closure. Most SOCs handle several types of incidents generated from the SIEM that originate from SIEM alerts. For example: * Authentication incident from an alert for a high number of unsuccessful login attempts by a user * Malware incident from an alert for a suspicious file triggering endpoint security alerts * Impossible travel/access incident from an alert on a user accessing data from different locations at the same time Each of these incident types require you to create targeted workflows and automated responses that generate accurate data sets from which you can design incident-type specific layouts to enable analysts to quickly digest event information. The incident type determines how the incident progresses through the investigation and response phase in the incident lifecycle and is presented in Cortex XSOAR: * **Playbook**: which playbook will run for this incident type. * **Automation level**: Is it possible to automate the entire process, in which case an analyst will never interact with the incident. You can also automate the majority of the incident response but require an analyst to review it before taking a final decision. All of this is determined by the playbook. * **Default playbook**: It is recommended to create a default playbook for all incident types that do not have a specific playbook associated with them (in time you will add more playbooks and the default playbook will be triggered less). * **Incident/Indicator fields**: The incident and indicator fields vary depending on the incident type. For example, a file hash field will be relevant for Malware incidents but not for an access incident. Cortex XSOAR includes several pre-built playbooks and incident types. Each incident type has out-of-the-box fields that comprise the incident and indicator layouts. You can customize these to add required fields and remove fields that are not necessary. When selecting fields to include in a layout, it’s important to remember that the analyst will need to view, digest, and act upon the information you present. It’s a good practice to include everything that will accomplish this goal, but not more than is required. * **Analyst incident assignment**: If analyst intervention is required, you can also decide which analyst is assigned (for example, do you want your analysts to pick up the first incident they see, or do you want to auto-assign to the most appropriate analyst that XSOAR suggests). **Plan the Workflow for Each Incident Type** The following workflow takes place before the analyst is assigned. * Assign incoming events to Cortex XSOAR incidents In Cortex XSOAR, incident classification is the process by which an incoming security event/alert is assigned to a Cortex XSOAR incident type. When you fetch security events from a third-party service, in our example, QRadar, the event data is ingested in JSON format. You classify the security event based on the fields (keys) from the event JSON. In QRadar, the **`categories`** key contains the offense (event) type in QRadar. The values from this key can be used to classify the incidents in Cortex XSOAR, although you can use any field (key). Most integrations that fetch security incidents include out-of-the-box (default) event classification for the most common security events. The default classifier for QRadar assigns the following values for the **`categories`** key as Access incidents in Cortex XSOAR. * SIEM User Authentication * User Login Failure In addition to these default classifiers, we can add additional categories (security events) to an incident type in Cortex XSOAR. For more detailed information, learn about [Classification and Mapping](https://app.gitbook.com/s/OHlpKeFtqCLUYKuYyccd/customize-and-configure-cortex-xsoar/incidents/classification-and-mapping). ![tutorial-siem-incident-classifier.png](/files/6u2aGB0NUuTeyVoRtQo8) * Pre-process incoming incidents In many cases, you want to eliminate false-positives and deduplicate incidents. This enables you to maintain a clean set of incidents for analysts to work on. Pre-processing rules enable you to perform certain actions on security events before they are ingested as incidents in Cortex XSOAR. You perform actions when the condition of a rule is met, for example, link the incoming incident to an existing incident, or under configured conditions, drop the incoming incident altogether. In addition, you can run a script on the incident when the condition(s) are met. * Run a playbook on the incident After the security event is ingested, classified to an Cortex XSOAR incident type, and filtered through the pre-processing rules, the default playbook for the incident type is run on the incident. In most cases, the default playbook does one or more of the following: * Extracts and enriches indicators * Determines the incident severity * Assigns the incident to an analyst for manual review Depending on how you design the workflow for the incident type, when the playbook completes its run the incident data is presented for the first time to analysts in the layouts and dashboards. ### Analyst Flow Depending on how you design the incident life cycle, many actions are performed automatically before the analyst even sees an incident. For example, incidents may be closed as duplicates or false-positives, data is enriched, and more. For most incidents, the analyst will: 1. Pick up an open incident. 2. View enough data to be able to make decisions including what steps have already been taken (Incident Summary, Work Plan). 3. Easily collect additional data by running commands on third-party tools. 4. Collaborate with SOC team members in the War Room; ask questions, post comments, and more. 5. Make an informed decision on how to handle the incident. A typical flow is to design the incident page to include a set of buttons that the analyst can select from (Escalate, Close, etc.) 6. Activate one of several possible responses either within Cortex XSOAR or externally (e.g., open a ticket for IT). 7. Close the incident and specify a close reason. ### Prerequisites This tutorial assumes that you already have the following components installed and configured in your Cortex XSOAR instance. It’s important to have this done because the workflows in this guide require their functionality at some point. For example, a playbook task might send an email notification to users, so if you don’t have an outgoing email integration configured you won’t be able to complete the playbook workflow. 1. Install the Cortex XSOAR server and verify that it’s up and running. 2. Configure an incoming email integration. For example, [Gmail](https://xsoar.pan.dev/docs/reference/integrations/gmail) or [Microsoft Graph Mail](https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-mail). 3. Configure an outgoing email integration. For example, [Mail Sender](https://xsoar.pan.dev/docs/reference/integrations/mail-sender-new). 4. Provision Cortex XSOAR users. For example, [Active Directory](https://xsoar.pan.dev/docs/reference/integrations/active-directory-query-v2) or [Okta](https://xsoar.pan.dev/docs/reference/integrations/okta-v2). 5. Make sure you have your IBM QRadar credentials. ### Set up Your IBM QRadar Integration Instance One of the most common use cases in Cortex XSOAR is integrating with a SIEM, such as QRadar or Splunk, to ingest events as Cortex XSOAR incidents. 1. Install the IBM QRadar pack. 1. Go to the Cortex XSOAR Marketplace. 2. Search for IBM QRadar v3. 3. Click the pack and click **Install**. 4. Click **Install** again to confirm the installation. 2. Configure the IBM QRadar instance. Before you configure the instance: * Make sure you have your IBM QRadar API key or authentication details. * Define your email sender integration and the SIEM admin email address. 1. Go to Settings → **Instances**. 2. Search for IBM QRadar v3. 3. Click **Add Instance**. 4. Under **Classifier**, select **N/A**. 5. Under **Incident Type**, select **QRadar Generic** At this point, we are using the generic QRadar incident type. As you become more familiar with Cortex XSOAR, you can create custom incident types as needed. 6. Under **Mapper Incoming**, select **QRadar - Generic Incoming Mapper**. ![tutorial-siem-mapper.png](/files/Ux8cxHhUv3SkfugG2B6s) 7. Enter the URL of your QRadar server, as well as the username and password (or credentials) and the QRadar API version. 8. Select the **Fetch mode**. This parameter defines whether to fetch offenses with events. Options are **`Fetch With All Events`** (default), **`Fetch Without Events`**, or **`Fetch Correlation Events Only`**. 9. Under the **Maximum number of events per incident** parameter, enter the number of events for this offense that you want to ingest. Out of the box, Cortex XSOAR ingests 20 events. When investigating incidents, you will see the total number of events per incident is much larger. However, ingesting all the events for each offense would slow down system performance. 10. Set the **Number of offenses to pull per API call (max 50)**. For mirroring with events, this value is used for mirroring API calls as well, so we recommend using a small value. Default is 20. ![tutorial-siem-qradar-config.png](/files/9FHa7d2WGWY48hr03j3o) 11. In the **Query to fetch offenses** parameter, define which offenses to fetch. Before defining your query to fetch incidents, we recommend that you check your QRadar offenses and fetch the most recent 5 offenses using the ID field. For example, **`id=483`** where 483 is the fifth most recent ID number in the QRadar offenses. For example, "severity >= 4 AND id > 5 AND status=OPEN" 12. Select the **Incidents Enrichment**. This enrichment provides additional information about IP addresses and assets that are related to the offenses you’re ingesting. Options are **`IPs And Assets`** (default), **`IPs`**, or **`None`**. 13. Add or remove fields from **Event fields to return from the events query**. This parameter lists all of the IBM QRadar fields for this offense that Cortex XSOAR ingests out-of-the-box (uses AQL SELECT syntax).

Caution

This parameter is correlated to the incoming mapper and changing the values may adversely affect mapping.

14. (Optional) Configure mirroring (for QRadar 7.3.3 Fix Pack 3 and up). 1. Select one of the **Mirroring Options**. This parameter defines how mirroring from QRadar to Cortex XSOAR should be done. Options are **`No Mirroring`** (default), **`Mirror Offense`**, or **`Mirror Offense and Events`**. 2. Select the **Close Mirrored XSOAR Incident** checkbox to close the Cortex XSOAR incident if the related offense is closed in QRadar. 3. Set **The number of incoming incidents to mirror each time** (default is 100). ![tutorial-siem-max-events.png](/files/fZUPCdQ2Ybei13SuMYUB) 15. Set any **Advanced Parameters**. This parameter is a comma-separated list of advanced parameter values. For example, EVENTS\_INTERVAL\_SECS=20,FETCH\_SLEEP=5 16. Select the **Long running instance** checkbox. This ensures the connection with the QRadar server is always kept open so you have the most up-to-date information. 3. Go to the **Incidents** page and verify that incidents are being ingested. ### Run a Playbook After you define the pack and start ingesting incidents, the default playbook assigned to the QRadar incident type automatically processes the incoming incidents. No additional steps are required from the analyst to initiate the playbook run/incident-handling process. By default, the QRadar integration uses the **QRadar Generic** playbook, which is executed for the QRadar Generic incident type. It performs all the common parts of the investigation, including: * Extracting and enriching indicator data from incidents * Calculating severity * Excluding irrelevant (duplicate) indicators * Assigning analysts to incidents for manual review * Tagging malicious indicators * Notifying the SIEM admin about false positives and adjusting indicators and rules * Generating a report with the playbook findings and notifying the SOC **Playbook Inputs** Every playbook has inputs that help determine how the playbook will flow. The inputs (and outputs) are configured at the very beginning of the playbook, under **Playbook Triggered**. For a full description of each of the inputs for this playbook, refer to the [playbook documentation](https://xsoar.pan.dev/docs/reference/playbooks/q-radar-generic). However, for purposes of this tutorial, we will focus on the following inputs: * **Enrich** - This input determines whether you want the playbook to enrich all of the indicators in the incident. By default, it’s set to true. However, enrichment can be a very resource intensive operation, so you might want to change this setting to false and enrich only specific indicators and only use certain integrations. Also, if you do want to enrich indicators, you should enable at least one of the out-of-the-box enrichment integrations, such as VirusTotal. * **UseCustomSeveritySettings** - Determines whether to use the severity mapping provided in the mapper. By default, this input is set to true, meaning that QRadar events are mapped as follows: 1,1,1,2,2,2,2,3,3,3 Magnitude 1-3 in QRadar is given a Low severity in Cortex XSOAR. Magnitude 4-7 in QRadar is given a Medium severity in Cortex XSOAR. Magnitude 8-10 in QRadar is given a High severity in Cortex XSOAR. * **RunAdditionalSearch** - Determines whether to fetch more QRadar logs associated with an offense, in addition to the default 20 logs provided by the integration. To fetch more than the default number, set this input to true and in the QRadar - Get Offense Logs subplaybook, define how many and what kind of logs to fetch. * **UseCalculateSeverity** - Determines whether to set the severity of the incident based on the Calculate Severity playbook (default, true), or to set the severity based on a different attribute. If you set this to false, configure the field by which you want to determine severity in the **`FieldToSetSeverityFrom`** input, (by default, it is incident magnitude), as well as configure how magnitude values are translated in Cortex XSOAR using the ScaleToSetSeverityFrom input. * **FieldToSetSeverityFrom** - As mentioned above, if you do not calculate the severity based on the Calculate Severity playbook, you must determine the severity by one of the fields from the QRadar incident. QRadar has several fields that can be used to determine severity, and this can be configured in Cortex XSOAR by changing the value in the **`Get`** field for this input. As you can see in the screenshot below, it is set by default to Magnitude. However, you can change it to Severity, Credibility, or any other value from the incident. ![tutorial-siem-field-severity.png](/files/5E7xcuJlkkUzuTxAEn0K) * **ScaleToSetSeverityFrom** - QRadar uses a scale of 1-10 to determine the severity of an incident. However, Cortex XSOAR uses 5 values in a scale from 0-4: * Informational * Low * Medium * High * Critical By default, the QRadar values are mapped to Cortex XSOAR values in the QRadar Generic mapping provided out-of-the-box. These values are mapped as follows: 1,1,1,2,2,2,2,3,3,3 Magnitude 1-3 in QRadar is given a Low severity in Cortex XSOAR. Magnitude 4-7 in QRadar is given a Medium severity in Cortex XSOAR. Magnitude 8-10 in QRadar is given a High severity in Cortex XSOAR. To change this mapping, you must enter a value from 0-4 that corresponds to the slot representing the value from QRadar. The following is an example of an alternate mapping: * 1-2 - Informational * 3-4 - Low * 5-6 - Medium * 7-8 - High * 9-10 - Critical **Enrich Indicators** If you select in the playbook input to enrich all of the indicators from the incident, the playbook extracts the indicators and uses whichever integrations you enabled for enrichment. Enriched indicators provide the analyst with more information about each indicator. The Entity Enrichment playbook checks for information about all kinds of indicators, including malicious URLs, domains, or IP addresses. It can also check against a list of VIP assets in your organization that might have been targeted, or detonate a file that was attached to the incident. While these capabilities are available in the playbook, they are only available if you have enabled or installed integrations for these checks. For information about enabling additional integrations, refer to the [integration documentation](https://xsoar.pan.dev/docs/reference/index). If you also configured the playbook to use the Calculate Severity playbook, the playbook takes the information from the enriched indicators and provides a severity based on the DBot score. **Manual Investigation** After the playbook gathers all of the necessary information, an SLA timer is triggered and the incident is assigned to an analyst for manual investigation. This includes optimizing the analysis by eliminating indicators and false positives. **Exclude Indicators** The analyst can optionally email the SIEM admin to select indicators from the list generated by the offense and QRadar logs to add to the Cortex XSOAR exclude list. The excluded indicators won't be created in Cortex XSOAR anymore, reducing the number of indicators the analyst needs to investigate and improving performance. **True/False Positive** The analyst also needs to determine if an incident is a true positive or false positive. If the incident is a true positive, the analyst can tag malicious indicators to fine-tune the system for future cases, and then generate an incident report and take the necessary remediation steps. If the incident is a false positive, the analyst can email the SIEM admin a list of indicators to exclude at the QRadar integration level and rules to label in order to fine-tune the system for future cases. ![tutorial-siem-which-rules.png](/files/UjKiC2UYl6kprVORQ4KY) The feedback from the analyst is sent to the SIEM admin so they can review the suggested changes and make any necessary adjustments. ### Analyze Incident Data After events are fetched and the playbook executes, the events appear as incidents in the Incidents page. All of the information that is displayed in the respective tabs is determined by the layout you designed for the QRadar Generic incident type. The layout appearance, including which tabs, their order, names, and more is [customizable](https://app.gitbook.com/s/IWHPB8LtGrWulD6OXGWq/incidents/incident-customization/customize-incident-layouts). The analyst can click on the ID of any incident to view additional incident data that you configured for the incident type. **Incident Info View** The Incident Info tab provides information about the incident itself. For example, when was the incident opened and updated, what’s the severity of the incident and from where did it originate. It gives you easy access to all of the indicators extracted from the incident, what is the current state of the incident, and more. ![tutorial-siem-incident-info.png](/files/fLtLEhs7dgzKDTCMd5LT) For example, in the screenshot above, we see, in the Work Plan section of the page, that the incident is currently on hold waiting for the manual investigation to complete. **QRadar Offense View** The QRadar Offense tab bring the information that is available in QRadar and provides it to you in one screen within Cortex XSOAR. So, for example, you can see how many of the events associated with the offense were pulled (by default, it’s 20) and the magnitude that was assigned in QRadar. ![tutorial-siem-offense-summary.png](/files/C5X9wHiyip8IyEI3xbdN) The view includes all of the network data that is available from QRadar, as well as a link to the incident in QRadar itself. **QRadar Events View** The QRadar Events tab presents a table with the events that were pulled when the offense was ingested. By default, to improve performance, only the last 20 events are pulled, but you can override this in the **Maximum number of events per incident** field in the integration settings. **QRadar Assets** The QRadar Assets tab presents information about any critical assets that were involved in the offense, whether they were targeted or tangentially related. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/tutorials/cortex-xsoar-tutorials/readme/ingest-incidents-from-a-siem-using-qradar.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.