IBM QRadar

7.4.0

Application Framework Guide

IBM



Note

Before you use this information and the product that it supports, read the information in “Notices” on

page 139.

®

What's new for the application framework in QRadar V.7.4.0....................................................................1

QRadar apps ................................................................................................................................................1

QRadar app development overview ............................................................................................................2

GUI application framework fundamentals..................................................................................................3

App le structure..........................................................................................................................................7

Software development kit overview..........................................................................................................38

Installing the SDK...................................................................................................................................... 40

Use Python 2.7 in your app .......................................................................................................................40

Creating your development environment................................................................................................. 41

Creating an extension from your app........................................................................................................ 50

Sample apps.............................................................................................................................................. 54

Support functions...................................................................................................................................... 83

QRadar Python helper library functions....................................................................................................85

Jinja2 templates........................................................................................................................................ 86

App Framework JavaScript library............................................................................................................ 87

Communicating with QRadar hosts from Python......................................................................................89

GUI Application Framework REST API endpoints.................................................................................... 91

App logs......................................................................................................................................................92

Application globalization........................................................................................................................... 99

Custom fragments injection points......................................................................................................... 108

Custom column injection points..............................................................................................................114

Custom actions for CRE responses......................................................................................................... 115

Trademarks.............................................................................................................................................. 140

Terms and conditions for product documentation................................................................................. 140

IBM Online Privacy Statement................................................................................................................ 141

iv

The QRadar app framework v1 documentation is now on GitHub.

You can now access the documentation at https://ibmsecuritydocs.github.io/qradar_appfw_v1/.

Note: Use this documentation for maintaining apps that are built by using CentOS, Python 2, and the

QRadar App Framework version 1. For newer apps that are built using Red Hat Universal Base Image

(UBI) 8 and Python 3, see the App Framework version 2 documentation. IBM

Exchange no

Assistant, and Log source manager, can now be used in a multi-tenant environment.

App developers will now be able to mark that their app has been tested and works in a multi-tenanted

environment. There are two forms of multi-tenancy support in apps:

1. The app is tested and works with multi-tenancy, but it is not multi-tenancy aware. When a user installs

the app, they are presented with the option to create a default instance. Users can select this option

if they only want a single instance of the app, or the app does not need to support multi-tenancy. If

a user does not select the Default Instance option, they must create a separate instance for each

customer and associate each instance with a security prole to keep all client data separate.

2. The app is tested and is multi-tenancy aware. In this case, only one instance of the app is necessary.

This type of app is also benecial if the app is designed to be used only by administrators.

You create your own apps from QRadar by using the QRadar GUI Application Framework Software

Development Kit (SDK). You can then package the app and reuse it in other QRadar deployments. You

