QRadar SIEM

Table of Contents

Release Notes

Version

Publication

Notes

2.5.0

June. 2025

  • Update functions to return status=False and reason when fail.
  • Update search function to handle subqueries.
  • Add bulk_load for reference sets.
  • Updated funct_qradar_reference_table_get_table to use filters range limits and fields

2.4.1

May. 2024

Bug fix for function input field name qradar_note. Change it to qradar_siem_note.

2.4.0

April. 2024

Added functions to create offense notes and make changes to an offense.

2.3.1

April. 2024

Bug fix for search_ref_set function

2.3.0

September. 2023

Python3 / Playbook Conversion

2.2.6

June. 2023

Fix bug in qradar_search function

2.2.5

July. 2022

Bug Fix for windows clients

2.2.4

July. 2022

Update SOAR required version

2.2.3

June. 2022

Bug fix for using with MSSP

2.2.2

May. 2022

Add more documentation and bug fix

2.2.1

March 2022

Cancel QRadar queries which have timed out

2.2.0

March 2022

Allow multiple QRadar instances

2.1.1

July 2021

Fixed selftest failing when using cafile

2.1.0

Feb. 2021

Additional functions for reference table mapping.

2.0.9

Feb. 2021

Bug fixes associated with require input field validation.

2.0.8

Nov. 2020

Fixed a bug failing search function when used with token.

2.0.7

July 2020

Correct typos and describe optional Search activity field Update SOAR version.

2.0.6

May 2020

Add option to return all results from Search.

2.0.4

April 2020

Additional configuration notes.

2.0

March 2019

Supports the 2.0 release.

1.0

July 2018

Initial publication.

Overview

IBM QRadar SOAR Components for ‘fn_qradar_integration’

screenshot: main

fn_qradar_integration supports performing ariel search to retrieve data from QRadar. It also provide functions to find/add/delete reference set items.

Key Features

This guide describes the QRadar Function integrations.. The QRadar app with the SOAR platform package provides the following:

  • Search function to perform a QRadar Ariel query

  • Search function to query an item in a QRadar reference set

  • Search function to find all the reference sets that contain an item

  • Add function to insert a new item in a QRadar reference set

  • Delete function to remove an item from a QRadar reference set

  • List all reference tables

  • View all items associated with a given reference table

  • Add/Update/Delete items to a QRadar reference table

  • Update an offense, such as changing status to closed

  • Writing notes to an offense

With the above functions, this package includes example workflows that demonstrate how to call the functions, rules that start the example workflows, and custom data tables updated by the example workflows.

Requirements

This app supports the IBM Security QRadar SOAR Platform and the IBM Security QRadar SOAR for IBM Cloud Pak for Security.

SOAR platform

The SOAR platform supports two app deployment mechanisms, Edge Gateway (also known as App Host) and integration server.

If deploying to a SOAR platform with an App Host, the requirements are:

  • SOAR platform >= 51.0.0.0.9339.

  • The app is in a container-based format (available from the AppExchange as a zip file).

If deploying to a SOAR platform with an integration server, the requirements are:

  • SOAR platform >= 51.0.0.0.9339.

  • The app is in the older integration format (available from the AppExchange as a zip file which contains a tar.gz file).

  • Integration server is running resilient_circuits>=50.0.0.

  • If using an API key account, make sure the account provides the following minimum permissions:

    Name

    Permissions

    Org Data

    Read, edit

    Function

    Read

The following SOAR platform guides provide additional information:

  • Edge Gateway Deployment Guide or App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.

  • Integration Server Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.

  • System Administrator Guide: provides the procedure to install, configure and deploy apps.

The above guides are available on the IBM Documentation website at ibm.biz/soar-docs. On this web page, select your SOAR platform version. On the follow-on page, you can find the Edge Gateway Deployment Guide, App Host Deployment Guide, or Integration Server Guide by expanding Apps in the Table of Contents pane. The System Administrator Guide is available by expanding System Administrator.

Cloud Pak for Security

If you are deploying to IBM Cloud Pak for Security, the requirements are:

  • IBM Cloud Pak for Security >= 1.10.15.

  • Cloud Pak is configured with an Edge Gateway.

  • The app is in a container-based format (available from the AppExchange as a zip file).

The following Cloud Pak guides provide additional information:

  • Edge Gateway Deployment Guide or App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings. From the Table of Contents, select Case Management and Orchestration & Automation > Orchestration and Automation Apps.

  • System Administrator Guide: provides information to install, configure, and deploy apps. From the IBM Cloud Pak for Security IBM Documentation table of contents, select Case Management and Orchestration & Automation > System administrator.

These guides are available on the IBM Documentation website at ibm.biz/cp4s-docs. From this web page, select your IBM Cloud Pak for Security version. From the version-specific IBM Documentation page, select Case Management and Orchestration & Automation.

Proxy Server

The app does support a proxy server.

Python Environment

Python 3.9, 3.11, and 3.12 are officially supported. When deployed as an app, the app runs on Python 3.11. Additional package dependencies may exist for each of these packages:

  • resilient_circuits>=51.0.0

Installation

Install

  • To install or uninstall an App or Integration on the SOAR platform, see the documentation at ibm.biz/soar-docs.

  • To install or uninstall an App on IBM Cloud Pak for Security, see the documentation at ibm.biz/cp4s-docs and follow the instructions above to navigate to Orchestration and Automation.

