Communicating with QRadar hosts from Python

You can communicate with IBM® QRadar® Hosts from Python by using the REST endpoints that QRadar exposes.

As part of any communication from QRadar to an app, QRadar provides the following headers:

QRADAR-USER: This header contains theQRadar user name.
QRADAR-USER-ROLE: This header contains the user role assigned to the user.
QRADAR-SECURITY-PROFILE: This header contains the security profile that defines which networks, log sources, and domains that the user can access

qpylib library

The qpylib library provides functions that encapsulate much of the logic that is required to initiate this communication.

For REST API calls, use the qpylib.REST(RESTtype, request_url, headers, data, json, params, version) function. This function prepends the IP address of the host console to the request URL.

This REST function acts as a wrapper for the Python requests library. It returns a requests.Response object.

The following table describes the fields that you can access from this object:

Table 1. Response fields
Field Name	Description
status_code	Status code for the response. Useful for determining the success of a request. For example, if you are checking for a `200` response.
url	URL of the request.
headers	Dictionary object that contains the response headers.
text	Raw text output of the response. Useful for debugging purposes.

The function parameters are explained in the following table:

Table 2. Function parameters
Parameter Name	Explanation
RESTtype	String REST request type. Accepts 'GET', 'PUT', 'POST' and 'DELETE'.
request_url	URL of the REST endpoint. The qpylib library prepends the appropriate console IP address to the URL so that only the URL from /api/ is needed. For example: /api/gui_app_framework/applications.
headers (optional)	Optional headers to be added to the request. Headers must be contained within a Python dictionary object, for example, `{'Accept': 'application/json'}`.
data (optional)	Optional data that can be contained within a request's body. Data must be in the format that is appropriate to the REST endpoint. For example, data must be converted to a JSON string by using the JSON Python library (json.dumps()) when a REST endpoint accepts application/json.
json (optional)	Optional parameter that accepts Python dictionary objects that are converted to a JSON String that is included in the request's body.
params (optional)	Optional parameter that accepts Python dictionary objects that are converted to URL query parameters.
version (optional)	Optional parameter that specifies which version of the QRadar RESTful API to use. The value must be a string that matches a supported version of the QRadar RESTful API (for example, `5.0`). If no version is specified, no version header is sent and the most recent version is used by default.

The Response object also contains functions that simplify access to the data contained in the response body. You can use the json() function to retrieve a dictionary object that contains the response body, or a list of dictionary objects if the endpoint returns a collection.

Example: Get QRadar Offenses

import qpylib
offenses_endpoint = '/api/siem/offenses'
headers = {'content-type' :  'application/json'}
response = qpylib.REST('GET', offenses_endpoint, headers=headers)
offenses_json_list = response.json()
# List containing dictionary objects for each QRadar offense

# Iterate over each offense JSON in the list and print its id.
format_string =  'Found offense id [{0}].'
for offense_json  in offenses_json_list:
             offense_id = str(offense_json['id'])  # Access fields
             print(format_string.format(offense_id))

Example: Get QRadar Offenses With Queries

import qpylib
offenses_endpoint = '/api/siem/offenses'
headers = {'content-type' : 'application/json'}
params= { 'filter' : 'inactive=false' }
response = qpylib.REST('GET', offenses_endpoint, headers=headers, params=params)
offenses_json_list = response.json()

Example: Post QRadar Offense Closing Reason

import qpylib
offense_closing_reasons_endpoint = '/api/siem/offense_closing_reasons'
headers = {'content-type' : 'application/json'}
json_dict = { 'reason' : 'Demonstrating posting data to QRadar'}
response = qpylib.REST('POST', offense_closing_reasons_endpoint, 
                        headers=headers, json=json_dict)