can share your app on the IBM X-Force Exchange portal (https://exchange.xforce.ibmcloud.com/).

Apps provide new tabs, API methods, dashboard items, pop-up menus, toolbar buttons, conguration

pages, and more within the QRadar user interface. The functionality is entirely dened by Python Flask

framework apps that serves the app endpoints from a secure container.

Important: The QRadar app framework does not support systems that are congured using the Security

Technical Implementation Guide (STIG). Customers that use STIG hardened systems can not install apps

in QRadar.

Copyright IBM Corp. 2016, 2020 1

You can see a list of available apps on the IBM Security App Exchange (https://

exchange.xforce.ibmcloud.com/hub). Filter apps by selecting the Application check box.

2

 IBM QRadar : QRadar Application Framework Guide

If your app requires a minimum memory allocation, you must provide information about it in your app's

documentation.

Chapter 1. Developing with the QRadar app framework

3

• Validates the manifest of the app.

GET /gui_app_framework/

applications/

{application_id}

POST /gui_app_framework/

applications/

{application_id}

PUT /gui_app_framework/

4 IBM QRadar : QRadar Application Framework Guide

gui_app_framework/

applications/

{application_id}

GET /gui_app_framework/

named_services

GET /gui_app_framework/

named_services/{uuid}

Flask is the web server from which the app-coded endpoints are served. You use Python functions to

deliver use cases. You can use route annotations for each Python method in the Flask application. After

the Flask web server starts, HTTP/HTTPS-bound requests are serviced by Flask for that route, and the

Python functions are run.

Each Flask server that is run from within the Docker container uses port 5000. Outwardly from the

container, Docker maps that internal port 5000 to the next free port from the 32768-60999 ephemeral

range. During the registration phase, this outward mapped port is stored by QRadar so that web requests

for an app, through QRadar are proxied to the correct container.

The following code is a sample Python route:

Version Description

Flask 0.10.1 Microframework, or micro web application

itsdangerous 0.24 Utility package for signing and encrypting data

jinja2 2.7.3 Template engine for python

markupsafe 0.23 Unicode escape library used alongside Jinja2

Werkzeug 0.96 WSGI (Web Server Gateway Interface) utility

For more information, see the Flask website (http://flask.pocoo.org/).

Chapter 1. Developing with the QRadar app framework

5

root. Only URLs that live within the QRadar

application can be referenced.

String

afliate with their user role to access this

area.

or URI encoded parameters in the PUT or POST body.

REST methods are typically implemented in Python by using the Flask framework.

The following implementation of a REST method retrieves a type of metadata:

This method is then exposed in the manifest in the following way:

The following table describes the Rest_methods block elds in the manifest.json le.

12

 IBM QRadar : QRadar Application Framework Guide

the app.

method Yes String An HTTP method on named endpoint (GET/

url Yes String The URL to access the REST method,

relative to the app root. Only URLs within

the app are supported.

String

afliate with their user role to access this

method.

A new item on the IBM QRadar dashboard. These items are available to users, who must manually add

the items to their dashboard.

The contents of the item come from the response of the REST method execution. The expected format of

the response is outlined in the following way:

Table 6.

Field Required Type Description

text Yes String A unique ID for this area.

description Yes String Concise text to display that describes the

area. Can optionally point at a resource

bundle key if the application is globalized.

rest_method Yes String Name of the REST method to load this item.

Must be declared in the rest_methods

section of the manifest.

Chapter 1. Developing with the QRadar app framework13

The following code is a sample dashboard_items block from the manifest.json le:

14

 IBM QRadar : QRadar Application Framework Guide

Chapter 1. Developing with the QRadar app framework15

action is performed. Either this argument or

the REST method argument is required. If

both are specied, then the REST method

You must provide at least 1 group.

You can also use a group name in

this format ariel:<FIELD_NAME>, where

<FIELD_NAME> is the name of a eld in

the QRadar Event or Flow viewer. If this

eld is specied, the action is installed into

the menu of that eld, and the context

parameter is the contents of the eld.

required_capabilities No Array of

String

A set of capabilities that a user must

afliate with their user role to access this

16

 IBM QRadar : QRadar Application Framework Guide

page_id String The page ID that includes the scripts.

scripts Array of String The relative path to scripts that you

The following table describes the metadata_providers block elds in the manifest.json le.

Chapter 1. Developing with the QRadar app framework

metadata_type Yes String Type of metadata that can be fetched

Describes the language locales and locations of the locale properties le locations that you use when you

globalize your app.

The following table describes the Resource_bundles block elds in the manifest.json le.

Table 11.

Field Required Type Description

locale Yes String Language locale code

bundles Yes String Path to the globalization resource

bundle properties les. Files are stored

in the /app/static/resources/

18 IBM QRadar : QRadar Application Framework Guide

The following code is a sample resource_bundles block from the manifest.json le:

Text strings for globalization are stored as key/value pairs in Java format properties les. If you congured

text strings for globalization, they appear in IBM QRadar when the user sets their preferences for the

relevant locale.

QRadar API and test the application locally before you upload to your QRadar production instance.

The following table describes the parameters of the Dev_opts block:

Table 12.

Field Required Type Description

console_ip Yes String The IP address of the remote

The following code is a sample dev_opts block from the manifest.json le:

Chapter 1. Developing with the QRadar app framework

20 IBM QRadar : QRadar Application Framework Guide

custom content is injected.

Chapter 1. Developing with the QRadar app framework21

(=) sign.

The Hello World sample app

When you add an app in the Application Development Manager window, a simple "Hello World" sample

app is also created.

The Hello World sample app adds a Hello World tab to QRadar.

The following image shows an example of the Hello World tab that is added to QRadar.

You can use this sample app as a simple template from which to build your own apps that require tabs.

When you run the development environment script, the les that are described in the following table are

added to your application development folder:

Table 19. Application development

imports views from the views.py script and functions from the qpylib

library.

views.py the main entry point into the web application. This le and

the manifest.json le are the only les that are required in every app.

Contains sample code for the Hello World app.

qradar_appfw_venv Contains the Python virtual environment where the dependencies are

installed.

__init__.py Creates an instance of the Flask micro-framework that is used to serve

content to QRadar.

manifest.json Describes to QRadar what the sample Hello World app does.

28 IBM QRadar : QRadar Application Framework Guide

The rst four objects, name, description, version, and uuid provide basic app information.

The areas object describes the capabilities of the Hello World app. The QRadar GUI Application

Framework uses areas objects to describe new complete pages of the app. Areas objects are

represented as tabs in the user interface.

The areas block contains the elds that are described in the following table:

Table 20. Areas block

Name Description Value

id The ID of the new tab QHelloWorld

text The name of the tab that is displayed in the user

interface.

Hello World

s

users with Administrator privileges.

The dev_opts block is used to provide the IP address of networked instance of QRadar Console for

testing purposes. This block is not required for this sample app.

The views.py le contains the following code:

Chapter 1. Developing with the QRadar app framework

The code creates the default '/' and '/index' routes, both of which return a simple string. The index

route is declared in the url eld of the manifest.json le.

dene all the necessary endpoints and routes that serve content back to QRadar.

The run.py le creates a new Flask application (by starting the Flask web server), from the app

directory.

app to it.

However, most importantly you can use the Hello World sample app les as a template to start developing

your own QRadar apps.

You can build on the Hello World sample app that the IBM QRadar SDK installs in your app workspace to

add a tab to QRadar.

You can build an app that uses a Jinja2 template to serve HTML content to a new tab as shown in the

following image.

The les and folders that are described in the following table are required for the tab example:

30

 IBM QRadar : QRadar Application Framework Guide

from flask import render_template

def index():

return render_template("index.html",

title = "QApp1 : Hello World !")

The Flask app route uses a Flask-Jinja2 templated HTML page to build the

content for the Hello World tab.

/templates/index.html - The Jinja2 template to render when requests

are routed to app.route annotated endpoints.

/static/css/style.css Renders the content that is served by the Jinja2

code, which is changed sightly from the Hello World sample app example.

"areas": [

{

"id":"QHelloWorld",

"text":"Hello World",

"description":"A Hello World app",

"url":"index",

"required_capabilities":["ADMIN"]

The dev_opts is removed and is needed only for testing the app on a

networked QRadar Console.

Chapter 1. Developing with the QRadar app framework

Functionally, this manifest le is identical to the manifest.json that is provided in the basic "Hello

32

 IBM QRadar : QRadar Application Framework Guide

Important: Apps in QRadar App Editor 3.0 support QRadar App Framework V2 apps only. The QRadar

App Editor does not provide any automatic migration tools. Instead, users can follow the instructions to

migrate an app from QRadar App Framework V1 to V2. For more information, see Migrating from App

Chapter 1. Developing with the QRadar app framework

Tip: The QRadar App Editor does not provide any automatic migration tools. Instead, users can follow

the instructions to migrate an app from QRadar App Framework V1 to V2. For more information, see

Migrating from App Framework v1 to v2.

• IBM

•

), and then click Admin to open the

3. Click Extensions Management and follow these steps:

2. On the navigation menu, click Apps, and then click the Develop Applications icon.

The following table shows the tiles that you can select on the IBM Application Development Manager

window.

34

 IBM QRadar : QRadar Application Framework Guide

selecting one of the other templates that you clone from a Git repository.

3. To develop a new app that uses the one of the available templates, click the New App tile.

Chapter 1. Developing with the QRadar app framework

• To select an existing app (.zip le), click Browse to nd the local app, or drag and drop an app into

36

 IBM QRadar : QRadar Application Framework Guide

• To clone an app from a Git repository, type the Git repository URL in the Enter the git repository url

the app.

download the app from the Git repository. This feature is useful when you're using a local

You might have to wait for a short time before the tab for the app appears in QRadar.

Edit and create les and folders in the app editor tab, which is created on the QRadar Console.

When you install a new app, the Hello World development tab that includes the editor is added to the

Console, and a second tab shows the Hello World app in normal installed mode without the editor.

The following diagram shows the rst Hello World app tab without the editor, and the Hello World -

Custom Tab Development tab that includes the editor on QRadar.

Figure 4. Hello World tabs

4. Copy or move les from one folder to folder in the app folder navigation.

Chapter 1. Developing with the QRadar app framework

If this command returns 2.7.x, it might indicate an issue with pyenv. To solve this problem, open or

create the ~/.bash_profile le in a text editor and add the following lines:

export PATH=/usr/local/bin:$PATH

export PYENV_ROOT="$HOME/.pyenv"

export PATH="$PYENV_ROOT/shims:$PATH"

folder.

2. Package your app by using the following command syntax:

qradar_app_creator package -w <path_to_app_folder>/<app_name_folder> -p

• To package an app on UNIX or Linux computers, type the following command:

• To package an app on a Windows computer, type the following command:

state output that is returned when you issue the qradar_app_creator deploy command. You

need it when you export you app as a QRadar extension.

In the following example, the application ID is 1023.

Application Creation Task state: {u'status': u'COMPLETED',

u'application_id': u1023', u'error_messages': u'[]'}

If you're viewing your QRadar Console user interface in a browser, refresh your browser to see your

app running.

After you successfully test your app, you can use the QRadar Content Management Tool to export the app

as an extension. You then use the QRadar Extensions Management tool on the Admin settings page to

44

 IBM QRadar : QRadar Application Framework Guide

1. Run your app locally.

• To run on Unix or Linux, type the following command:

• To run on Windows, type the following command:

2. Open a browser and type http://0.0.0.0:5000 in the address bar. If your browser does not

support the http://0.0.0.0 URL, type http://127.0.0.1:5000.

Your app is displayed in the browser window, and the application output is sent to the command line or

to your terminal.

resources.

The following example shows the authentication section in the manifest le.

The "authorisation_flow" entry is optional. The only accepted value is "CLIENT_CREDENTIALS".

If the authorization is not congured as CLIENT_CREDENTIALS, the installation fails and returns the

following message:

"OAuth flow type X is not currently supported".

Chapter 1. Developing with the QRadar app framework

Authorization Manager. The record is identied by the App Name and App ID and includes the assigned

1. Click Main Menu > Admin tab.

2. Click the App Authorization Manager app icon to open the app.

3. To change assigned users for the OAuth authorization token, click Edit, and then select any users that

are available in the list. For example, if you don't want to use the Admin user and another user is

available in the list, you can change to a user with the requested capabilities that are dened in the

app manifest le.

Any users that appear in the list have the capability that the app requires to run.

Figure 5. OAuth bearer token app

The following example shows how an app that is a background service gets and uses the bearer token for

authorization to make QRadar REST API calls:

1. The manifest.json le includes an authentication entry to identify and congure the app as an

OAuth app, and instructs the Flask web server not to load.

46

 IBM QRadar : QRadar Application Framework Guide

Chapter 1. Developing with the QRadar app framework

app's src_deps/pip directory.

48

 IBM QRadar : QRadar Application Framework Guide

Note: The PyCrypto libraries in your app are subject to US export classication laws. If the app that you

develop is used outside of the US, you must ensure that you have an Export Control Classication Number

(ECCN) to comply with United States Department of Commerce regulations.

Multitenancy support for apps

QRadar V7.4.0 and later includes support for multi-tenanted apps. A number of out of the box apps, such

as Pulse, Assistant, and Log source manager, can now be used in a multitenant environment.

App developers are able to mark that their app is tested and works in a multi-tenanted environment. You

can support multitenancy in your app in two ways:

1. The app is tested and works with multitenancy, but it is not multitenancy aware. When a user installs

the app, they are presented with the option to create a default instance. Users can select this option if

they only want a single instance of the app, or the app does not need to support multitenancy. If a user

This type of app is also benecial if the app is used only by administrators.

single_instance_only

If the multitenancy_safe key is not set to true, then QRadar assumes that it cannot trust the app to

run in a multitenant environment. This key indicates that only one instance of the app runs, and that a

limited set of users can access it. This setting ensures that users who are in a tenant can't access other

tenants' data.

If the key is not set to true, users can create multiple instances of the app. Set this key to true if the app

Associating instances with security proles instead of tenants gives users more control over which users

can access tenant data. A tenant is expected to have one or more security proles associated with it to

dene what data different users can see.

Chapter 1. Developing with the QRadar app framework

Tip: If your app uses an API key to autonomously access QRadar APIs, set up your application to request

authentication through its manifest. You can then dene the exact access capabilities that are required,

and that key is delivered to your app securely as needed. For more information on app authentication, see

multitenanted apps.

Creating an extension from your app

After you deploy and test your app, you must export it as an extension to deploy it in a production

The IBM QRadar GUI Application Framework SDK deploy command is intended for use only in test

environments. To create an extension that you can use in a production environment, you must use the

QRadar Content Management Tool to export your application as an extension.

1. Use the QRadar GUI Application Framework SDK to package and deploy your application to

your QRadar Console test environment. Make sure that you obtain the application ID for your

app from Application Creation Task state output that is returned when you issue the

2. Use SSH to log in to QRadar Console where your app is running as root user.

1023



The extension is created as a .zip le in the /opt/qradar/bin folder. The le name has the

installed_application-ContentExport-YYYYMMDDhhmmss.zip

Here is an example:

installed_application-ContentExport-20160911141607.zip

Download the .zip le from the /opt/qradar/bin folder on your QRadar Console. You can then use

QRadar Extensions Management on the Admin tab to install your extension on your QRadar Console.

For more information about exporting apps and content in extensions, and Extensions Management, see

50

 IBM QRadar : QRadar Application Framework Guide

2. To get a list of the content types and search parameters, type the following command:

/opt/qradar/bin/contentManagement.pl -h export

In the following example, you search for apps that are represented by the content type ID of 100, and

the regex .*, which matches everything.

/opt/qradar/bin/contentManagement.pl --action search -c 100 -r .*

You must specify the content type (-c) and a search regex (-r).

In the following example, you search for the custom content type "dashboard" that is represented by

the content type ID of 4, and the regex .*, which matches everything for dashboards content.

/opt/qradar/bin/contentManagement.pl --action search -c 4 -r .*

Use regex to narrow your search, for example, you use the following search to nd dashboards content

<content_type_ID_or_string>,<Content_or_app_ID>

Use the following rules to create the package text le:

• Use a separate line for each content type.

• Make sure that the rst value that you enter on a line is the content type.

• Make sure that the value that follows the content type is the ID of the app or the content.

• Use commas to separate values.

Here's an example of packaging an app that has a content type of 100 and a dashboard that has a

content type of 4.

4,22

100,1051

Chapter 1. Developing with the QRadar app framework

installed_application,1001

dashboard,10

4. Save the text le as <my_package>.txt

5. Type the following command to assemble and export your content in an extension le:



The extension is created as a .zip le in the /opt/qradar/bin folder. The le name has the

following format:

<file_name>-ContentExport-YYYYMMDDhhmmss.zip

Download the compressed (.zip) le from the /opt/qradar/bin folder on your QRadar Console. You

can then use QRadar Extensions Management on the Admin tab to install your extension on your QRadar

All apps and content extensions are hosted on the IBM X-Force Exchange portal (https://

exchange.xforce.ibmcloud.com/), where you can lter by content type such as custom AQL function or

custom property. You can use content extensions can be used in conjunction with apps.

The following table describes the types of content extension that you can deploy in QRadar.

Content extension type

Enhancement

type

Description

Dashboard Data An associated set of dashboard items, which you view

on the Dashboard tab in QRadar. Dashboard items

to display or group data by). By saving the criteria of

commonly run searches, you don't need to dene them

repeatedly. Saved searches are required for reports and

dashboards.

FGroup Data A group of similar items by type, such as a group of

log sources, a group of rules, a group of searches,

or a group of report templates. FGroups are used as

organizational units.

52 IBM QRadar : QRadar Application Framework Guide

type

an inbound event or flow. Can be based on a regular

expression that extracts a subset of a particular event

or flow payload as a textual property. They can be based

on calculations, and perform an arithmetic operation on

existing numeric properties of the event or flow.

mainframe, workstation, rewall, router, application, or

database. Any events that enter QRadar and originate

from that source are attributed to the log source. Log

sources contain the conguration information that is

needed to receive inbound events, or to pull event data

from the event source. Log sources contain information

Chapter 1. Developing with the QRadar app framework53

d