App Configuration

The following table provides the settings you need to configure the app. These settings are made in the app.config file. See the documentation discussed in the Requirements section for the procedure.

Config

Required

Example

Description

host

Yes

localhost

*QRadar host name or IP Address *

qradarpassword

No

changeme

username password for QRadar authentication

qradartoken

No

changeme

QRadar token to use rather than password

username

Yes

admin

Username for QRadar authentication

verify_cert

No

`false

/path/to/cert`

search_timeout

No

60

Seconds to timeout after search begins

2.3.0 Changes

In v2.3.0, the existing rules and workflows have been replaced with playbooks. This change is made to support the ongoing, newer capabilities of playbooks. Each playbook has the same functionality as the previous, corresponding rule/workflow.

If upgrading from a previous release, you’ll notice that the previous release’s rules/workflows remain in place. Both sets of rules and playbooks are active. For manual actions, playbooks have the same name as it’s corresponding rule, but with “(PB)” added at the end.

You can continue to use the rules/workflows. But migrating to playbooks provides greater functionality along with future app enhancements and bug fixes.

2.2.0 Changes

Starting in version 2.2.0, more than one QRadar instance can be configured for SOAR case data synchronization. For enterprises with only one QRadar instance, your app.config file will continue to define the QRadar instance under the [fn_qradar_integration] section header.

For enterprises with more than one QRadar instance, each instance will have it’s own section header, such as [fn_qradar_integration:qradar_instance_label] where qradar_instance_label represents any label helpful to define you QRadar environment.

Be aware that modifications to the workflows will be needed to correctly pass this label through the qradar_label function input field if the QRadar server/servers in the app.config have labels.

If you have existing custom workflows, see Creating workflows when server/servers in app.config are labeled for more information about changing them to reference the qradar_label function input field.

Function - QRadar SIEM: Add Reference Set Item

Add an item to a given QRadar reference set

screenshot: fn-qradar-siem-add-reference-set-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_set_item_value

text

No

-

Value of a QRadar reference set item

qradar_reference_set_name

text

No

-

Name of a QRadar reference set

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "collection_id": 11,
    "creation_time": 1440703724417,
    "element_type": "IP",
    "name": "DHCP Servers",
    "namespace": "SHARED",
    "number_of_elements": 2,
    "timeout_type": "FIRST_SEEN"
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_set_item_value": "9.9.9.9",
    "qradar_reference_set_name": "DHCP Servers"
  },
  "status_code": 200
}

Example Function Input Script: 

inputs.qradar_reference_set_item_value = artifact.value
inputs.qradar_reference_set_name = getattr(playbook.inputs, "qradar_reference_set_to_move_to")
inputs.qradar_label = getattr(playbook.inputs, "qradar_server")

Example Function Post Process Script: 

results = playbook.functions.results.qradar_add_reference_set_item_result

if results.get("status_code") == 200:
  incident.addNote(u"Successfully added {} to {} on QRadar Server: {}".format(artifact.value, playbook.inputs.qradar_reference_set_name, results.get("inputs", {}).get("qradar_label")))
else:
  incident.addNote(u"Failed to add {} to {} on QRadar server: {}. Status code: {}, message: {}".format(artifact.value, playbook.inputs.qradar_reference_set_name, results.get("inputs", {}).get("qradar_label"), results.get("status_code"), results.get
  ("message")))

Function - QRadar SIEM: Bulk Add Reference Set Items

Add or update data in a reference set.

screenshot: fn-qradar-siem-bulk-add-reference-set-items

Inputs:

Name

Type

Required

Example

Tooltip

qradar_domain_id

text

No

SHARED

Specify the numeric domain_id tag for the data or SHARED for Admin users. Must be a domain ID for which the caller has access.

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_namespace

select

Yes

-

-

qradar_reference_set_name

text

No

-

Name of a QRadar reference set

qradar_reference_set_values

text

Yes

string, string, string

A comma seperated list of values to add to the reference set.

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "collection_id": 44,
    "creation_time": 1712668910618,
    "element_type": "ALN",
    "name": "test",
    "namespace": "SHARED",
    "number_of_elements": 12,
    "timeout_type": "FIRST_SEEN"
  },
  "inputs": {
    "qradar_domain_id": "SHARED",
    "qradar_namespace": "SHARED",
    "qradar_reference_set_name": "test",
    "qradar_reference_set_values": "thing3, thing6"
  },
  "metrics": {
    "execution_time_ms": 31368,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.5.0",
    "timestamp": "2025-04-25 11:00:01",
    "version": "1.0"
  },
  "raw": null,
  "reason": null,
  "success": true,
  "version": 2.0
}

Example Function Input Script: 

if getattr(playbook.inputs, "qradar_siem_namespace", None):
  inputs.qradar_namespace = getattr(playbook.inputs, "qradar_siem_namespace", None)
if getattr(playbook.inputs, "qradar_siem_reference_set_values", None):
  inputs.qradar_reference_set_values = getattr(playbook.inputs, "qradar_siem_reference_set_values", None)
if getattr(playbook.inputs, "qradar_server", None):
  inputs.qradar_label = getattr(playbook.inputs, "qradar_server", None)
if getattr(playbook.inputs, "qradar_siem_reference_set_name", None):
  inputs.qradar_reference_set_name = getattr(playbook.inputs, "qradar_siem_reference_set_name", None)
