IBM QRadar SIEM helps your business by detecting anomalies, uncovering advanced threats, and removing false positives. It consolidates log events and network flow data from thousands of devices, endpoints, and applications distributed throughout a network.
This document provides information about the IBM QRadar connector, which facilitates automated interactions, with a QRadar server using FortiSOAR™ playbooks. Add the IBM QRadar connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically getting information about the offenses and details of the offenses from QRadar and also querying a QRadar device.
You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling offenses from IBM QRadar. For more information, see the Data Ingestion Support section.
Connector Version: 1.6.1
FortiSOAR™ Version Tested on: 7.4.1-3167
IBM QRadar Version Tested on: 7.4.1
Authored By: Fortinet
Certified: Yes
The following enhancements have been made to the IBM QRadar connector in version 1.6.1:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root
user to install connectors from an SSH session:
yum install cyops-connector-qradar
/api/ariel/*
and /api/siem/*
APIs, therefore ensure that you have the appropriate access as required by these APIs.For the procedure to configure a connector, click here.
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IBM QRadar connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
Parameter | Description |
---|---|
Address | Specify the IP address of the QRadar server from where the connector gets offenses information and to which you connect and perform automated operations. |
API Token | Specify the API token to access the QRadar server to which you connect and perform automated operations. |
API Version | Specify the version of the QRadar API to be used for performing automated operations. By default, this is set to 14.0. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified. By default, this is set to True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™:
Function | Description | Annotation and Category |
---|---|---|
Get Offenses from QRadar | Retrieves a list of offenses from the QRadar server based on the filter string that you have specified. | get_offenses Investigation |
Get Events Related to an Offense | Retrieves details of events associated with a QRadar offense, from the QRadar server, based on the QRadar offense ID that you have specified. | get_events Investigation |
Make an Ariel Query to QRadar | Executes an Ariel query on the QRadar server. QRadar uses the Ariel Query Language (AQL) to search for offenses or events based on query parameters. | run_query Investigation |
Get Offense Closing Reasons | Retrieves a list of closing reasons associated with all offenses from the QRadar server. | get_offense_closing_reasons Remediation |
Close Offense | Closes an offense on the QRadar server based on the offense ID that you have specified. | close_offense Remediation |
Get Source IP Addresses | Retrieves IP address details associated with source address IDs from the QRadar server, based on the source address IDs that you have specified | ip_details Investigation |
Get Destination IP Addresses | Retrieves IP address details associated with the destination address IDs from the QRadar server, based on the destination address IDs that you have specified | ip_details Investigation |
Invoke QRadar REST API | Invokes a function to Get or Post an API endpoint on the QRadar server. | api_call Miscellaneous |
Get Offense Types | Retrieves a list containing IDs of all the offense types from the QRadar server. | get_offense_type Investigation |
Manipulate Reference Set Content | Adds or deletes the content that you have specified from a reference set on QRadar you have specified. | handle_reference_set_value Investigation |
Get Offense Notes | Retrieves a list of notes associated with a specified offense in QRadar based on the offense ID you have specified. | get_notes Remediation |
Create Note | Creates a note for a specified offense in QRadar based on the offense ID you have specified. | add_notes Remediation |
Get Assets Properties | Retrieves a detailed list of available asset properties or specific available asset properties from QRadar based on input parameters specified. | get_assets_properties Investigation |
Get Assets | Retrieves a detailed list of all available assets or specific available assets from QRadar based on input parameters specified. | get_assets Investigation |
Update Asset | Updates the attributes of a specific asset on the QRadar server based on the asset ID and asset properties you have specified. Note: You can retrieve the list of asset properties using the 'Get Assets Properties' operation. |
update_asset Investigation |
Get Cases | Retrieves a detailed list of all cases or specific cases from QRadar based on input parameters specified. Note: This action is supported on QRadar API version 7.0 and later. |
get_cases Investigation |
Create Case |
Creates a new case on QRadar based on the case properties you have specified. Note: This action is supported on QRadar API version 7.0 and later. |
create_case Investigation |
Get Reference Tables | Retrieves a detailed list of all reference tables or specific reference tables from QRadar based on input parameters specified. | get_reference_tables Investigation |
Delete or Purge Reference Table | Deletes a specific reference table and optionally purges its content from QRadar based on the reference table name you have specified. Note: You can retrieve names and details of reference tables using the 'Get Reference Tables' operation. |
delete_reference_table Investigation |
Get Table Elements | Retrieves the record details (elements) of a specific reference table based on the reference table name you have specified. Note: You can retrieve names and details of reference tables using the 'Get Reference Tables' operation. |
get_table_elements Investigation |
Add or Update Table Element | Adds or updates an element in the specified reference table based on the reference table name, outer key, inner key, and other input parameters you have specified. | add_table_element Investigation |
Delete Table Element | Specify the element to be deleted from a reference table on Qradar based on the input parameters specified. | delete_table_element Investigation |
Parameter | Description |
---|---|
Filter String | Specify the filter string based on which you want to retrieve the list of offenses from QRadar. For example, assigned_to="admin" . |
The JSON output contains a list of offenses retrieved from the QRadar server, based on the filter string that you have specified.
The output contains the following populated JSON schema:
[ { "credibility": "", "source_address_ids": [], "remote_destination_count": "", "local_destination_address_ids": [], "assigned_to": "", "local_destination_count": "", "source_count": "", "start_time": "", "id": "", "destination_networks": [], "inactive": "", "protected": "", "policy_category_count": "", "description": "", "category_count": "", "domain_id": "", "relevance": "", "device_count": "", "security_category_count": "", "flow_count": "", "event_count": "", "offense_source": "", "status": "", "magnitude": "", "severity": "", "username_count": "", "closing_user": "", "follow_up": "", "closing_reason_id": "", "close_time": "", "source_network": "", "last_updated_time": "", "categories": [], "offense_type": "" } ]
Parameter | Description |
---|---|
QRadar Offense ID | Specify the Offense ID based on which you want to retrieve events from QRadar. |
Offense Start Time | Specify the number of milliseconds since the epoch from the offense was started. |
Offense Last Update Time | Specify the number of milliseconds since the epoch from the offense was last modified. |
Max Events to return | (Optional) Specify the maximum number of events that this operation should return. |
A JSON output contains details of events associated with a QRadar offense, retrieved from the QRadar server, based on the QRadar offense ID that you have specified.
The output contains the following populated JSON schema:
{ "events": [ { "qid": "", "category": "", "sourceip": "", "username": "", "magnitude": "", "starttime": "", "eventcount": "", "identityip": "", "protocolid": "", "sourceport": "", "logsourceid": "", "destinationip": "", "destinationport": "" } ] }
Parameter | Description |
---|---|
Ariel Search String | Specify the Ariel query that you want to run on the QRadar server. |
The JSON output contains details of offenses or events depending on the query that you run on the QRadar server. QRadar uses the Ariel Query Language (AQL) to search for offenses or events based on query parameters.
The output contains a non-dictionary value.
None
The JSON output contains a list of closing reasons associated with all offenses retrieved from the QRadar server.
The output contains the following populated JSON schema:
[ { "is_deleted": "", "id": "", "is_reserved": "", "text": "" } ]
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense that you want to close on the QRadar server. |
Offense Closing Reason - ID | Specify the ID of the offense closing reason using which you want to close the offense on the QRadar server. |
Closure Note | (Optional) Note that you want to associate with the offense that you want to close on the QRadar server. |
The JSON output contains the updated offense details, including the status (should be closed) of the specified offense retrieved from the QRadar server.
The output contains the following populated JSON schema:
{ "credibility": "", "source_address_ids": [], "remote_destination_count": "", "local_destination_address_ids": [], "assigned_to": "", "local_destination_count": "", "source_count": "", "start_time": "", "id": "", "destination_networks": [], "inactive": "", "protected": "", "policy_category_count": "", "description": "", "category_count": "", "domain_id": "", "relevance": "", "device_count": "", "security_category_count": "", "flow_count": "", "event_count": "", "offense_source": "", "status": "", "magnitude": "", "severity": "", "username_count": "", "closing_user": "", "follow_up": "", "closing_reason_id": "", "close_time": "", "source_network": "", "last_updated_time": "", "categories": [], "offense_type": "" }
The offense data provided by QRadar contains the IDs of the source addresses. Use this operation to fetch the IP address details for the specified source address IDs.
Parameter | Description |
---|---|
Source Address Ids | Specify the IDs of source addresses based on which you want to retrieve IP address details from the QRadar server. For example, [3,4,5] . |
The output contains the following populated JSON schema:
{ "id": "", "source_ip": "", "network": "", "magnitude": "" }
The offense data provided by QRadar contains the IDs of the destination addresses. Use this operation to fetch the IP address details for the specified destination address IDs.
Parameter | Description |
---|---|
Destination Address Ids | IDs of destination addresses based on which you want to retrieve IP address details from the QRadar server. For example, [3,4,5] . |
The output contains the following populated JSON schema:
{ "id": "", "local_destination_ip": "", "network": "", "magnitude": "" }
If you require to invoke a QRadar API apart from the functions that we provide, you can use this function to directly invoke the QRadar API. Refer to IBM documentation for more information on the QRadar REST APIs.
Parameter | Description |
---|---|
Endpoint | Specifies the REST endpoint. For example, /siem/offenses . |
Request Method | Select the request method. You can choose between GET, POST, or PATCH.
|
Headers in json format | (Optional) Additional JSON formatted headers. The following headers are already added by the connector: 'Accept': 'application/JSON', 'Content-Type': 'application/JSON', 'SEC': <token> ,'Version': <api_version>, |
The JSON output contains the JSON response of the API invoked.
The output contains a non-dictionary value.
None
The output contains the following populated JSON schema:
[ { "property_name": "", "database_type": "", "id": "", "name": "", "custom": "" } ]
Parameter | Description |
---|---|
Request Method | Select the request method option of the operation that you want to perform on the specified reference set in QRadar. You can choose from following options:
|
The output contains the following populated JSON schema:
Output schema when you choose Request Method as Retrieves Value:
{ "data": [ { "first_seen": "", "last_seen": "", "source": "", "value": "" } ], "message": "", "element_type": "", "timeout_type": "", "name": "", "number_of_elements": "", "creation_time": "" }
Output schema when you choose Request Method as Add Value or Delete Value:
{ "message": "", "element_type": "", "timeout_type": "", "name": "", "number_of_elements": "", "creation_time": "" }
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense whose associated notes you want to retrieve from the QRadar server. |
The output contains the following populated JSON schema:
[ { "id": "", "note_text": "", "create_time": "", "username": "" } ]
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense for which you want to create a note on the QRadar server. |
Closure Note | Specify the text of the closure note that you want to create for the specified offense on the QRadar server. |
The output contains the following populated JSON schema:
{ "id": "", "note_text": "", "create_time": "", "username": "" }
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of asset properties) is returned.
Parameter | Description |
---|---|
Limit | Specify the maximum count of asset properties to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Filter | Specify the parameters to be used to filter (restrict) the list of asset properties to be returned by this operation in the response. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
The output contains the following populated JSON schema:
[ { "data_type": "", "display": "", "custom": "", "name": "", "id": "", "state": "" } ]
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of assets) is returned.
Parameter | Description |
---|---|
Filter | Specify the parameters to be used to filter (restrict) the list of assets to be returned by this operation in the response. |
Limit | Specify the maximum count of assets to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Sort | Specify the fields using which you want to sort the response. Specify the negative (-) sign to sort the results in descending order and the positive sign (+) to sort in ascending order. |
The output contains the following populated JSON schema:
[ { "vulnerability_count": "", "interfaces": [ { "mac_address": "", "last_seen_profiler": "", "created": "", "last_seen_scanner": "", "first_seen_scanner": "", "ip_addresses": [ { "last_seen_profiler": "", "created": "", "last_seen_scanner": "", "first_seen_scanner": "", "network_id": "", "id": "", "type": "", "first_seen_profiler": "", "value": "" } ], "id": "", "first_seen_profiler": "" } ], "risk_score_sum": "", "hostnames": "", "id": "", "users": "", "domain_id": "", "properties": [ { "last_reported": "", "name": "", "type_id": "", "id": "", "last_reported_by": "", "value": "" } ], "products": "" } ]
Parameter | Description |
---|---|
Asset ID | Specify the ID of the asset whose properties you want to update on QRadar. |
Asset Properties | Specify a JSON dictionary with the asset properties that you want to update in the specified asset you want to update on QRadar |
Content Type | This is a system field that cannot be edited. |
The output contains a non-dictionary value.
Note: This operation is supported on QRadar API version 7.0 and later.
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of cases) is returned.
Parameter | Description |
---|---|
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Filter | Specify the parameters to be used to filter (restrict) the list of cases to be returned by this operation in the response. |
Limit | Specify the maximum count of cases to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
The output contains the following populated JSON schema:
[ { "assigned_to": [], "id": "", "name": "" } ]
NOTE: This operation is supported on QRadar API version 7.0 and later.
Parameter | Description |
---|---|
Case Properties | Specify a JSON dictionary with the case properties using which you want to create the case on QRadar. |
Content Type | This is a system field that cannot be edited. |
The output contains the following populated JSON schema:
{ "case_id": "", "name": "", "id": "", "state": "", "assigned_to": [] }
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of reference tables) is returned.
Parameter | Description |
---|---|
Filter | Specify the parameters to be used to filter (restrict) the list of reference tables to be returned by this operation in the response. |
Limit | Specify the maximum count of reference tables to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
The output contains the following populated JSON schema:
[ { "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": { "port": "", "source_ip": "", "timestamp": "" }, "element_type": "" } ]
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table that you want to delete from QRadar. |
Purge Table | Select the 'true' option from the Purge Table drop-down list if you want to have the contents of the specified reference table to be purged from QRadar, i.e., in this case, the structure of the specified reference table is retained. Select the 'false' (default) option from the Purge Table drop-down list to purge the contents of the specified reference table, i.e., in this case, the specified reference table is completely removed. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table that you want to delete from QRadar. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users. |
The output contains the following populated JSON schema:
{ "created_by": "", "created": "", "name": "", "modified": "", "started": "", "completed": "", "id": "", "message": "", "status": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table whose record details (elements) you want to retrieve from QRadar. |
Limit | (Optional) Specify the maximum count of table elements to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table whose record details (elements) you want to retrieve from QRadar. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users. |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "data": { "outer_key": { "inner_key": { "last_seen": "", "first_seen": "", "source": "", "value": "" } } }, "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table in which you want to add or update the specified element. |
Outer Key | Specify the outer key in which you want to add or update the specified element. |
Inner Key | Specify the inner key in which you want to add or update the specified element. |
Value | Specify the value of the element that you want to add or update in the specified reference table. Note: Date values must be represented in Unix Epoch milliseconds. |
Domain ID | (Optional) In the case of MSSP setups, you can specify the domain ID to be set for the 'value' you have specified in the 'Value' field. If the 'Domain ID' field is null, then the shared domain is used. |
Element Source | (Optional) Specify the source of the specified element that you want to add or update in the specified table. By default, this is set to 'FortiSOAR'. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table in which you want to add or update the specified element. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table from which you want to delete the specified element. |
Outer Key | Specify the outer key from which you want to delete the specified element. |
Inner Key | Specify the inner key from which you want to delete the specified element. |
value | Specify the value of the element that you want to delete from the specified reference table. Note: Date values must be represented in Epoch milliseconds. |
Domain ID | (Optional) In the case of MSSP setups, you can specify the domain ID to be set for the 'value' you have specified in the 'Value' field. If the 'Domain ID' field is null, then the shared domain is used. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table from which you want to delete the specified element. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
The Sample - IBM QRadar - 1.6.1
playbook collection comes bundled with the IBM QRadar connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IBM QRadar connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling offenses from IBM QRadar. Currently, "offenses" in IBM QRadar are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.
You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming IBM QRadar "offenses" to FortiSOAR™ "alerts".
The Data Ingestion Wizard enables you to configure the scheduled pulling of data from IBM QRadar into FortiSOAR™. It also lets you pull some sample data from IBM QRadar using which you can define the mapping of data between IBM QRadar and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users are mostly required to only map any custom fields that are added to the IBM QRadar incident.
status="OPEN"
in the Search Query field.UTC
.Field Mapping
screen displays the Sample Data on the right side and the Field Mapping (FortiSOAR™ fields) on the left side. The sample data is in the form of a Key-Value pair.categories
parameter of a QRadar offense to the Type
parameter of a FortiSOAR™ alert, click the Type field and then click the categories field to populate its keys:5
, and in the minute box enter 0
:Summary
screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks.IBM QRadar > Post Create Alert > Fetch Events
playbook, in the Start step (Post-Create trigger) step, in the Resource field, update the resource from Alerts to the module based on which you want to fetch the data.> QRadar > Create Alert
playbook, in the Add a note of offense update step, in the "Correlations" section, you will see an Alerts field that is being set. If you are using a module other than "Alert", then you will see a field with that name and you will require to set that field. For example, if you are using the "Incidents" module, then you will see the Incidents field and you will need to set that to ["{{vars.steps.Create_Record['@id']}}"]
IBM QRadar > Post Create Alert > Fetch Events
playbook, in the Set Variable step, add custom fields to the event_query_params
variable. By default, this is set as starttime,sourceip,destinationip,username,QIDNAME(qid) as 'Event_Name',CATEGORYNAME(category) AS 'Category_Name',LOGSOURCENAME(logsourceid) as 'Log_Source'
IBM QRadar > Post Create Alert > Fetch Events
playbook that is located at: Settings > System Fixtures > Data Ingestion Playbooks.IMPORTANT: The CyberSponse Application will be deprecated with the next release of this connector. Therefore, it is highly recommended that you set up Data Ingestion to ingest QRadar offenses into FortiSOAR.
If you want to forward offenses to FortiSOAR™ from the QRadar UI directly, then you require to install and configure the CyberSponse Application on the QRadar server. The extension zip file (CyberSponse_1.1.0.zip) is attached to this document. Upload and install the extension on the QRadar console following the steps described in the following IBM document: Uploading and installing extensions to IBM QRadar deployments.
After the installation, the CyberSponse Integration icon appears in the Plug-ins
section of the Admin tab.
Click the CyberSponse Integration icon to open the Server Configuration
dialog. Enter the details of the FortiSOAR server to which you want to forward the offenses and then click Save.
Ensure that the QRadar server has connectivity to the FortiSOAR™ server and can send requests to the FortiSOAR™ instance on port 443. Now, you can forward offenses to FortiSOAR™ by using the Create CyOPs alert button in the Offense Summary Toolbar
as shown in the following image:
Clicking the Create CyOPs alert button sends a POST trigger to the https://<CyOPs>/api/triggers/1/qradar with the payload {“Offense_ID”: <id>}
URL.
The API - Push Offense From QRadar included playbook listens to this API trigger and fetches all the data related to the offense specified in the offense id and creates a FortiSOAR™ alert. You can verify the integration with the help of this playbook or make a copy of the playbook and update it as per your requirement. If you make a copy, deactivate the included playbook, to avoid two playbooks acting on the same API trigger.
IBM QRadar SIEM helps your business by detecting anomalies, uncovering advanced threats, and removing false positives. It consolidates log events and network flow data from thousands of devices, endpoints, and applications distributed throughout a network.
This document provides information about the IBM QRadar connector, which facilitates automated interactions, with a QRadar server using FortiSOAR™ playbooks. Add the IBM QRadar connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically getting information about the offenses and details of the offenses from QRadar and also querying a QRadar device.
You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling offenses from IBM QRadar. For more information, see the Data Ingestion Support section.
Connector Version: 1.6.1
FortiSOAR™ Version Tested on: 7.4.1-3167
IBM QRadar Version Tested on: 7.4.1
Authored By: Fortinet
Certified: Yes
The following enhancements have been made to the IBM QRadar connector in version 1.6.1:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root
user to install connectors from an SSH session:
yum install cyops-connector-qradar
/api/ariel/*
and /api/siem/*
APIs, therefore ensure that you have the appropriate access as required by these APIs.For the procedure to configure a connector, click here.
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IBM QRadar connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
Parameter | Description |
---|---|
Address | Specify the IP address of the QRadar server from where the connector gets offenses information and to which you connect and perform automated operations. |
API Token | Specify the API token to access the QRadar server to which you connect and perform automated operations. |
API Version | Specify the version of the QRadar API to be used for performing automated operations. By default, this is set to 14.0. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified. By default, this is set to True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™:
Function | Description | Annotation and Category |
---|---|---|
Get Offenses from QRadar | Retrieves a list of offenses from the QRadar server based on the filter string that you have specified. | get_offenses Investigation |
Get Events Related to an Offense | Retrieves details of events associated with a QRadar offense, from the QRadar server, based on the QRadar offense ID that you have specified. | get_events Investigation |
Make an Ariel Query to QRadar | Executes an Ariel query on the QRadar server. QRadar uses the Ariel Query Language (AQL) to search for offenses or events based on query parameters. | run_query Investigation |
Get Offense Closing Reasons | Retrieves a list of closing reasons associated with all offenses from the QRadar server. | get_offense_closing_reasons Remediation |
Close Offense | Closes an offense on the QRadar server based on the offense ID that you have specified. | close_offense Remediation |
Get Source IP Addresses | Retrieves IP address details associated with source address IDs from the QRadar server, based on the source address IDs that you have specified | ip_details Investigation |
Get Destination IP Addresses | Retrieves IP address details associated with the destination address IDs from the QRadar server, based on the destination address IDs that you have specified | ip_details Investigation |
Invoke QRadar REST API | Invokes a function to Get or Post an API endpoint on the QRadar server. | api_call Miscellaneous |
Get Offense Types | Retrieves a list containing IDs of all the offense types from the QRadar server. | get_offense_type Investigation |
Manipulate Reference Set Content | Adds or deletes the content that you have specified from a reference set on QRadar you have specified. | handle_reference_set_value Investigation |
Get Offense Notes | Retrieves a list of notes associated with a specified offense in QRadar based on the offense ID you have specified. | get_notes Remediation |
Create Note | Creates a note for a specified offense in QRadar based on the offense ID you have specified. | add_notes Remediation |
Get Assets Properties | Retrieves a detailed list of available asset properties or specific available asset properties from QRadar based on input parameters specified. | get_assets_properties Investigation |
Get Assets | Retrieves a detailed list of all available assets or specific available assets from QRadar based on input parameters specified. | get_assets Investigation |
Update Asset | Updates the attributes of a specific asset on the QRadar server based on the asset ID and asset properties you have specified. Note: You can retrieve the list of asset properties using the 'Get Assets Properties' operation. |
update_asset Investigation |
Get Cases | Retrieves a detailed list of all cases or specific cases from QRadar based on input parameters specified. Note: This action is supported on QRadar API version 7.0 and later. |
get_cases Investigation |
Create Case |
Creates a new case on QRadar based on the case properties you have specified. Note: This action is supported on QRadar API version 7.0 and later. |
create_case Investigation |
Get Reference Tables | Retrieves a detailed list of all reference tables or specific reference tables from QRadar based on input parameters specified. | get_reference_tables Investigation |
Delete or Purge Reference Table | Deletes a specific reference table and optionally purges its content from QRadar based on the reference table name you have specified. Note: You can retrieve names and details of reference tables using the 'Get Reference Tables' operation. |
delete_reference_table Investigation |
Get Table Elements | Retrieves the record details (elements) of a specific reference table based on the reference table name you have specified. Note: You can retrieve names and details of reference tables using the 'Get Reference Tables' operation. |
get_table_elements Investigation |
Add or Update Table Element | Adds or updates an element in the specified reference table based on the reference table name, outer key, inner key, and other input parameters you have specified. | add_table_element Investigation |
Delete Table Element | Specify the element to be deleted from a reference table on Qradar based on the input parameters specified. | delete_table_element Investigation |
Parameter | Description |
---|---|
Filter String | Specify the filter string based on which you want to retrieve the list of offenses from QRadar. For example, assigned_to="admin" . |
The JSON output contains a list of offenses retrieved from the QRadar server, based on the filter string that you have specified.
The output contains the following populated JSON schema:
[ { "credibility": "", "source_address_ids": [], "remote_destination_count": "", "local_destination_address_ids": [], "assigned_to": "", "local_destination_count": "", "source_count": "", "start_time": "", "id": "", "destination_networks": [], "inactive": "", "protected": "", "policy_category_count": "", "description": "", "category_count": "", "domain_id": "", "relevance": "", "device_count": "", "security_category_count": "", "flow_count": "", "event_count": "", "offense_source": "", "status": "", "magnitude": "", "severity": "", "username_count": "", "closing_user": "", "follow_up": "", "closing_reason_id": "", "close_time": "", "source_network": "", "last_updated_time": "", "categories": [], "offense_type": "" } ]
Parameter | Description |
---|---|
QRadar Offense ID | Specify the Offense ID based on which you want to retrieve events from QRadar. |
Offense Start Time | Specify the number of milliseconds since the epoch from the offense was started. |
Offense Last Update Time | Specify the number of milliseconds since the epoch from the offense was last modified. |
Max Events to return | (Optional) Specify the maximum number of events that this operation should return. |
A JSON output contains details of events associated with a QRadar offense, retrieved from the QRadar server, based on the QRadar offense ID that you have specified.
The output contains the following populated JSON schema:
{ "events": [ { "qid": "", "category": "", "sourceip": "", "username": "", "magnitude": "", "starttime": "", "eventcount": "", "identityip": "", "protocolid": "", "sourceport": "", "logsourceid": "", "destinationip": "", "destinationport": "" } ] }
Parameter | Description |
---|---|
Ariel Search String | Specify the Ariel query that you want to run on the QRadar server. |
The JSON output contains details of offenses or events depending on the query that you run on the QRadar server. QRadar uses the Ariel Query Language (AQL) to search for offenses or events based on query parameters.
The output contains a non-dictionary value.
None
The JSON output contains a list of closing reasons associated with all offenses retrieved from the QRadar server.
The output contains the following populated JSON schema:
[ { "is_deleted": "", "id": "", "is_reserved": "", "text": "" } ]
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense that you want to close on the QRadar server. |
Offense Closing Reason - ID | Specify the ID of the offense closing reason using which you want to close the offense on the QRadar server. |
Closure Note | (Optional) Note that you want to associate with the offense that you want to close on the QRadar server. |
The JSON output contains the updated offense details, including the status (should be closed) of the specified offense retrieved from the QRadar server.
The output contains the following populated JSON schema:
{ "credibility": "", "source_address_ids": [], "remote_destination_count": "", "local_destination_address_ids": [], "assigned_to": "", "local_destination_count": "", "source_count": "", "start_time": "", "id": "", "destination_networks": [], "inactive": "", "protected": "", "policy_category_count": "", "description": "", "category_count": "", "domain_id": "", "relevance": "", "device_count": "", "security_category_count": "", "flow_count": "", "event_count": "", "offense_source": "", "status": "", "magnitude": "", "severity": "", "username_count": "", "closing_user": "", "follow_up": "", "closing_reason_id": "", "close_time": "", "source_network": "", "last_updated_time": "", "categories": [], "offense_type": "" }
The offense data provided by QRadar contains the IDs of the source addresses. Use this operation to fetch the IP address details for the specified source address IDs.
Parameter | Description |
---|---|
Source Address Ids | Specify the IDs of source addresses based on which you want to retrieve IP address details from the QRadar server. For example, [3,4,5] . |
The output contains the following populated JSON schema:
{ "id": "", "source_ip": "", "network": "", "magnitude": "" }
The offense data provided by QRadar contains the IDs of the destination addresses. Use this operation to fetch the IP address details for the specified destination address IDs.
Parameter | Description |
---|---|
Destination Address Ids | IDs of destination addresses based on which you want to retrieve IP address details from the QRadar server. For example, [3,4,5] . |
The output contains the following populated JSON schema:
{ "id": "", "local_destination_ip": "", "network": "", "magnitude": "" }
If you require to invoke a QRadar API apart from the functions that we provide, you can use this function to directly invoke the QRadar API. Refer to IBM documentation for more information on the QRadar REST APIs.
Parameter | Description |
---|---|
Endpoint | Specifies the REST endpoint. For example, /siem/offenses . |
Request Method | Select the request method. You can choose between GET, POST, or PATCH.
|
Headers in json format | (Optional) Additional JSON formatted headers. The following headers are already added by the connector: 'Accept': 'application/JSON', 'Content-Type': 'application/JSON', 'SEC': <token> ,'Version': <api_version>, |
The JSON output contains the JSON response of the API invoked.
The output contains a non-dictionary value.
None
The output contains the following populated JSON schema:
[ { "property_name": "", "database_type": "", "id": "", "name": "", "custom": "" } ]
Parameter | Description |
---|---|
Request Method | Select the request method option of the operation that you want to perform on the specified reference set in QRadar. You can choose from following options:
|
The output contains the following populated JSON schema:
Output schema when you choose Request Method as Retrieves Value:
{ "data": [ { "first_seen": "", "last_seen": "", "source": "", "value": "" } ], "message": "", "element_type": "", "timeout_type": "", "name": "", "number_of_elements": "", "creation_time": "" }
Output schema when you choose Request Method as Add Value or Delete Value:
{ "message": "", "element_type": "", "timeout_type": "", "name": "", "number_of_elements": "", "creation_time": "" }
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense whose associated notes you want to retrieve from the QRadar server. |
The output contains the following populated JSON schema:
[ { "id": "", "note_text": "", "create_time": "", "username": "" } ]
Parameter | Description |
---|---|
Offense ID | Specify the ID of the offense for which you want to create a note on the QRadar server. |
Closure Note | Specify the text of the closure note that you want to create for the specified offense on the QRadar server. |
The output contains the following populated JSON schema:
{ "id": "", "note_text": "", "create_time": "", "username": "" }
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of asset properties) is returned.
Parameter | Description |
---|---|
Limit | Specify the maximum count of asset properties to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Filter | Specify the parameters to be used to filter (restrict) the list of asset properties to be returned by this operation in the response. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
The output contains the following populated JSON schema:
[ { "data_type": "", "display": "", "custom": "", "name": "", "id": "", "state": "" } ]
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of assets) is returned.
Parameter | Description |
---|---|
Filter | Specify the parameters to be used to filter (restrict) the list of assets to be returned by this operation in the response. |
Limit | Specify the maximum count of assets to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Sort | Specify the fields using which you want to sort the response. Specify the negative (-) sign to sort the results in descending order and the positive sign (+) to sort in ascending order. |
The output contains the following populated JSON schema:
[ { "vulnerability_count": "", "interfaces": [ { "mac_address": "", "last_seen_profiler": "", "created": "", "last_seen_scanner": "", "first_seen_scanner": "", "ip_addresses": [ { "last_seen_profiler": "", "created": "", "last_seen_scanner": "", "first_seen_scanner": "", "network_id": "", "id": "", "type": "", "first_seen_profiler": "", "value": "" } ], "id": "", "first_seen_profiler": "" } ], "risk_score_sum": "", "hostnames": "", "id": "", "users": "", "domain_id": "", "properties": [ { "last_reported": "", "name": "", "type_id": "", "id": "", "last_reported_by": "", "value": "" } ], "products": "" } ]
Parameter | Description |
---|---|
Asset ID | Specify the ID of the asset whose properties you want to update on QRadar. |
Asset Properties | Specify a JSON dictionary with the asset properties that you want to update in the specified asset you want to update on QRadar |
Content Type | This is a system field that cannot be edited. |
The output contains a non-dictionary value.
Note: This operation is supported on QRadar API version 7.0 and later.
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of cases) is returned.
Parameter | Description |
---|---|
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Filter | Specify the parameters to be used to filter (restrict) the list of cases to be returned by this operation in the response. |
Limit | Specify the maximum count of cases to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
The output contains the following populated JSON schema:
[ { "assigned_to": [], "id": "", "name": "" } ]
NOTE: This operation is supported on QRadar API version 7.0 and later.
Parameter | Description |
---|---|
Case Properties | Specify a JSON dictionary with the case properties using which you want to create the case on QRadar. |
Content Type | This is a system field that cannot be edited. |
The output contains the following populated JSON schema:
{ "case_id": "", "name": "", "id": "", "state": "", "assigned_to": [] }
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list (of reference tables) is returned.
Parameter | Description |
---|---|
Filter | Specify the parameters to be used to filter (restrict) the list of reference tables to be returned by this operation in the response. |
Limit | Specify the maximum count of reference tables to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
The output contains the following populated JSON schema:
[ { "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": { "port": "", "source_ip": "", "timestamp": "" }, "element_type": "" } ]
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table that you want to delete from QRadar. |
Purge Table | Select the 'true' option from the Purge Table drop-down list if you want to have the contents of the specified reference table to be purged from QRadar, i.e., in this case, the structure of the specified reference table is retained. Select the 'false' (default) option from the Purge Table drop-down list to purge the contents of the specified reference table, i.e., in this case, the specified reference table is completely removed. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table that you want to delete from QRadar. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users. |
The output contains the following populated JSON schema:
{ "created_by": "", "created": "", "name": "", "modified": "", "started": "", "completed": "", "id": "", "message": "", "status": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table whose record details (elements) you want to retrieve from QRadar. |
Limit | (Optional) Specify the maximum count of table elements to be returned by this operation in the response. Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table whose record details (elements) you want to retrieve from QRadar. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users. |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "data": { "outer_key": { "inner_key": { "last_seen": "", "first_seen": "", "source": "", "value": "" } } }, "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table in which you want to add or update the specified element. |
Outer Key | Specify the outer key in which you want to add or update the specified element. |
Inner Key | Specify the inner key in which you want to add or update the specified element. |
Value | Specify the value of the element that you want to add or update in the specified reference table. Note: Date values must be represented in Unix Epoch milliseconds. |
Domain ID | (Optional) In the case of MSSP setups, you can specify the domain ID to be set for the 'value' you have specified in the 'Value' field. If the 'Domain ID' field is null, then the shared domain is used. |
Element Source | (Optional) Specify the source of the specified element that you want to add or update in the specified table. By default, this is set to 'FortiSOAR'. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table in which you want to add or update the specified element. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
Parameter | Description |
---|---|
Reference Table Name | Specify the name of the reference table from which you want to delete the specified element. |
Outer Key | Specify the outer key from which you want to delete the specified element. |
Inner Key | Specify the inner key from which you want to delete the specified element. |
value | Specify the value of the element that you want to delete from the specified reference table. Note: Date values must be represented in Epoch milliseconds. |
Domain ID | (Optional) In the case of MSSP setups, you can specify the domain ID to be set for the 'value' you have specified in the 'Value' field. If the 'Domain ID' field is null, then the shared domain is used. |
Fields | (Optional) Specify the fields to be returned in the response. Fields that are not named are excluded. Specify subfields in brackets, and multiple fields in the same object are separated by commas. |
Namespace | (Optional) Specify the namespace of the reference table from which you want to delete the specified element. By default, it is 'SHARED' for 'admin' users and 'TENANT' for 'tenant' users. Note: If you select true from the Purge Table drop-down list, i.e., purge_only is set to true , then the default is 'SHARED' for all users |
The output contains the following populated JSON schema:
{ "timeout_type": "", "number_of_elements": "", "creation_time": "", "name": "", "key_name_types": "", "element_type": "" }
The Sample - IBM QRadar - 1.6.1
playbook collection comes bundled with the IBM QRadar connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IBM QRadar connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling offenses from IBM QRadar. Currently, "offenses" in IBM QRadar are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.
You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming IBM QRadar "offenses" to FortiSOAR™ "alerts".
The Data Ingestion Wizard enables you to configure the scheduled pulling of data from IBM QRadar into FortiSOAR™. It also lets you pull some sample data from IBM QRadar using which you can define the mapping of data between IBM QRadar and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users are mostly required to only map any custom fields that are added to the IBM QRadar incident.
status="OPEN"
in the Search Query field.UTC
.Field Mapping
screen displays the Sample Data on the right side and the Field Mapping (FortiSOAR™ fields) on the left side. The sample data is in the form of a Key-Value pair.categories
parameter of a QRadar offense to the Type
parameter of a FortiSOAR™ alert, click the Type field and then click the categories field to populate its keys:5
, and in the minute box enter 0
:Summary
screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks.IBM QRadar > Post Create Alert > Fetch Events
playbook, in the Start step (Post-Create trigger) step, in the Resource field, update the resource from Alerts to the module based on which you want to fetch the data.> QRadar > Create Alert
playbook, in the Add a note of offense update step, in the "Correlations" section, you will see an Alerts field that is being set. If you are using a module other than "Alert", then you will see a field with that name and you will require to set that field. For example, if you are using the "Incidents" module, then you will see the Incidents field and you will need to set that to ["{{vars.steps.Create_Record['@id']}}"]
IBM QRadar > Post Create Alert > Fetch Events
playbook, in the Set Variable step, add custom fields to the event_query_params
variable. By default, this is set as starttime,sourceip,destinationip,username,QIDNAME(qid) as 'Event_Name',CATEGORYNAME(category) AS 'Category_Name',LOGSOURCENAME(logsourceid) as 'Log_Source'
IBM QRadar > Post Create Alert > Fetch Events
playbook that is located at: Settings > System Fixtures > Data Ingestion Playbooks.IMPORTANT: The CyberSponse Application will be deprecated with the next release of this connector. Therefore, it is highly recommended that you set up Data Ingestion to ingest QRadar offenses into FortiSOAR.
If you want to forward offenses to FortiSOAR™ from the QRadar UI directly, then you require to install and configure the CyberSponse Application on the QRadar server. The extension zip file (CyberSponse_1.1.0.zip) is attached to this document. Upload and install the extension on the QRadar console following the steps described in the following IBM document: Uploading and installing extensions to IBM QRadar deployments.
After the installation, the CyberSponse Integration icon appears in the Plug-ins
section of the Admin tab.
Click the CyberSponse Integration icon to open the Server Configuration
dialog. Enter the details of the FortiSOAR server to which you want to forward the offenses and then click Save.
Ensure that the QRadar server has connectivity to the FortiSOAR™ server and can send requests to the FortiSOAR™ instance on port 443. Now, you can forward offenses to FortiSOAR™ by using the Create CyOPs alert button in the Offense Summary Toolbar
as shown in the following image:
Clicking the Create CyOPs alert button sends a POST trigger to the https://<CyOPs>/api/triggers/1/qradar with the payload {“Offense_ID”: <id>}
URL.
The API - Push Offense From QRadar included playbook listens to this API trigger and fetches all the data related to the offense specified in the offense id and creates a FortiSOAR™ alert. You can verify the integration with the help of this playbook or make a copy of the playbook and update it as per your requirement. If you make a copy, deactivate the included playbook, to avoid two playbooks acting on the same API trigger.