IBM Support

QRadar: Overview of making queries to the QRadar API

How To


Summary

API requests can be made to various endpoints within QRadar to pull and/or update data. This can be done within the Interactive API in the UI of QRadar, or from the command line on the Console or Managed Host of QRadar.

Endpoints hold different types of data for QRadar, including Reference Sets, Event and Flow Data, Log Sources, Assets, Rules, and Offenses, among other things. Customers can make these queries one at a time as needed, or incorporate them into scripts that gather information or do other functions.

IBM QRadar support is not responsible for helping create queries or scripts for customers. It is not officially supported and customers must use supplied QRadar documentation to build and test queries themselves. Any support questions can be posted to the QRadar Forums.

In the case of unexpected errors for queries that should be working, a best-effort can be applied in helping to find the cause. This does not include network issues if running the queries from a third-party system into QRadar.

Steps

Performing a Query

You must include authentication credentials in each query.  Each query is basically an HTTP GET or PUT (or sometimes DELETE) request done by using “curl”.

The basic method uses username/password by using the HTTP request to the API.  Only queries to the Documentation Page of the API can be pulled this way.

Every other query to an endpoint requires an Authorized Services token, which you specify in the SEC header of the HTTP request.

A version of the API can be specified whether wanted, but if one is not included, the latest version is queried.  Newer versions of the API can include access to endpoints that older versions do not have.  Refer to the API documentation linked to this technote to see all endpoints.

In the curl request, you specify the method you want to use with the -X flag (typically – X GET), followed by a header flag -H that specifies the auth token.  

Some POST queries require data to be sent to an endpoint.  In those instances, a -d flag with the payload in quotations after it would be entered.  

The -k option can be used to avoid the use of certificates when connecting to the API as well.  The connection is considered insecure, but if it is being made on the QRadar system, it is OK.

So a basic GET request would be formatted like so:
url -X GET -H "SEC: <auth_token>" -H "Accept: application/json” -k https://<console_ip>
 /restapi/api/<general_endpoint_category/<specific_endpoint>

A fully filled out example would look like:
url -X GET -H "SEC: ab123c4d-56ef-7g89-a1bcd234ef56" -H "Accept: application/json” -k
 https://10.10.100.10 /restapi/api/access/login_attempts
If 200 was returned, a typical HTTP response code would be returned, followed by the response body. This is a sample response of the query:
 
[
    {
        "attempt_method": "String <one of: LOGIN_PAGE, HTTP_BASIC>",
        "attempt_result": "String <one of: SUCCESS, FAILURE>",
        "attempt_time": 42,
        "remote_ip": "String",
        "user_id": 42
    }
]
The list of HTTP Response codes can include the following:

200 – Successful query.
422 – A parameter/filter/field in the query was not valid (or does not exist).
404 – The specific data/id does not exist within the queried field.
409 – The data (when trying to use a POST query) exists at the endpoint.
500 – An error occurred while <endpoint data name> was being retrieved.
Other errors might be displayed, but can provide specific details as to what the error means.

Determining Query Structure

There are two ways to find out which filters and options an endpoint uses. 
The first is the official QRadar documentation at: QRadar API endpoint documentation and supported versions.

At the link to the official QRadar documentation, you can find the versions of the API per version of QRadar.  After clicking one of the links, you are taken to the GitHub link that lists all available endpoints. You can browse from there, or use Ctrl+F to search for certain keywords such as “reference” or “user” to find out what you might be looking for. After you click the link for the wanted endpoint, it explains what data you can pull, what filters to use, and what response codes you can expect to see.

The second way, and probably the easiest, is with the “Interactive API for Developers” in the QRadar GUI. You can access the menu after you logged in to the UI by using the navigation menu ( Navigation menu icon ), and the option is near the end of the list.

You have a new window where you can browse the endpoints in a tree structure.  It might be difficult to determine what the final endpoint is you want to access it. If you use the documentation as described, such as with a search, it informs you the path you would expand in the tree view to display the wanted endpoint.

After you clicked the final endpoint in the Interactive API, it shows you much the same data as the documentation, but now it will describe the fields and filters. You can test the query right there by simply entering the data in the filters.  It builds the curl command for you, which you can copy and paste out to be used in the CLI later on. There’s a Try it Out! button to run the command and see the results right in the browser window. This is a great function to use to see the results you can expect to see.  It confirms if the data you are looking for is provided.

Keep in mind that the UI is running the queries as Admin to itself, and the curl command it provides does NOT include a SEC token. If running the query later from the CLI, you still need to remove the -u admin portion and replace it with your auth token.

Level of Access Needed for the Authorized Service Token

When an Authorized Service Token is generated, you must give it a User Role and a Security Profile, much like what you would do when creating a user. If you require a token that pulls only data specific to one tenant, you can also assign a tenant to that token.
The easiest way to get access to the data on any endpoint is to simply give the Administrator User Role and an Administrator Security Profile that encompasses ALL Networks and Log Sources. However, if this user role is too wide open and you want to minimize risk, you have to create and assign roles and profiles that limit access depending on which endpoints you plan on accessing. 
Note: Several endpoints REQUIRE Admin level permissions to be queried, so it is not always possible to minimize access to every endpoint.
The documentation for the QRadar API on GitHub sometimes lists the permissions required, but many do not. Provided are some samples for some of the more common endpoints customers access.

Endpoint

User Role Access Neede

Security Profile Access Needed

/ariel/searches

“Log Activity” for event searches.

“Network Activity” for flow searches.

Search will run with any permission, but will only return data from the Networks/Log Sources/Domains assigned to the Security Profile.

/access/login_attempts

Admin (to view all user login attempts)