if getattr(playbook.inputs, "qradar_siem_domain_id", None):
  inputs.qradar_domain_id = getattr(playbook.inputs, "qradar_siem_domain_id", None)

Example Function Post Process Script: 

results = playbook.functions.results.qradar_siem_bulk_add_ref_set_items_results
if results.get("success", None):
  if results.get('content', {}).get('http_response', {}):
    incident.addNote(f"QRadar SIEM: Bulk Add Reference Set Items returned:\n{results.get('content', {}).get('http_response', {})}")
  else:
    incident.addNote(f"QRadar SIEM: Bulk Add Reference Set Items\nItems: {playbook.inputs.qradar_siem_reference_set_values} added to reference set: {playbook.inputs.qradar_siem_reference_set_name} on QRadar server: {playbook.inputs.qradar_server}")
else:
  incident.addNote(f"QRadar SIEM: Bulk Add Reference Set Items failed with reason:\n{results.get('reason', None)}")

Function - QRadar SIEM: Create Offense Note

Add a note to the QRadar offense.

screenshot: fn-qradar-siem-create-offense-note

Inputs:

Name

Type

Required

Example

Tooltip

qradar_id

number

Yes

-

-

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_siem_note

text

Yes

-

-

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "create_time": 1713464714559,
    "id": 214,
    "note_text": "test from soar\\x03",
    "username": "API_token: ms qradar integration"
  },
  "inputs": {
    "qradar_id": 164,
    "qradar_label": "9.46.246.248",
    "qradar_siem_note": "test from soar"
  },
  "metrics": {
    "execution_time_ms": 463,
    "host": "localhost",
    "package": "fn-qradar-integration",
    "package_version": "2.4.0",
    "timestamp": "2024-04-18 14:25:14",
    "version": "1.0"
  },
  "raw": null,
  "reason": null,
  "success": true,
  "version": 2
}

Example Function Input Script: 

inputs.qradar_id = playbook.inputs.qradar_id
inputs.qradar_siem_note = playbook.inputs.qradar_siem_note
inputs.qradar_label = playbook.inputs.qradar_label

Example Function Post Process Script: 

results = playbook.functions.results.create_note_results
if results.success:
  incident.addNote(f"QRadar note created for offense {playbook.inputs.qradar_id}: '{playbook.inputs.qradar_siem_note}'")
else:
  incident.addNote(f"QRadar note failed for offense: {playbook.inputs.qradar_id} Reason: {results.reason}")

Function - QRadar SIEM: Delete Reference Set Item

Delete an item from a given QRadar reference set

screenshot: fn-qradar-siem-delete-reference-set-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_set_item_value

text

No

-

Value of a QRadar reference set item

qradar_reference_set_name

text

No

-

Name of a QRadar reference set

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "content": {
      "collection_id": 12,
      "creation_time": 1440703735265,
      "element_type": "IP",
      "name": "DNS Servers",
      "namespace": "SHARED",
      "number_of_elements": 1,
      "timeout_type": "FIRST_SEEN"
    },
    "status_code": 200
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_set_item_value": "9.9.9.9",
    "qradar_reference_set_name": "DNS Servers"
  },
  "metrics": {
    "execution_time_ms": 1306,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-14 21:08:54",
    "version": "1.0"
  },
  "raw": "{\"status_code\": 200, \"content\": {\"timeout_type\": \"FIRST_SEEN\", \"number_of_elements\": 1, \"creation_time\": 1440703735265, \"name\": \"DNS Servers\", \"namespace\": \"SHARED\", \"element_type\": \"IP\", \"collection_id\": 12}}",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_reference_set_item_value = artifact.value
inputs.qradar_reference_set_name = getattr(playbook.inputs, "qradar_reference_set_name")
inputs.qradar_label = getattr(playbook.inputs, "qradar_server")

Example Function Post Process Script: 

None

Function - QRadar SIEM: Find Reference Set Item

Find an item in a given QRadar reference set

screenshot: fn-qradar-siem-find-reference-set-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_set_item_value

text

No

-

Value of a QRadar reference set item

qradar_reference_set_name

text

No

-

Name of a QRadar reference set

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "collection_id": 35,
    "creation_time": 1557250160405,
    "data": [
      {
        "domain_id": null,
        "first_seen": 1694498079793,
        "last_seen": 1694498079793,
        "source": "EC: Sysmon - Detected a Possible Credential Dumping Tool",
        "value": "192.168.107.107"
      }
    ],
    "element_type": "IP",
    "name": "EC Compromised Hosts",
    "namespace": "SHARED",
    "number_of_elements": 1,
    "timeout_type": "FIRST_SEEN"
  },
  "found": "True",
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_set_item_value": "192.168.107.107",
    "qradar_reference_set_name": "EC Compromised Hosts"
  },
  "status_code": 200
}

Example Function Input Script: 

inputs.qradar_reference_set_item_value = artifact.value
inputs.qradar_reference_set_name = playbook.inputs.qradar_reference_set_name
inputs.qradar_label = getattr(playbook.inputs, "qradar_server")

Example Function Post Process Script: 

results = playbook.functions.results.qradar_find_reference_set_item_result
if results.get("found") == "True":
  incident.addNote("Found {} in list: {} on QRadar server: {}.".format(artifact.value, results.get("inputs", {}).get("qradar_reference_set_name"), results.get("inputs", {}).get("qradar_label")))
