QRadar Public API Series, Part 1
Use the QRadar REST API
Joshua Hatfield, Associate Security Consultant at Prolifics
[email protected]
Nilesh Patel, Security Solution Architect at Prolifics
[email protected]
Document version 1.0 June 6, 2014
Abstract:
In this white paper, you use the RESTful API to directly interface with the QRadar Console for the purpose of ariel
database queries, session authorization, reference data management, and Vulnerability Manager functionality.
About this series:
The QRadar Public API Series explores how to get the most out of QRadar's public API sets from a variety of
programming environments. The series consists of three parts as follows:
•
•
•
Part 1: Use the REST API - Explores the structure of the REST APIs and describes the parameters of the key
APIs.
Part 2: How to use QRadar Public APIs with Java - Show how to invoke the QRadar APIs from Java run time
environments.
Part 3: How to use QRadar Public APIs by leveraging IBM Security Directory Integrator - Describes how to
invoke the QRadar APIs from within a Directory Integrator assembly line.
Visit the series home page at https://ibm.biz/callqradar
• Table of Contents
1Introduction .............................................................................................................................................3
2QRadar REST API ..................................................................................................................................3
2.1QRadar..............................................................................................................................................5
2.1.1/ariel..........................................................................................................................................6
2.1.2/referencedata..........................................................................................................................12
2.2QRadar Vulnerability Manager......................................................................................................30
2.2.1/qvm........................................................................................................................................30
2.2.2/scanner...................................................................................................................................35
3Making REST calls with a Web browser...............................................................................................38
3.1Before you begin............................................................................................................................38
3.2About this task................................................................................................................................43
4Resources ..............................................................................................................................................50
5About the authors...................................................................................................................................51
• Table of Figures
Figure 1: QRadar Console........................................................................................................................38
Figure 2: Highlighted Admin tab in QRadar Console..............................................................................39
Figure 3: Highlighted User Roles option in the Admin tab.....................................................................39
Figure 4: Create New Role.......................................................................................................................40
Figure 5: Create new Role options...........................................................................................................41
Figure 6: Deploy changes........................................................................................................................41
Figure 7: Authorized Services in Admin tab............................................................................................42
Figure 8: Add Authorized Service option................................................................................................42
Figure 9: Add Authorized Service options...............................................................................................42
Figure 10: Authorized Service Token.......................................................................................................43
Figure 11: Chrome apps URL..................................................................................................................43
Figure 12: Installed Google chrome apps................................................................................................44
Figure 13: Postman REST Client App.....................................................................................................45
Figure 14: QRadar Public API URL........................................................................................................46
Figure 15: REST API Headers.................................................................................................................46
Figure 16: REST API URL Parameters....................................................................................................47
Figure 17: REST API Method..................................................................................................................48
Figure 18: Send REST API Request........................................................................................................49
Figure 19: REST API Response...............................................................................................................50
• Index of Tables
Table 1: Ariel database APIs....................................................................................................................11
Table 2: Reference Sets APIs...................................................................................................................17
Table 3: Reference Maps APIs.................................................................................................................21
Table 4: Reference Map of Sets APIs......................................................................................................25
Table 5: Reference Table APIs.................................................................................................................29
Table 6: QVM(/qvm) APIs.......................................................................................................................34
Table 7: QVM Scanner(/scanner) APIs....................................................................................................37
1 Introduction
This document is an in-depth explanation of the REST API for QRadar with all of the API’s
capabilities. The REST API was added to QRadar in release 7.2 MR1 to allow developers an easy way
to make HTTP Secure queries to the QRadar Console. This API enables access to functionality
previously only available in the QRadar web console. The REST API allows QRadar administrators to
input information and receive properly formatted URLS as well as header, error, and schema
information. Like other REST APIs, it uses the standard HTTP GET, PUT, POST and DELETE
methods.
2 QRadar REST API
In QRadar 7.2 MR1, a framework was added to help make HTTPS queries easy for API developers
through the implementation of a user interface for the API. This API framework allows customers to
input information, click test, and receive properly formatted HTTPS URL, expected responses, header
information, error information, schema information, and more for the input format for your put, get,
post, or delete commands. This framework is developed as a J2EE application named as restapi and
hosted on tomcat. The restapi application is developed based on the resources and methods. The
resources are basically the target entities such as reference data, vulnerability data etc. These resources
in the restapi are defined using request type, path and version. The request types are the HTTP
operations like GET, POST, PUT, DELETE etc and path is the relative path of the URL. The methods
are the underline java methods to perform requested operation given in the request type on the given
path.
The web.xml (located at /opt/tomcat/webapps/restapi/WEB-INF) defines deployment descriptor of the
restapi application. The web.xml also provide detail request handling, Servlets and web service URL
mapping.
The web.xml of QRadar 7.2 MR1 release looks like below :
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
<display-name>restapi</display-name>
<!-- BEGIN JDNI PROPERTIES -->
<env-entry>
<env-entry-name>WEBAPP_CONTEXT</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>restapi</env-entry-value>
</env-entry>
<!-- END JDNI PROPERTIES -->
<servlet>
<description></description>
<display-name>AutoDoc</display-name>
<servlet-name>AutoDoc</servlet-name>
<servlet-class>com.q1labs.restapi.servlet.autodoc.AutoDoc</servlet-class>
<!-- Start after APIDelegate -->
<load-on-startup>3</load-on-startup>
</servlet>
<servlet>
<description></description>
<display-name>APIDelegate</display-name>
<servlet-name>APIDelegate</servlet-name>
<servlet-class>com.q1labs.restapi.servlet.apidelegate.APIDelegate</servletclass>
<!-- Start after APILoginDelegate -->
<load-on-startup>2</load-on-startup>
</servlet>
<servlet>
<description></description>
<display-name>APILoginDelegate</display-name>
<servlet-name>APILoginDelegate</servlet-name>
<servlet-class>com.q1labs.restapi.servlet.auth.APILoginDelegate</servlet-class>
<!-- Start after FileServlet -->
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<description></description>
<display-name>FileServlet</display-name>
<servlet-name>FileServlet</servlet-name>
<servlet-class>com.q1labs.restapi.servlet.file.FileServlet</servlet-class>
<load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>AutoDoc</servlet-name>
<url-pattern>/doc/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>APILoginDelegate</servlet-name>
<url-pattern>/login/</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>APIDelegate</servlet-name>
<url-pattern>/api/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>FileServlet</servlet-name>
<url-pattern>/file/*</url-pattern>
</servlet-mapping>
<listener>
<listener-class>com.q1labs.restapi.servlet.QRadarServlet</listener-class>
</listener>
<!-- Define a role for logged in users -->
<security-role>
<description>A user who is logged into the system</description>
<role-name>AuthenticatedUser</role-name>
</security-role>
<!-- Allow our login page -->
<security-constraint>
<display-name>Security Exceptions</display-name>
<web-resource-collection>
<web-resource-name>Security Exceptions</web-resource-name>
<url-pattern>/login/</url-pattern>
<url-pattern>/login.jsp</url-pattern>
<url-pattern>/img/main_logo.gif</url-pattern>
</web-resource-collection>
</security-constraint>
<!-- Define a Security Constraint on this Application -->
<security-constraint>
<display-name>Entire Application</display-name>
<web-resource-collection>
<web-resource-name>Entire Application</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>AuthenticatedUser</role-name>
</auth-constraint>
</security-constraint>
<!-- Our login configuration will direct to our login servlet for additional
redirection -->
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/login/</form-login-page>
<form-error-page>/login/</form-error-page>
</form-login-config>
</login-config>
</web-app>
This web.xml clearly defines followings :
1) /restapi is the context root, so QRadar APIs will be accessed by https://<console ip>/restapi
2) APIDeletegate Servlet
APIDelegate Servlet is the main heart of the QRadar API framework. When the API request
comes in to APIDelegate Servlet, it first parse and then initializes all parameters and at last
stage based on the requested operation, it invoke underline QRadar methods to fulfill the API
request. All user requests to restapi/api will call APIDelegate Servlet.
3) AutoDoc Servlet
AutoDoc Servlet requests APIDelegate Servlet to build a documentation of the requested API.
All user requests to restapi/doc will call AutoDoc Servlet.
4) FileServlet Servlet
The FileServlet Servlet is to read contents of file recursively, it is based on relative
configuration path /opt/qradar/conf/api-server/restapi. All user requests to restapi/file will call
FileServlet Servlet.
5) All user requests to restapi/login will call APILoginDelegate Servlet.
The QRadar restapi application leverages HTTP commands such as GET, POST, PUT and DELETE
over secure a connection i.e. https.
The QRadar REST APIs provided by framework are broadly categorized in to the following two
sections:
1) QRadar
2) QRadar Vulnerability Manager
2.1 QRadar
The QRadar Platform provides a /ariel, /auth, /help and /referencedata. These APIs are available on all
QRadar products. As name implies /ariel API provides management of data stored in the ariel and it is
available from the QRadar 7.2 MR2 release onward, /auth API provides authentication scheme to
QRadar APIs, /help API provides help on each of the QRadar APIs and /referencedata API provides
management of QRadar reference set and data elements.
2.1.1 /ariel
Refer to Table 1: Ariel database APIs for QRadar Ariel database APIs.
Name
/databases
Operation
GET
/databases/ GET
{dbname}
/searches
GET
Description
Request
Parameters
Response
Retrieve a list
of the Ariel
databases that
are available.
The names of
the Ariel
databases that
are available.
Retrieve the
columns that
are defined for
the specified
Ariel database.
A list of
dbname - Required - The name of
columns
the Ariel database to retrieve the
defined for the columns for.
specified
database.
Multiple
properties of
each column
are returned.
For example,
the column ID,
or an indication
of if the
column is
indexable.
Retrieve the list A list of the
of Ariel
search IDs.
searches. This
includes
searchIDs for
completed and
NA
NA
Response
Success
Failure
HTTP Response
200 - The
database list was
retrieved.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to retrieve
the list of Ariel
databases.
HTTP Response HTTP Response 404,
200 - The
Unique code 1002 - The
database columns database does not exist.
were retrieved.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to retrieve
the database columns.
HTTP Response HTTP Response 500,
200 - The search Unique code 1020 - An
list was retrieved. error occurred while
attempting to retrieve
the list of searches.
Name
Operation
Description
Request
Parameters
Response
Response
Success
Failure
active searches.
POST
Creates a new
Ariel search as
specified by the
Ariel Query
Language
(AQL) query
expression.
Information
about the
specified
search,
including the
searchID.
queryExpression - Required - The HTTP Response
AQL query to execute.
201 - A new Ariel
search was
queryLanguageVersion successfully
Optional - The version of the AQL
created.
expression.
searchID - Optional - A searchID
value to be used for the new search
instead of a system generated
searchID.
startTime - Optional - The
beginning of the query time
interval, in milliseconds
endTime - Optional - The end of
the query time interval, in
milliseconds
/searches/ GET
{searchID}
Retrieve status
information for
a search, based
on the searchID
parameter.
Information
about the
specified
search,
including
search status.
searchID - Required - The
identifier for an Ariel search.
HTTP Response 409,
Unique code 1004 - The
search could not be
created, the searchID
provided is already in
use.
HTTP Response 422,
Unique code 2000 - The
queryExpression
contains invalid AQL
syntax.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to create a
new search.
HTTP Response HTTP Response 404,
200 - The search Unique code 1002 - The
information was search does not exist.
retrieved.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
Name
Operation
Description
Request
Parameters
Response
Response
Success
Failure
valid.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to retrieve
the search information.
POST
Updates details Information
for an Ariel
about the
search.
specified
search that was
updated.
searchID - Required - The ID of
the search to update.
saveResults - Optional - The only
accepted value is 'true'. If this
value is provided, the search
results will not be deleted by the
search expiration removal process.
status - Optional - The only
accepted value is 'CANCELED'. If
this value is provided the search
will be canceled.
HTTP Response HTTP Response 404,
200 - The search Unique code 1002 - The
was updated.
search does not exist.
HTTP Response 409,
Unique code 1002 - The
current status of the
search prevented the
search results from
being saved.
HTTP Response 422,
Unique code 1002 - A
request parameter is not
valid.
HTTP Response 500,
Unique code 1002 - An
error occurred while
attempting to update the
search.
DELETE Deletes an
Ariel search.
There is no
response body
for a
searchID - Required - The
searchID of the search to delete.
HTTP Response HTTP Response 404,
204 - The search unique code 1002 - The
was deleted.
search does not exist.
Name
Operation
Description
Request
Parameters
Response
Response
Success
successfully
deleted Ariel
Search.
Failure
HTTP Response 422,
unique code 1005 - A
request parameter is not
valid.
HTTP Response 500,
unique code 1020 - An
error occurred while
attempting to delete the
search.
/searches/ GET
{searchID}/
results
Retrieve the
results of the
Ariel search
that is
identified by
the searchID.
The search
results for the
specified
searchID.
searchID - Required - The ID of
the search whose results are to be
returned.
rangeStart - Optional - The first
row of the range of records to
return, starting from one (1).
rangeEnd - Optional - The last
row of the range of records to be
return.
HTTP Response HTTP Response 404,
200 - The search Unique code 1002 - The
results were
search does not exist.
retrieved.
HTTP Response 404,
Unique code 1003 Search results not found,
the search is still in
progress.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
valid.
HTTP Response 422,
Unique code 1007 Retrieving the search
results for this searchID
is unsupported.
HTTP Response 500,
Unique code 1020 - An
Name
Operation
Description
Request
Response
Parameters
Response
Success
Failure
error occurred while
attempting to retrieve
the search results.
Table 1: Ariel database APIs
2.1.2 /referencedata
The /referencedata APIs are categorized based on the QRadar Reference Set and Data elements.
•
Reference Sets
Refer to Table 2: Reference Sets APIs for QRadar Reference Sets API.
•
Reference Maps
Refer to Table 3: Reference Maps APIs for QRadar Reference Maps API
•
Reference Map Of Sets
Refer to Table 4: Reference Map of Sets APIs for QRadar Reference Map of Sets API.
•
Reference Table
Refer to Table 5: Reference Table APIs for QRadar Reference Table API
Name
/sets
Operation
Description
Request
Parameters
Response
Response
Success
Failure
GET
Retrieve a list A list of all of NA
of all
the reference
reference sets sets. This
returns
information
about the sets
but not the
contained data.
HTTP Response
200 - The
reference set list
has been retrieved
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve all
of the reference sets.
POST
Create a new
reference set
HTTP Response
201 – A new
reference set was
successfully
created.
HTTP Response 409,
Unique Code 1004 The reference set could
not be created, the name
provided is already in
use.
Information
name - Required - The name of the
about the newly reference set being created
created
elementType - Required - The
reference set.
element type for the values
allowed in the reference set. The
allowed values are: ALN
(alphanumeric), ALNIC
(alphanumeric ignore case), IP (IP
address), NUM (numeric), PORT
(port number) or DATE. Note that
date values need to be represented
in milliseconds since the Unix
Epoch January 1st 1970.
maxElements - Required - The
maximum number of elements the
reference set can contain
timeoutType - Optional - The
allowed values are
"FIRST_SEEN", "LAST_SEEN"
and "UNKNOWN". The default
value is "UNKNOWN". This
HTTP Response 422,
Unique Code 1005 – A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 – An
error occurred while
attempting to create the
reference set
Name
Operation
Description
Request
Parameters
Response
Response
Success
Failure
indicates if the timeToLive interval
is based on when the data was first
seen or last seen.
timeToLive - Optional - The time
to live interval, for example: "1
month" or "5 minutes"
/set/{name} GET
POST
Retrieve the
reference set
identified by
name. If
provided,
limit specifies
the number of
records to
return starting
at record
specified by
offset. If not
specified, then
the first 20
records will be
returned.
The reference
set identified
by the name
specified in the
request. The
portion of the
set's data
returned is
dependent on
the limit and
offset specified
in the request.
Add or update Information
an element in about the
a reference set reference set
that had an
element added
or updated.
This returns
name - Required - The name of the HTTP Respone
reference set to retrieve
200 - The
reference set has
limit - Optional - The number of
been retrieved
records to return. The default value
is 20.
offset - Optional - The offset
value. This indicates to retrieve
values starting from the offset
value rather than from the
beginning of the reference set. The
default value is 0.
name - Required - The name of the HTTP Response
reference set to add or update an
200 - The
element in
reference set has
had an element
value - Required - The value to
added or updated
add or update in the reference set.
Note: Date values must be
HTTP Response 404,
Unique Code 1002 –
The reference set does
not exist.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 – An
error occured while
attempting to retrieve
the reference set
HTTP Response 404,
Unique Code 1002 The reference set does
not exist
HTTP Response 422,
Unique Code 1005 - A
Name
Operation
Description
Request
Parameters
Response
information
about the
reference set
but not the
contained data.
Response
Success
Failure
represented in milliseconds since
the Unix Epoch January 1st 1970.
request parameter is not
valid
source - Optional - An indication
of where the data originated. The
default value is 'reference data api'
HTTP Response 422,
Unique Code 1006 The reference set is full
and can not have any
more values added.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to add or
update an element in the
reference set
DELETE Remove a
reference set
or purge its
contents
If the reference
set was
removed
nothing is
returned,
otherwise
information
about the
reference set
that had its
contents purged
is returned.
name - Required - The name of the HTTP Response
set to remove or purge
200 - The
reference set has
purgeOnly - Optional - The
had its contents
allowed values are "false" or
purged
"true". The default value is false.
This indicates if the reference set HTTP Response
should have its contents purged
204 - The
(true), keeping the reference set
reference set has
structure. If the value is "false" or been removed
not specified the reference set will
be removed completely.
HTTP Response 404,
Unique Code 1002 The reference set does
not exist
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove or
purge values from the
reference set
Name
/sets/
{name}/
{value}
Operation
Description
Request
DELETE Remove a
value from a
reference set
Response
Information
about the
reference set
that had an
value removed.
This returns
information
about the
reference set
but not the
contained data.
Parameters
Response
Success
name - Required - The name of the HTTP Response
reference set to remove a value
200 - The
from
reference set that
had a value
value - Required - The value to
removed
remove from the reference set.
Note: Date values must be
represented in milliseconds since
the Unix Epoch January 1st 1970.
Failure
HTTP Response 404,
Unique Code 1002 The reference set does
not exist
HTTP Response 404,
Unique Code 1003 The record does not
exist in the reference set
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove the
value from the reference
set.
/
POST
sets/bulkLo
ad/{name}
Add or update Information
data in a
about the
reference set reference set
that had data
added or
updated. This
returns
information
about the
reference set
but not the
name - Required - The name of set HTTP Response
to add or update data in
200 - The
reference set has
data - Required - The JSON
had data added or
formated data to add or update in
updated
the reference set
HTTP Response 400,
Unique Code 1001 - An
error occurred parsing
the JSON formatted
message body
HTTP Response 404,
Unique Code 1002 The reference set does
not exist
HTTP Response 422,
Name
Operation
Description
Request
Response
contained data.
Parameters
Response
Success
Failure
Unique Code 1005 - A
request parameter is not
valid
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to add or
update data in the
reference set
Table 2: Reference Sets APIs
Name
/maps
Operation
Description
Request
Parameters
Response
GET
Retrieve a list
of all
reference
maps.
A list of all of NA
the reference
maps. This
returns
information
about the maps
but not the
contained data.
POST
Create a new Information
name - Required - The name of the
reference map about the newly reference map to create
created
keyLabel - Optional - The label to
reference map.
describe the keys
valueLabel - Optional - The label
to describe the data values
elementType - Required - The
element type for the values
allowed in the reference map. The
allowed values are: ALN
(alphanumeric), ALNIC
(alphanumeric ignore case), IP (IP
address), NUM (numeric), PORT
(port number) or DATE. Note that
date values need to be represented
in milliseconds since the Unix
Epoch January 1st 1970.
timeoutType - Optional - The
allowed values are
"FIRST_SEEN", "LAST_SEEN"
Response
Success
Failure
HTTP Response
200 - The
reference map list
has been
retrieved.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve all
of the reference maps.
HTTP Response
201 - A new
reference map
was successfully
created
HTTP Response 409,
Unique Code 1004 The reference map could
not be created, the name
provided is already in
use. Please change the
name and try again.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to create the
reference map.
and "UNKNOWN". The default
value is "UNKNOWN". This
indicates if the timeToLive interval
is based on when the data was first
seen or last seen.
timeToLive - Optional - The time
to live interval, for example: "1
month" or "5 minutes"
/maps/
{name}
GET
POST
Retrieve the
reference map
identified by
name. If
provided,
limit specifies
the number of
records to
return starting
at record
specified by
offset. If not
specified, then
the first 20
records will be
returned.
The reference
map identified
by the name
specified in the
request. The
portion of the
reference map's
data returned is
dependent on
the limit and
offset specified
in the request.
name - Required - The name of the HTTP Response
reference map to retrieve
200 - The
reference map has
limit - Optional - The number of
been retrieved
records to return. The default value
is 20.
Add or update
an element in
a reference
map.
Information
about the
reference map
that had an
element added
or updated.
This returns
information
about reference
name - Required - The name of the HTTP Response
reference map to add or update an 200 - The
element in.
reference map has
had an element
key - Required - The key who's
added or updated.
value we want to add or update.
offset - Optional - The offset
value. This indicates to retrieve
values starting from the offset
value rather than from the
beginning of the reference map.
The default value is 0.
value - Required - The value to
add or update in the reference map.
Note: Date values must be
HTTP Response 404,
Unique Code 1002 The reference map does
not exist
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve
the reference map
HTTP Response 404,
Unique Code 1002 The reference map does
not exist.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
map but not the represented in milliseconds since
contained data. the Unix Epoch January 1st 1970.
source - Optional - An indication
of where the data originated. The
default value is 'reference data api'.
DELETE Remove a
reference map
or purge its
contents.
/maps/
{name}/
{key}
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to add or
update data in the
reference map.
If the reference
map was
removed
nothing is
returned,
otherwise
information
about the
reference map
that had its
contents purged
is returned.
name - Required - The name of the HTTP Response
reference map to remove or purge 200 - The
reference map has
purgeOnly - Optional - The
had its contents
allowed values are "false" or
purged.
"true". The default value is false.
This indicates if the reference map HTTP Response
should have its contents purged
204 - The
(true), keeping the reference map reference map has
structure. If the value is "false" or been removed.
not specified the reference map
will be removed completely.
HTTP Response 404,
Unique Code 1002 The reference map does
not exist.
DELETE Remove a
Information
value from a about the
reference map. reference map
that had an
element
removed. This
returns
information
about map but
not the
contained data.
name - Required - The name of the HTTP Response
reference map to remove a value
200 - The
from.
reference map has
had a value
key - Required - The key of the
removed.
value to remove.
HTTP Response 404,
Unique Code 1002 The reference map does
not exist.
value - Required - The value to
remove from the reference map.
Note: Date values must be
represented in milliseconds since
the Unix Epoch January 1st 1970.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove or
purge values from the
reference map.
HTTP Response 404,
Unique Code 1003 The record does not
exist in the reference
map.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove the
value from the reference
map.
Table 3: Reference Maps APIs
Name
Operations
/mapOfSets GET
POST
Description
Request
Retrieve a list
of all
reference map
of sets.
Parameters
Response
A list of all of
the reference
map of sets.
This returns
information
about the map
of sets but not
the contained
data.
Create a new Information
reference map about the newly
of sets.
created
reference map
of sets.
Response
Success
NA
HTTP Response
200 - The
reference map of
sets list has been
retrieved.
name - Required - The name of the HTTP Response
reference map of sets to create
201 - A new
reference map of
elementType - Required - The
sets was
element type for the values
successfully
allowed in the reference map of
created.
sets. The allowed values are: ALN
(alphanumeric), ALNIC
(alphanumeric ignore case), IP (IP
address), NUM (numeric), PORT
(port number) or DATE. Note that
date values need to be represented
in milliseconds since the Unix
Epoch January 1st 1970.
keyLabel - Optional - The label to
describe the keys
valueLabel - Optional - The label
to describe the data values
timeoutType - Optional - The
allowed values are
Failure
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve all
of the reference map of
sets.
HTTP Response 409,
Unique Code 1004 The reference map of
sets could not be
created, the name
provided is already in
use.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to create the
reference map of sets.
"FIRST_SEEN", "LAST_SEEN"
and "UNKNOWN". The default
value is "UNKNOWN". This
indicates if the timeToLive interval
is based on when the data was first
seen or last seen.
TimeToLive - Optional - The time
to live interval, for example: "1
month" or "5 minutes".
/
GET
mapOfSets/
{name}
POST
Return the
reference map
of sets
identified by
name. If
provided, limit
specifies the
number of
records to
return starting
at record
specified by
offset. If not
specified, then
the first 20
records will be
returned.
The reference
map of sets
identified by
the name
specified in the
request. The
portion of the
reference map
of sets' data
returned is
dependent on
the limit and
offset specified
in the request.
name - Required - The name of the HTTP Response
reference map of sets to retrieve
200 - The
reference map of
limit - Optional - The number of
sets has been
records to return. The default value
retrieved.
is 20.
Add or update
an element in
a reference
map of sets.
Information
about the
reference map
of sets that has
had an element
added or
updated. This
name - Required - The name of the HTTP Response
reference map of sets to add or
200 - The
update an element in.
reference map of
sets has had an
key - Required - They key who's
element added or
set we want to add or update.
updated.
value - Required - The value to
offset - Optional - The offset value.
This indicates to retrieve values
starting from the offset value rather
than from the beginning of the
reference map of sets. The default
value is 0.
HTTP Response 404,
Unique Code 1002 The reference map of
sets does not exist.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve
the reference map of
sets.
HTTP Response 404,
Unique Code 1002 The reference map of
sets does not exist.
HTTP Response 422,
Unique Code 1005 - A
DELETE Remove a map
of sets or
purge its
contents.
/
DELETE Remove a
mapOfSets/
value from a
{name}/
reference map
{key}
of sets.
returns
information
about the
reference map
of sets but not
the contained
data.
add or update in the reference map
of sets. Note: Date values must be
represented in milliseconds since
the Unix Epoch January 1st 1970.
If the reference
map of sets was
removed
nothing is
returned,
otherwise
information
about the
reference map
of sets that had
its contents
purged is
returned.
name - Required - The name of the HTTP Response
reference map of sets to remove or 200 - The
purge.
reference map has
had its contents
purgeOnly - Optional - The
purged.
allowed values are "false" or
"true". The default value is false.
HTTP Response
This indicates if the reference map 204 - The
of sets should have its contents
reference map has
purged (true), keeping the
been removed.
reference map of sets structure. If
the value is "false" or not specified
the reference map of sets will be
removed completely.
HTTP Response 404,
Unique code 1002 - The
reference map of sets
does not exist.
Information
about the
reference map
of sets that had
a value
removed. This
returns
information
about the
reference map
name - Required - The name of the HTTP Response
reference map of sets to remove a 200 - The
value from.
reference map of
sets has had a
key - Required - The key of the
value removed.
value to remove.
HTTP Response 404,
Unique Code 1002 The reference map of
sets does not exist.
source - Optional - This indicates
where the data originated. The
default value is 'reference data api'.
value - Required - The value to
remove from the reference map of
sets. Note: Date values must be
represented in milliseconds since
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to add or
update data in the
reference map of sets.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to remove or
purge values from the
reference map of sets.
HTTP Response 404,
Unique Code 1003 The record does not
exist in the reference
map of sets.
of sets but not
the contained
data.
the Unix Epoch January 1st 1970.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove
the reference map of
sets value.
Table 4: Reference Map of Sets APIs
Name
/tables
Operations
Description
Request
Parameters
Response
Response
Success
Failure
GET
Retrieve a list
of all
reference
tables.
A list of all of NA
the reference
tables. This
returns
information
about the tables
but not the
contained data.
HTTP Response
200 - The
reference table list
has been
retrieved.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to retrieve all
of the reference tables.
POST
Create a new
reference
table.
Information
name - Required - The name of the
about the newly reference table to create.
created
elementType - Required - The
reference table.
default element type for the values
allowed in the reference table. This
is used when values are added or
updated in the reference table
who's inner key was not defined in
the keyNameTypes parameter. The
allowed values are: ALN
(alphanumeric), ALNIC
(alphanumeric ignore case), IP (IP
address), NUM (numeric), PORT
(port number) or DATE. Note that
date values need to be represented
in milliseconds since the Unix
Epoch January 1st 1970.
HTTP Response
201 - A new
reference table
was successfully
created.
HTTP Response 409,
Unique Code 1004 The reference table
could not be created, the
name provided is
already in use.
outerKeyLabel - Optional - The
label to describe the outer keys.
timeoutType - Optional - The
allowed values are
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to create the
reference table.
"FIRST_SEEN", "LAST_SEEN"
and "UNKNOWN". The default
value is "UNKNOWN". This
indicates if the timeToLive interval
is based on when the data was first
seen or last seen."
timeToLive - Optional - The time
to live interval, for example: "1
month" or "5 minutes".
keyNameTypes - Optional - A
JSON formatted string. This array
creates the inner key names and
corresponding value types for the
table
/tables/
{name}
GET
POST
Return the
reference table
identified by
name. If
provided,
limit specifies
the number of
records to
return starting
at record
specified by
offset. If not
specified, then
the first 20
records will be
returned.
The reference
table identified
by the name
specified in the
request. The
portion of the
reference
table's data
returned is
dependent on
the limit and
offset specified
in the request.
Add or update Information
an element in about the
name - Required - The name of the HTTP Response
reference table to retrieve.
200 - The
reference table
limit - Optional - The number of
has been
records to return. The default value
retrieved.
is 20.
offset - Optional - The offset value.
This indicates to retrieve values
starting from the offset value rather
than from the beginning of the
reference table. The default value
is 0.
name - Required - The name of the HTTP Response
reference table to add or update an 200 - The
HTTP Response 404,
Unique code 1002 - The
reference table does not
exist.
HTTP Response 422,
Unique code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique code 1020 - An
error occurred while
attempting to retrieve
the reference table.
HTTP Response 404,
Unique Code 1002 -
a reference
table. The
value to be
added must be
of the
appropriate
type: either the
type that
corresponds to
the innerKey
predefined for
the reference
table, or the
default
elementType
of the
reference
table.
reference table
that had an
element added
or updated.
This returns
information
about the
reference table
but not the
contained data.
DELETE Remove a
reference table
or purge its
contents.
If the table was
removed
nothing is
returned,
otherwise
information
about the
reference table
that had its
contents purged
is returned.
element in.
outerKey - Required - The outer
key for the element to add or
update.
reference table
has had an
element added or
updated.
innerKey - Required - The inner
key for the element to add or
update.
value - Required - The value to
add or update in the reference
table. Note: Date values must be
represented in milliseconds since
the Unix Epoch January 1st 1970.
The reference table does
not exist.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to add or
update data in the
reference table.
source - Optional - An indication
of where the data originated. The
default value is 'reference data api'.
name - Required - The name of the HTTP Response
reference table to remove or purge 200 - The
reference table
purgeOnly - Optional - The
has had its
allowed values are "false" or
contents purged.
"true". The default value is false.
This indicates if the reference table HTTP Response
should have its contents purged
204 - The
(true), keeping the reference table reference table
structure. If the value is "false" or has been removed.
not specified the reference table
will be removed completely.
HTTP Response 404,
Unique Code 1002 The reference table does
not exist.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove or
purge values from the
reference table.
/tables/
DELETE Remove a
{name}/
value from a
{outerkey}/
reference
{innerkey}
table.
Information
about the
reference table
that had an
element
removed. This
returns
information
about table but
not the
contained data.
name - Required - The name of the HTTP Response
reference table to remove a value 200 - The
from.
reference table
had had a value
outerKey - Required - The outer
removed.
key of the value to remove.
innerKey - Required - The inner
key of the value to remove.
value - Required - The value to
remove from the reference table.
Note: Date values must be
represented in milliseconds since
the Unix Epoch January 1st 1970.
HTTP Response 404,
Unique Code 1002 The reference table does
not exist.
HTTP Response 404,
Unique Code 1003 The record does not
exist in the reference
table.
HTTP Response 422,
Unique Code 1005 - A
request parameter is not
valid.
HTTP Response 500,
Unique Code 1020 - An
error occurred while
attempting to remove
the reference table
value.
Table 5: Reference Table APIs
2.2 QRadar Vulnerability Manager
The QRadar Vulnerability Manager provides /qvm and /scanner. These APIs allow to query QRadar
Vulnerability Manager for data or put data in QVM to update remediation for an assigned vulnerability.
The /scanner API provides administrators a way to work with scan profiles through the API.
2.2.1 /qvm
Refer to Table 6: QVM(/qvm) APIs for /qvm APIs.
Name
Opera
tions
Description
Request
Parameters
Response
Response
Success
Failure
/assets
GET
List the assets with list of assets
discovered
data.
vulnerabilities
present in the asset
model. The
response will
contain all
available RESTful
resources.
savedSearchId - Id of saved
search
HTTP Response
200 - The request
to retrieve
savedSearchName - Saved search
vulnerabilities by
name
asset completed
successfully
filters - List of JSON objects for
application of bespoke query
search dataset filter. Format
[{"parameter":"","operator":"","val
ue":""}] e.g. [{"parameter":"IPv4
Address","operator":"Equals","val
ue":"10.100.85.111"}]
HTTP Response 420,
Unique code 9101 Invalid search
parameters, search
cannot be performed.
/filters
GET
Get a list of the
list of Filters.
allowable filters
that can be used or
applied against
the:
NA
HTTP Response 420,
Unique Code 9102 - An
error occurred while
executing the search.
HTTP Response
500 - The search
executed
successfully.
/qvm/assets
/qvm/vulns
/
qvm/vulninstances
/qvm/openservices
/qvm/networks
queries
/network
GET
List the networks List of network savedSearchId - Id of saved
present in the asset related data.
search.
HTTP Response HTTP Response 420,
200 - The request unique Code 9101 -
Name
Opera
tions
Description
Request
Parameters
Response
Response
Success
Failure
model with
vulnerabilities
present. The
response will
contain all
available RESTful
resources.
savedSearchName - Saved search to retrieve
Invalid search
name.
vulnerabilities by parameters, search
network
cannot be performed.
filters - List of JSON objects for
completed
application of bespoke query
successfully.
search dataset filter. Format
[{"parameter":"","operator":"","val
ue":""}] e.g. [{"parameter":"IPv4
Address","operator":"Equals","val
ue":"10.100.85.111"}]
/
GET
openservic
es
List the
List of open
openservices
services related
present in the asset data.
model with
vulnerabilities
present. The
response will
contain all
available RESTful
resources.
savedSearchId - Id of saved
search.
HTTP Response
200 - The request
to retrieve
savedSearchName - Saved search
vulnerabilities by
name.
open service
completed
filters - List of JSON objects for
successfully.
application of bespoke query
search dataset filter. Format
[{"parameter":"","operator":"","val
ue":""}] e.g. [{"parameter":"IPv4
Address","operator":"Equals","val
ue":"10.100.85.111"}]
HTTP Response 420,
unique code 9101 Invalid search
parameters, search
cannot be performed.
/
GET
savedsearc
hes
Get a list of saved
searchs that can be
used or applied
against the:
NA
HTTP Response 420,
Unique code 9103 - An
error occurred while
trying to retrieve the list
of saved searches.
/qvm/assets
List of saved
searches. Per
saved search:
id, name and
list fo filters
that make up
this saved
HTTP Response
200 - The request
to retrieve the list
of saved searches
completed
successfully.
Name
Opera
tions
Description
Request
/qvm/vulns
Parameters
Response
Response
Success
Failure
HTTP Response
200 - The request
to assign a ticket
completed
successfully.
HTTP Response 420,
unique code 9104 - An
error occurred while
trying to assign a ticket
due to invalid
arguments.
search.
/
qvm/vulninstances
/qvm/openservices
/qvm/networks
queries
/
POST Update the
success
ticket - The ticket number
tickets/assi
remediation ticket message if
gh
for the assigned
update succeed.
vulnerability.
/
GET
vulninstanc
es
List the
List of
Vulnerability
vulnerability
Instances present instance data.
in the asset model.
The response will
contain all
available RESTful
resources.
savedSearchId - Id of saved
search.
HTTP Response 420,
Unique code 9101 Invalid search
parameters, search
cannot be performed.
/vulns
List the
Vulnerabilities
savedSearchId - Id of saved
search.
HTTP Response HTTP Response 420,
200 - The request unique code 9101 -
GET
List of
vulnerability
HTTP Response
200 - The request
to retrieve
savedSearchName - Saved search
vulnerabilities by
name.
instance
completed
filters - List of JSON objects for
successfully.
application of bespoke query
search dataset filter. Format
[{"parameter":"","operator":"","val
ue":""}] e.g. [{"parameter":"IPv4
Address","operator":"Equals","val
ue":"10.100.85.111"}]
Name
Opera
tions
Description
Request
Response
present in the asset data.
model. The
response will
contain all
available RESTful
resources.
Table 6: QVM(/qvm) APIs
Parameters
Response
Success
savedSearchName - Saved search to retrieve
name.
vulnerabilities
completed
filters - List of JSON objects for
successfully.
application of bespoke query
search dataset filter. Format
[{"parameter":"","operator":"","val
ue":""}] e.g. [{"parameter":"IPv4
Address","operator":"Equals","val
ue":"10.100.85.111"}]
Failure
Invalid search
parameters, search
cannot be performed.
2.2.2 /scanner
Refer to Table 7: QVM Scanner(/scanner) APIs for QRadar Vulnerability Manager Scanner APIs.
Name
/profiles
Opera
tions
GET
Description
Request
Retrieves all of the
currently created
scan profiles. No
parameters are
required and the
following
information should
be retrieved for
each scan profile scanProfileId scanProfileName description scanType scannerName.
/
POST Initiates a request
profiles/cre
to create a new
ate
scanProfile. The
request takes one
parameter createScanRequest
, which is just a
POJO. To create
the scan, you will
need to build up a
JSON object that
contains the Scan
Profile name and
hosts to scan e.g.
{'name':'New Scan
Profile', 'ips':
Parameters
Response
Response
Success
Failure
The list of scan NA
profiles
currently
configured in
QVM.
HTTP Response
200 - The list of
scan profiles was
successfully
returned.
HTTP Response 500,
Unique code 1030 Occurs when an attempt
is made to list scan
profiles when certain
conditions are not met,
or when too many scan
requests have been
made.
An indicator of scanProfile - Required - The scan
whether the
profile in ScanRequest type.
scan has been
created
successfully or
not.
HTTP Response
200 - The scan
has been
successfully
created.
HTTP Response 419,
Unique code 9101 Occurs when a
parameter is missing or
invalid.
HTTP Response 500,
Unique code 1030 Occurs when an attempt
is made to create a scan
when certain conditions
are not met, or when too
many scan requests have
been made.
Name
Opera
tions
Description
Request
Parameters
Response
Response
Success
Failure
['10.100.85.135']}.
/
POST Initiates a request
profiles/sta
to start an already
rt
created
scanProfile. The
request takes one
parameter scanProfileId. To
get a list of
scanProfileIds,
simply get a list of
the current scan
profiles by
initiating a
'profiles' request
on the scanner
endpoint. The
scanProfileId will
be validated and an
appropriate
message returned.
Table 7: QVM Scanner(/scanner) APIs
An indicator of scanProfileId - Required - The
whether the
unique id of the scan profile we
scan has been want to start.
started
successfully or
not.
HTTP Response
200 - The scan
has been
successfully
started.
HTTP Response 403,
Unique code 1000 Occurs if the user does
not have permission to
start a scan, or the scan
is in progress.
HTTP Response 500,
Unique code 1030 Occurs when an attempt
is made to start a scan
when certain conditions
are not met, or when too
many scan requests have
been made.
3 Making REST calls with a Web browser
The QRadar Public API uses HTTP Basic authentication for transmitting the user ID and password
using Basic Base64 encoding via Authorization header. Upon successful authentication restapi returns
security token. Because each request is stateless, each subsequent calls to the REST API must include
either Authorization header or security token. The other way to get REST Client authenticated with
QRadar without using username and password is by using QRadar Authorized Services. QRadar 7.2
MR1 also introduced a new user role API – Reference data API and it must be enabled to an user to use
QRadar Reference data REST APIs. Similarly QRadar 7.2 MR2 introduced a new user role API – Ariel
and it must be enabled to an user to use QRadar Ariel REST APIs.
3.1 Before you begin
All REST APIs are protected and it requires authentication. To allow users (non-admin) accounts to
access the API, administrator(admin) must enable a user role for API from the Admin tab. After
administrator update non-admin users with the required permission, administrator need to deploy the
changes to enable access.
1. Access QRadar console using https://<console_ip>/console and login with admin user.
Figure 1: QRadar Console
2. Click Admin tab.
Figure 2: Highlighted Admin tab in QRadar Console
3. Click “User Roles” under “System Configuration” → “User Management”
Figure 3: Highlighted User Roles option in the Admin tab
4. Click “New” to create a new Role.
Figure 4: Create New Role
5. Provide “User Role name”, select “API” check-box and hit Save and then close window.
Figure 5: Create new Role options
Note : Vulnerability Management and Asset must be selected for QVM REST APIs.
6. Click “Deploy changes” to deploy changes.
Figure 6: Deploy changes
7. Under Admin tab, click “Authorized Services” to create security token for 'API-Role'.
Figure 7: Authorized Services in Admin tab
8. Click “Add Authorized Service”.
Figure 8: Add Authorized Service option
9. Provide Service Name, User Role, Expiry date and click Create Service.
Figure 9: Add Authorized Service options
10. Select newly added authorized service and take a note of token.
Figure 10: Authorized Service Token
3.2 About this task
The REST API uses several HTTP methods to perform various actions on REST resources. Using Web
browser REST client Any REST API call can be submitted. In this article we will be demonstrating
using open source and freely available Google Chrome's Postman-REST Client.
The Postman - REST Client for Google Chrome can be downloaded from here.
To access a REST API with a browser, complete the following steps:
1. Open Google Chrome.
2. Open “chrome://apps”
Figure 11: Chrome apps URL
3. Click “Postman – REST Client” app.
Figure 12: Installed Google chrome apps
4. Postman REST Client App
Figure 13: Postman REST Client App
5. Provide “Request URL”. Here in this example, we will be retrieving reference sets.
Figure 14: QRadar Public API URL
Note: Request URL will be different based on QRadar server and the API resource
6. Click “Headers” and provide version, Accept, Allow-Experimental, Allow-Provisional and SEC
headers as shown in Figure 15: REST API Headers.
Figure 15: REST API Headers
Note : SEC must be set to a value which was generated as an authorized token for Reference
Data APIs.
7. Click “URL params” to provide parameters if required. Since
Figure 16: REST API URL Parameters
8. Select “GET” as a HTTP Method from the drop-down list.
Figure 17: REST API Method
9. Click Send to send a request.
Figure 18: Send REST API Request
10. Review response of the request.
Figure 19: REST API Response
4 Resources
Visit the QRadar on developersWorks community for QRadar Security Intelligence Platform.
Visit the security on developerWorks blog for announcements of new security articles, how-to guides,
and demonstration videos.
Visit the IBM developerWorks security zone for more articles about security topics.
Sign up for the developerWorks security newsletter and other topical newsletters from developerWorks.
Follow @dwSecurity on Twitter.
5 About the authors
Joshua Hatfield is a Security Engineer with over four years of information technology experience. He
specializes in Security Information and Event Management (SIEM) as well as Identity and Access
Management (IAM) and has worked with IBM Security products for more than a year. Alongside
Nilesh Patel he has developed Prolifics’ “Ready for IBM Security Intelligence” Identity Intelligence
solution, a marriage of QRadar and IAM that leverages Reference Data Collections to track identity
information across multiple sources.
Nilesh Patel, Security Solution Architect at Prolifics is a preeminent identity and access management
and security intelligence expert with 9 years’ experience in information technology. He has extensive
experience in the design, customization, installation, configuration, and implementation of IBM
Security solutions. Nilesh has published many technical papers and has customized integration modules
for identity and access management and security intelligence products. He has delivered many
technical webcasts to educate others on new features and on the integration of IBM Security products.
Nilesh is IBM accredited Master Author. Prior to Prolifics, Nilesh worked with IBM as Senior Identity
and Access Management and Security Intelligence Professional.