Administrator

/analytics/rules

“View Custom Rules” under the Offenses, Log Activity, and Network Activity groups.

Any

/asset_model/assets

Asset Category or QVM

Results are filtered using the caller's Security Profile. An asset is visible if the domain_id is in the list of allowable domains, AND the asset use at least one IP address that has a network_id in the list of allowable networks.

/config/access/authorized_services

Administrator

Administrator

/config/access/security_profiles

Administrator

Administrator

/config/access/users

Administrator

Administrator

/config/access/user_roles

Administrator

Administrator

/config/deployment/hosts

Administrator

Administrator

/config/deployment/license_pool

Administrator

Without “Admin” role, only the "over_allocated" fields are populated and the others are set to null

Administrator

/config/domain_management/domains Administrator Administrator
/config/event_sources/custom_properties/property_aql_expressions “User Defined Event Properties” under Log Activity.  If assigned to a tenant, cannot see CEPs of other tenants. Any

/config/event_sources/custom_properties/property_json_expressions

“User Defined Event Properties” under Log Activity.  If assigned to a tenant, cannot see CEPs of other tenants.

Any

/config/event_sources/custom_properties/regex_properties

“User Defined Event Properties” under Log Activity.  If assigned to a tenant, cannot see CEPs of other tenants.

Any

/config/event_sources/log_source_management/log_sources

Any

Results are restricted by what the Security Profile has access to.

/config/event_sources/log_source_management/log_source_groups

Log Activity category

Results are restricted by what the Security Profile has access to.

/config/extension_management/extensions

Administrator

Administrator

/config/network_hierarchy/networks

“Define Network Hierarchy” under Delegated Admin

Any network for domain_ids the Security Profile has access to.  Admin is preferred if updating the hierarchy with the API. No log sources required.

/reference_data/sets

Administrator

/siem/offenses

Just the “Offenses” option without any child permissions below it.

source_network:

The source_network is null if the user doesn't have access to the network.

destination_networks:

Displays only the network the user has access to. This could be an empty array if the user doesn't have access to any destination_networks.

source_count:

The source_count includes only sources the user has access to.

local_destination_count:

The local_destination_count includes only destinations the user has access to. This does not affect the remote_destination_count.

/system/about Administrator Administrator
/system/email_servers Administrator Administrator

/system/authorization/password_policies

Administrator

Administrator

Sample Endpoint Queries

Displayed are examples of our most common endpoints users query data from.
Ariel:

This one has a few parts.  You have to create a search in the Log Activity window of the UI first, then save it. Then, go into Search > Edit Search.  Find the saved search and select it. Then, choose the “Show AQL” button to display the AQL parameters.  You need to use this in the API query.

curl -s -X POST -H ‘SEC: <TOKEN>’ -k -d ‘query_expression=
<AQL_QUERY>’ https://<CONSOLE_IP>/restapi/api/ariel/searches

Copy the “cursor_id” value returned in the JSON response.

Check to see whether the search is completed. This might take a long time - rerun this command to keep checking the search status:

curl -s -X GET -H ‘SEC: <TOKEN>’ -k 
https://<CONSOLE_IP>/restapi/api/ariel/searches/<CURSOR_ID>

When the command shows the status is 'completed:true', download the event data in wanted format. The supported formats are ‘application/json’, ‘application/csv’, ‘application/xml’, and ‘text/table’. Change the ‘Accept’ header to the wanted format:

curl -X GET -H ‘SEC: <TOKEN>’ -H ‘Range: items=0-1’ -H ‘Accept: application/xml’ -k
https://<CONSOLE_IP>/restapi/api/ariel/searches/$CURSORID/results

After you downloaded ALL of the data from the cursor, you can delete the cursor to preserve space on /store/transient

curl -s -X DELETE -H ‘SEC: $SECTOKEN’ -k 
https://<CONSOLE_IP>/restapi/api/ariel/searches/<CURSOR_ID>
Reference Data:
 
curl -S -X GET -H 'SEC: b32366f0-a80c-48fd-8bf3-83ac2b5d310a' -H 'Range: items=0-49' 
-H 'Accept: application/json' 'https://10.10.100.10/api/reference_data/sets'
Offenses:
 
curl -S -X GET -H 'SEC: eeb900fc-5061-4fad-9f8c-91e7b5611b28' -H 'Range: items=0-49' 
-H 'Version: 19.0' -H 'Accept: application/json' 'https://10.10.100.10/api/siem/offenses'
Network Hierarchy:
 
curl -S -X GET -H 'SEC: b32366f0-a80c-48fd-8bf3-83ac2b5d310a'  -H 'Version: 19.0' 
-H 'Accept: application/json' 'https://10.10.100.10/api/config/network_hierarchy/networks'
Custom Rules:
 
curl -S -X GET -H 'SEC: b32366f0-a80c-48fd-8bf3-83ac2b5d310a' -H 'Range: items=0-49' 
-H 'Version: 19.0' -H 'Accept: application/json' 'https://10.10.100.10/api/analytics/rules'
Login Attempts:
 
curl -S -X GET -H 'SEC: f488ff9b-e282-473c-8203-e20d77e7cd87'  -H 'Range: items=0-49' 
-H 'Version: 19.0' -H 'Accept: application/json' 'https://10.10.100.10/api/access/login_attempts'
Results
API requests to various endpoints within QRadar are pulling and/or updating data.

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB24","label":"Security Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSBQAC","label":"IBM Security QRadar SIEM"},"ARM Category":[{"code":"a8m0z000000cwsyAAA","label":"Admin Tasks"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.4.3;7.5.0"}]

Document Information

Modified date:
16 February 2023

UID

ibm16954749