else:
  incident.addNote("{} not found in list: {} on QRadar server: {}.".format(artifact.value, results.get("inputs", {}).get("qradar_reference_set_name"), results.get("inputs", {}).get("qradar_label")))

Function - QRadar SIEM: Find Reference Sets

Find reference sets that contain a given item value, together with information about this item in those reference sets. Information includes whether this item is added to the reference set manually or by a rule.

screenshot: fn-qradar-siem-find-reference-sets

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_set_item_value

text

No

-

Value of a QRadar reference set item

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_set_item_value": "192.168.107.107"
  },
  "reference_items": [
    {
      "collection_id": 35,
      "creation_time": 1557250160405,
      "data": [
        {
          "domain_id": null,
          "first_seen": 1694498079793,
          "last_seen": 1694498079793,
          "source": "EC: Sysmon - Detected a Possible Credential Dumping Tool",
          "value": "192.168.107.107"
        }
      ],
      "element_type": "IP",
      "name": "EC Compromised Hosts",
      "namespace": "SHARED",
      "number_of_elements": 1,
      "timeout_type": "FIRST_SEEN"
    }
  ]
}

Example Function Input Script: 

inputs.qradar_reference_set_item_value = artifact.value
inputs.qradar_label = getattr(playbook.inputs, "qradar_server", None)

Example Function Post Process Script: 

results = playbook.functions.results.qradar_find_reference_sets_result
from datetime import datetime
current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") 
if results.get("reference_items"):
  for item in results.get("reference_items"):
    for ref_set_data in item.get("data"):
      if artifact.value == ref_set_data.get("value"):
        item_row = incident.addRow("qradar_reference_set")
        item_row["query_time"] = current_time
        item_row["qradar_server"] = results.get("inputs", {}).get("qradar_label")
        item_row["reference_set"] = item.get("name")
        item_row["item_value"] = ref_set_data.get("value")
        item_row["source"] = ref_set_data.get("source")
        item_row["qradar_siem_ref_set_namespace"] = item.get("namespace", None)
        item_row["qradar_siem_domain_id"] = ref_set_data.get("domain_id", None)

  incident.addNote("{} Reference sets found. Please refer to the QRadar SIEM Reference Sets data table".format(len(results.get("reference_items"))))
else:
  incident.addNote("No reference sets contain artifact: {} on QRadar server: {}".format(artifact.value, results.get("inputs", {}).get("qradar_label")))

Function - QRadar SIEM: Reference Table Add Item

Add an item to a given QRadar reference table

screenshot: fn-qradar-siem-reference-table-add-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_table_item_inner_key

text

No

-

The inner key for a QRadar Reference Table

qradar_reference_table_item_outer_key

text

No

-

The outer key for a QRadar Reference Table

qradar_reference_table_item_value

text

No

-

Value of a QRadar reference table item

qradar_reference_table_name

text

No

-

Value of a QRadar reference table item

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "content": {
      "collection_id": 44,
      "creation_time": 1694502585199,
      "element_type": "ALN",
      "key_label": "Outer Key Label",
      "key_name_types": {
        "Inner Key 1": "ALN"
      },
      "name": "test_ref_tabe_1",
      "namespace": "SHARED",
      "number_of_elements": 1,
      "timeout_type": "FIRST_SEEN"
    },
    "status_code": 200
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_table_item_inner_key": null,
    "qradar_reference_table_item_outer_key": null,
    "qradar_reference_table_item_value": "192.168.107.107",
    "qradar_reference_table_name": "test_ref_tabe_1"
  },
  "metrics": {
    "execution_time_ms": 1659,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-12 15:10:39",
    "version": "1.0"
  },
  "raw": "{\"status_code\": 200, \"content\": {\"timeout_type\": \"FIRST_SEEN\", \"number_of_elements\": 1, \"creation_time\": 1694502585199, \"name\": \"test_ref_tabe_1\", \"namespace\": \"SHARED\", \"key_name_types\": {\"Inner Key 1\": \"ALN\"}, \"element_type\": \"ALN\", \"collection_id\": 44, \"key_label\": \"Outer Key Label\"}}",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_reference_table_item_value = artifact.value
inputs.qradar_reference_table_item_inner_key = getattr(playbook.inputs, "qradar_ref_table_inner_key")
inputs.qradar_reference_table_item_outer_key = getattr(playbook.inputs, "qradar_ref_table_outer_key")
inputs.qradar_reference_table_name = getattr(playbook.inputs, "qradar_reference_table_name")
inputs.qradar_label = getattr(playbook.inputs, "qradar_server")

Example Function Post Process Script: 

results = playbook.functions.results.qradar_reference_table_add_item_result
note = u"""Outer key: {}
Inner key: {}
Entry: {}
Reference table: {}
QRadar Server: {}""".format(results.get("inputs", {}).get("qradar_reference_table_item_outer_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_inner_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_value"), 
                              results.get("inputs", {}).get("qradar_reference_table_name"),
                              results.get("inputs", {}).get("qradar_label"))
if results.get("success"):
    incident.addNote(u"Successful add\n{}".format(note))
else:
    incident.addNote(u"Failure to add item: {}\n{}".format(results.get("reason"), note))

Function - QRadar SIEM: Reference Table Delete Item

Delete an item from a given QRadar reference table

screenshot: fn-qradar-siem-reference-table-delete-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_table_item_inner_key

text

No

-

The inner key for a QRadar Reference Table

qradar_reference_table_item_outer_key

text

No

-

The outer key for a QRadar Reference Table

qradar_reference_table_item_value

text

No

-

Value of a QRadar reference table item

qradar_reference_table_name

text

No

-

Value of a QRadar reference table item

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "content": {
      "collection_id": 28,
      "creation_time": 1607452116847,
      "element_type": "ALN",
      "name": "pulse_imports",
      "namespace": "SHARED",
      "number_of_elements": 5,
      "timeout_type": "UNKNOWN"
    },
    "status_code": 200
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_table_item_inner_key": "part-3",
    "qradar_reference_table_item_outer_key": "pulse-a142f062-f41b-4c2c-96b8-4ab4e3b7bde4",
    "qradar_reference_table_item_value": "test123",
    "qradar_reference_table_name": "pulse_imports"
  },
  "metrics": {
    "execution_time_ms": 1420,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-15 16:58:55",
    "version": "1.0"
  },
  "raw": "{\"status_code\": 200, \"content\": {\"timeout_type\": \"UNKNOWN\", \"number_of_elements\": 5, \"creation_time\": 1607452116847, \"name\": \"pulse_imports\", \"namespace\": \"SHARED\", \"element_type\": \"ALN\", \"collection_id\": 28}}",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_reference_table_name = row.table
inputs.qradar_reference_table_item_outer_key = row.outer_key
inputs.qradar_reference_table_item_inner_key = row.inner_key
inputs.qradar_reference_table_item_value = row.value
inputs.qradar_label = row["qradar_server"]

Example Function Post Process Script: 

results = playbook.functions.results.qradar_reference_table_delete_item_result
note = u"""Outer key: {}
Inner key: {}
Entry: {}
Reference table: {}
QRadar Server: {}""".format(results.get("inputs", {}).get("qradar_reference_table_item_outer_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_inner_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_value"), 
                              results.get("inputs", {}).get("qradar_reference_table_name"),
                              row["qradar_server"])
if results.get("success"):
    incident.addNote(u"Successful delete\n{}".format(note))
    row['status'] = "deleted"
else:
    incident.addNote(u"Failure to delete item: {}\n{}".format(results.get("reason"), note))

Function - QRadar SIEM: Reference Table Get All Tables

Get all reference tables from a QRadar instance

screenshot: fn-qradar-siem-reference-table-get-all-tables

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_query_range_end

number

No

-

Range end number

qradar_query_range_start

number

No

-

Range start number

qradar_reference_table_return_fields

multiselect

No

-

The fields that will be returned.

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": [
    {
      "collection_id": 43,
      "creation_time": 1693550078786,
      "element_type": "ALN",
      "key_label": "offense_id",
      "name": "Generated_Cases",
      "namespace": "SHARED",
      "number_of_elements": 0,
      "time_to_live": "0 years 1 mons 0 days 0 hours 0 mins 0.0 secs",
      "timeout_type": "LAST_SEEN"
    },
    {
      "collection_id": 28,
      "creation_time": 1607452116847,
      "element_type": "ALN",
      "name": "pulse_imports",
      "namespace": "SHARED",
      "number_of_elements": 5,
      "timeout_type": "UNKNOWN"
    },
    {
      "collection_id": 44,
      "creation_time": 1694502585199,
      "element_type": "ALN",
      "key_label": "Outer Key Label",
      "key_name_types": {
        "Inner Key 1": "ALN"
      },
      "name": "test_ref_tabe_1",
      "namespace": "SHARED",
      "number_of_elements": 1,
      "timeout_type": "FIRST_SEEN"
    }
  ],
  "inputs": {
    "qradar_label": "1.1.1.1"
  },
  "metrics": {
    "execution_time_ms": 1442,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-15 18:47:24",
    "version": "1.0"
  },
  "raw": "[{\"time_to_live\": \"0 years 1 mons 0 days 0 hours 0 mins 0.0 secs\", \"timeout_type\": \"LAST_SEEN\", \"number_of_elements\": 0, \"creation_time\": 1693550078786, \"name\": \"Generated_Cases\", \"namespace\": \"SHARED\", \"element_type\": \"ALN\", \"collection_id\": 43, \"key_label\": \"offense_id\"}, {\"timeout_type\": \"UNKNOWN\", \"number_of_elements\": 5, \"creation_time\": 1607452116847, \"name\": \"pulse_imports\", \"namespace\": \"SHARED\", \"element_type\": \"ALN\", \"collection_id\": 28}, {\"timeout_type\": \"FIRST_SEEN\", \"number_of_elements\": 1, \"creation_time\": 1694502585199, \"name\": \"test_ref_tabe_1\", \"namespace\": \"SHARED\", \"key_name_types\": {\"Inner Key 1\": \"ALN\"}, \"element_type\": \"ALN\", \"collection_id\": 44, \"key_label\": \"Outer Key Label\"}]",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_label = getattr(playbook.inputs, "qradar_server")
if getattr(playbook.inputs, "qradar_ref_table_range_limit_start", None) and if getattr(playbook.inputs, "qradar_ref_table_range_limit_end", None):
  inputs.qradar_query_range_start = playbook.inputs.qradar_ref_table_range_limit_start
  inputs.qradar_query_range_end = playbook.inputs.qradar_ref_table_range_limit_end
if getattr(playbook.inputs, "qradar_ref_table_fields_to_be_returned", None):
  inputs.qradar_reference_table_return_fields = playbook.inputs.qradar_ref_table_fields_to_be_returned

Example Function Post Process Script: 

results = playbook.functions.results.qradar_reference_table_get_all_tables_result
from datetime import datetime
current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") 
if results.get("success"):
  if results.get("content"):
    for item in results.get("content"):
      item_row = incident.addRow("qradar_reference_table")
      item_row["query_time"] = current_time
      item_row["qradar_server"] = results.get("inputs", {}).get("qradar_label")
      item_row["reference_table"] = item.get("name")
      item_row["collection_id"] = item.get("collection_id")
      item_row["number_of_elements"] = item.get("number_of_elements")
      item_row["namespace"] = item.get("namespace")
    incident.addNote("QRadar SIEM: Get all Reference Tables: {} Reference tables have successfully been queried".format(len(results.get("content"))))
  else:
    incident.addNote("No reference tables found")
else:
  incident.addNote("An error occurred getting the reference tables: {} from QRadar server: {}".format(results.get("reason"), getattr(playbook.inputs, "qradar_label")))

Function - QRadar SIEM: Reference Table Get Table Data

Get the elements in the reference table

screenshot: fn-qradar-siem-reference-table-get-table-data

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_table_name

text

No

-

Value of a QRadar reference table item

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "collection_id": 44,
    "creation_time": 1694502585199,
    "data": {
      "None": {
        "None": {
          "domain_id": null,
          "first_seen": 1694502641647,
          "last_seen": 1694502641647,
          "source": "reference data api",
          "value": "192.168.107.107"
        }
      }
    },
    "element_type": "ALN",
    "key_label": "Outer Key Label",
    "key_name_types": {
      "Inner Key 1": "ALN"
    },
    "name": "test_ref_tabe_1",
    "namespace": "SHARED",
    "number_of_elements": 1,
    "timeout_type": "FIRST_SEEN"
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_table_name": "test_ref_tabe_1"
  },
  "metrics": {
    "execution_time_ms": 1392,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-15 19:00:19",
    "version": "1.0"
  },
  "raw": "{\"timeout_type\": \"FIRST_SEEN\", \"number_of_elements\": 1, \"data\": {\"None\": {\"None\": {\"last_seen\": 1694502641647, \"first_seen\": 1694502641647, \"source\": \"reference data api\", \"value\": \"192.168.107.107\", \"domain_id\": null}}}, \"creation_time\": 1694502585199, \"name\": \"test_ref_tabe_1\", \"namespace\": \"SHARED\", \"key_name_types\": {\"Inner Key 1\": \"ALN\"}, \"element_type\": \"ALN\", \"collection_id\": 44, \"key_label\": \"Outer Key Label\"}",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_reference_table_name = row['reference_table']
inputs.qradar_label = row["qradar_server"]

Example Function Post Process Script: 

results = playbook.functions.results.qradar_reference_table_get_table_data_result
from datetime import datetime
current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") 
if results.get("success"):
  for outer_key, item in results.get("content", {}).get('data',[]).items():
    for inner_key, inner_item in item.items():
      table_row = incident.addRow('qradar_reference_table_queried_rows')
      table_row['query_time'] = current_time
      table_row['qradar_server'] = row["qradar_server"]
      table_row['table'] = results.get("inputs", {}).get("qradar_reference_table_name")
      table_row['outer_key'] = outer_key
      table_row['inner_key'] = inner_key
      
      table_row['value'] = inner_item.get('value')
      table_row['status'] = 'active'
  num_data_gathered = len(results.get("content").get('data',[]).items()) * len(item.items())
  incident.addNote("{} Reference table data have been gathered".format(num_data_gathered))
else:
  incident.addNote("An error occurred getting the reference table data: {}".format(results.get("reason")))

Function - QRadar SIEM: Reference Table Update Item

Update an item in a given QRadar reference table

screenshot: fn-qradar-siem-reference-table-update-item

Inputs:

Name

Type

Required

Example

Tooltip

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_reference_table_item_inner_key

text

No

-

The inner key for a QRadar Reference Table

qradar_reference_table_item_outer_key

text

No

-

The outer key for a QRadar Reference Table

qradar_reference_table_item_value

text

No

-

Value of a QRadar reference table item

qradar_reference_table_name

text

No

-

Value of a QRadar reference table item

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "content": {
      "collection_id": 28,
      "creation_time": 1607452116847,
      "element_type": "ALN",
      "name": "pulse_imports",
      "namespace": "SHARED",
      "number_of_elements": 6,
      "timeout_type": "UNKNOWN"
    },
    "status_code": 200
  },
  "inputs": {
    "qradar_label": "1.1.1.1",
    "qradar_reference_table_item_inner_key": "part-3",
    "qradar_reference_table_item_outer_key": "pulse-a142f062-f41b-4c2c-96b8-4ab4e3b7bde4",
    "qradar_reference_table_item_value": "test123",
    "qradar_reference_table_name": "pulse_imports"
  },
  "metrics": {
    "execution_time_ms": 1365,
    "host": "local",
    "package": "fn-qradar-integration",
    "package_version": "2.3.0",
    "timestamp": "2023-09-15 16:57:43",
    "version": "1.0"
  },
  "raw": "{\"status_code\": 200, \"content\": {\"timeout_type\": \"UNKNOWN\", \"number_of_elements\": 6, \"creation_time\": 1607452116847, \"name\": \"pulse_imports\", \"namespace\": \"SHARED\", \"element_type\": \"ALN\", \"collection_id\": 28}}",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.qradar_label = row["qradar_server"]
inputs.qradar_reference_table_name = row.table
inputs.qradar_reference_table_item_outer_key = row.outer_key
inputs.qradar_reference_table_item_inner_key = row.inner_key

if playbook.inputs.qradar_ref_table_update:
  inputs.qradar_reference_table_item_value = getattr(playbook.inputs, "qradar_ref_table_update")
else:
  inputs.qradar_reference_table_item_value = "This is an example"

Example Function Post Process Script: 

results = playbook.functions.results.qradar_reference_table_update_result
note = u"""Outer key: {}
Inner key: {}
Entry: {}
Reference table: {}
QRadar Server: {}""".format(results.get("inputs", {}).get("qradar_reference_table_item_outer_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_inner_key"),
                              results.get("inputs", {}).get("qradar_reference_table_item_value"), 
                              results.get("inputs", {}).get("qradar_reference_table_name"),
                              row["qradar_server"])
if results.get("success"):
    incident.addNote(u"Successful updated\n{}".format(note))
    row['status'] = 'updated'
    row['value'] = results.get("inputs", {}).get("qradar_reference_table_item_value")
else:
    incident.addNote(u"Failure to updated item: {}\n{}".format(results.get("reason"), note))

Function - QRadar SIEM: Update Offense

Use for making updates to a QRadar offense, including closing an offense

screenshot: fn-qradar-siem-update-offense

Inputs:

Name

Type

Required

Example

Tooltip

qradar_id

number

Yes

-

-

qradar_label

text

No

-

Enter name of QRadar server to use from the app.config

qradar_update_json

text

Yes

{ "status": "CLOSED", "closing_reason_id":1 }

json encoding of fields to update

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "assigned_to": null,
    "categories": [
      "User Login Success"
    ],
    "category_count": 1,
    "close_time": 1713465658000,
    "closing_reason_id": 1,
    "closing_user": "API_token: ms qradar integration",
    "credibility": 2,
    "description": "Login\n",
    "destination_networks": [
      "other"
    ],
    "device_count": 1,
    "domain_id": 3,
    "event_count": 1,
    "first_persisted_time": 1711492873000,
    "flow_count": 0,
    "follow_up": false,
    "id": 164,
    "inactive": true,
    "last_persisted_time": 1713465658000,
    "last_updated_time": 1711492873201,
    "local_destination_address_ids": [],
    "local_destination_count": 0,
    "log_sources": [
      {
        "id": 962,
        "name": "F5FirePass @ f5networks.firepass.test.com",
        "type_id": 232,
        "type_name": "F5FirePass"
      }
    ],
    "magnitude": 1,
    "offense_source": "31.107.167.255",
    "offense_type": 0,
    "policy_category_count": 0,
    "protected": false,
    "relevance": 0,
    "remote_destination_count": 1,
    "rules": [
      {
        "id": 100462,
        "type": "CRE_RULE"
      }
    ],
    "security_category_count": 1,
    "severity": 1,
    "source_address_ids": [
      99
    ],
    "source_count": 1,
    "source_network": "other",
    "start_time": 1711492873201,
    "status": "CLOSED",
    "username_count": 1
  },
  "inputs": {
    "qradar_id": 164,
    "qradar_label": "11.22.33.44",
    "qradar_update_json": "{\"status\": \"CLOSED\", \"closing_reason_id\": 1}"
  },
  "metrics": {
    "execution_time_ms": 499,
    "host": "localhost",
    "package": "fn-qradar-integration",
    "package_version": "2.4.0",
    "timestamp": "2024-04-18 14:40:58",
    "version": "1.0"
  },
  "raw": null,
  "reason": null,
  "success": true,
  "version": 2
}

Example Function Input Script: 

import json

closing_reason_lookup = {
  "False Positive": 2,
  "Non-Issue": 1,
  "Policy Violation": 3,
  "Duplicate": 56,
  "Not an Issue": 57,
  "Resolved": 54,
  "Unresolved": 55
}

if not closing_reason_lookup.get(playbook.inputs.closing_reason):
  helper.fail(f"Closing reason not found: {playbook.inputs.closing_reason}")

inputs.qradar_label = playbook.inputs.qradar_label
inputs.qradar_id = playbook.inputs.qradar_id
inputs.qradar_update_json = json.dumps({
  "status": "CLOSED", 
  "closing_reason_id": closing_reason_lookup.get(playbook.inputs.closing_reason)
})

Example Function Post Process Script: 

results = playbook.functions.results.qradar_update_offense_results
if results.success:
  incident.addNote(f"QRadar offense update successful for: {playbook.inputs.qradar_id}")
else:
  incident.addNote(f"QRadar offense update failed for: {playbook.inputs.qradar_id} Reason: {results.reason}")

Playbooks

Playbook Name

Description

Activation Type

Object

Status

Condition

QRadar SIEM: Find in Reference Set - Example (PB)

Look for an item in QRadar reference set and add a note to the SOAR Incident

Manual

artifact

enabled

-

QRadar SIEM: Get All Reference Sets -Example (PB)

Get all the QRadar reference sets that contain the given artifact

Manual

artifact

enabled

-

QRadar SIEM: Add Item to this Reference Table - Example (PB)

Add a reference table item based on an existing named reference table

Manual

qradar_reference_table

enabled

-

QRadar SIEM: Add to Reference Set - Example (PB)

Add an IP address artifact to QRadar reference set

Manual

artifact

enabled

artifact.type equals IP Address

QRadar SIEM: Add to Reference Table - Example (PB)

Add a reference table item based on an artifact value

Manual

artifact

enabled

-

QRadar SIEM: Delete this Reference Table Item - Example (PB)

An example playbook that deletes a Reference Table Queried Row

Manual

qradar_reference_table_queried_rows

enabled

qradar_reference_table_queried_rows.status not_equals deleted

QRadar SIEM: Gather Reference Table Data - Example (PB)

Make a query on a reference table and return its results into another datatable

Manual

qradar_reference_table

enabled

-

QRadar SIEM: Get all Reference Tables - Example (PB)

An example playbook that returns a list of all Reference Tables on the QRadar instance.

Manual

incident

enabled

-

QRadar SIEM: Move from Sample Blocked to Sample Suspected - Example (PB)

Remove an item from QRadar reference set and add it to reference set. Add a note to the Incident after completing each step.

Manual

artifact

enabled

artifact.type equals IP Address

QRadar SIEM: Bulk Add Reference Set Items - Example (PB)

Add or update data in a reference set.

Manual

incident

enabled

-

QRadar SIEM: Create Note

Create a note for an offense

Manual

incident

enabled

-

QRadar SIEM: Update Offense (close offense)

Example of closing an offense using the Update Offense function

Manual

incident

enabled

-

QRadar SIEM: Update this Reference Table Item - Example (PB)

Update an existing reference table item. If it does not exist, it will be added

Manual

qradar_reference_table_queried_rows

enabled

qradar_reference_table_queried_rows.status not_equals deleted

QRadar SIEM: Get QRadar Offense Events - Example (PB)

Use the qradar_id field of the incident to search qradar events, and update the data table, qradar_offense_event, with the first 5 results.

Manual

incident

enabled

incident.properties.qradar_id has_a_value

Custom Layouts

  • Import the Data Tables and Custom Fields like the screenshot below:

    screenshot: custom_layouts

Data Table - QRadar SIEM Offense Events

screenshot: dt-qradar-siem-offense-events

API Name:

qradar_offense_event

Columns:

Column Name

API Access Name

Type

Tooltip

Category

category

text

-

Log Source

log_source

text

logsourceid

Protocol

protocol

text

protocolid

QRadar Server

qradar_server

text

-

Query Time

query_time

text

-

Rule

rule

text

creeventlist

Start Time

start_time

text

starttime

Data Table - QRadar SIEM Reference Sets

screenshot: dt-qradar-siem-reference-sets

API Name:

qradar_reference_set

Columns:

Column Name

API Access Name

Type

Tooltip

Domain ID

qradar_siem_domain_id

text

Specify the numeric domain_id tag for the data or SHARED for Admin users.

Item Value

item_value

text

Item value

Namespace

qradar_siem_ref_set_namespace

text

Either SHARED or TENANT.

QRadar Server

qradar_server

text

-

Query Time

query_time

text

-

Reference Set

reference_set

text

Name of reference set

Source

source

text

how this value is added to the reference set

Data Table - QRadar SIEM Reference Table Queried Rows

screenshot: dt-qradar-siem-reference-table-queried-rows

API Name:

qradar_reference_table_queried_rows

Columns:

Column Name

API Access Name

Type

Tooltip

Inner Key

inner_key

text

-

Outer Key

outer_key

text

-

QRadar Server

qradar_server

text

-

Query Time

query_time

text

-

Status

status

text

-

Table

table

text

-

Value

value

text

-

Data Table - QRadar SIEM Reference Tables

screenshot: dt-qradar-siem-reference-tables

API Name:

qradar_reference_table

Columns:

Column Name

API Access Name

Type

Tooltip

Collection Id

collection_id

text

-

Namespace

namespace

text

-

Number Of Elements

number_of_elements

text

-

QRadar Server

qradar_server

text

-

Query Time

query_time

text

-

Reference Table

reference_table

text

-

Custom Fields

Label

API Access Name

Type

Prefix

Placeholder

Tooltip

QRadar SIEM Offense ID

qradar_id

text

properties

-

ID number of the QRadar offense

qradar_destination

qradar_destination

text

properties

-

QRadar Destination to Sync With

How to configure to use a single QRadar Server

To use only a single server there are two ways this can be configured

  1. Use the configuration used in QRadar Integration versions prior to V2.2.0 screenshot: qr-single-server

  2. Either keep the label, SOAR_Plugin_Destination_Name1, or change it (The label does not matter when only one server is configured) screenshot: qr-single-label-server

Creating Playbooks when server/servers in app.config are labeled

The function input field qradar_label is required when QRadar server/servers in the app.config are labeled. In the example playbook pre-process scripts the input field qradar_label is defined the following way,

inputs.qradar_label = incident.properties.qradar_destination

Troubleshooting & Support

Refer to the documentation listed in the Requirements section for troubleshooting information.

For Support

This is a IBM Community provided app. Please search the Community ibm.biz/soarcommunity for assistance.