IBM Support

QRadar: Expanding on the use of the right-click menu for event and flow properties

How To


Summary

The enhancing the right-click menu document describes how to add functionality and run commands on certain Ariel properties from events or flows. This technical note provides guidance for users to create a script and use the QRadar API to add data to a reference set.

Objective

The goal of this technical note is to provide an example of the right-click menu action so any user can further implement useful commands for properties on the Log Activity or Network Activity tabs.
The example shows only four properties that can be used:
  • sourceIP
  • sourcePort
  • destinationIP
  • QID
This functionality addresses any property searchable within an AQL search performed under "Advanced Search" in the UI, such as "destinationIP", "sourceMac", "destinationMac", or other. The four properties listed as examples might be the most useful.

The right-click menu functionality appears only in the Log Activity screen when the real-time streaming is paused, or a certain timeframe is selected, and the property itself is clicked.  If the right-click is used on a Destination Port, for example, the added option in the right-click menu does not appear.

Environment

QRadar SIEM 7.3, 7.4, and 7.5

Steps

Before you begin
  • This procedure is for On-prem deployments and not QRadar on Cloud.
  • The "arguments" section cannot contain any whitespace or it can fail. 
  • Include only properties to be used or displayed, and separated by a dash if more than one is used.
  • If a curl command is called to the API, an authentication token with admin/admin privileges is needed.
  • The reference set needs to be of the type of the data type to be added. An IP address needs to be IP, Port needs to be Port, a string value such as URL must match this type of data.
There are four required entries to add in the arielRightClick.properties file to add new functionality.
  1. plug-inActions - The function needs to be defined as either <property>webUrlAction or <property>ScriptAction
  2. arielProperty - The property needs to be defined first. It is the same property listed in the plug-inAction.
  3. Text - The text is what is shown in the menu in order to make the selection.
  4. Url - Is to be used for an urlWebAction or command and arguments with a ScriptAction.

Generating an authorized service token

  1. Log in to the QRadar UI as an admin user.
  2. Click Admin tab.
  3. Click the Authentication Services icon.
  4. Generate an Authentication token with admin privileges.
  5. Copy the Authentication token to a clipboard to be used in creating the script.

Creating the script

When the UI runs a "scriptAction" command, it runs from CLI in a jail, /opt/qradar/bin/ca_jail/, which is treated as the new root "/" directory.  In the example, it references /usr/bin/refSet.sh, which exists under /opt/qradar/bin/ca_jail/usr/bin/refSet.shWhen Tomcat is restarted, it replicates any entries under /usr/bin/ to the /opt/qradar/bin/ca_jail/usr/bin/ path.
 
In the properties file, these directory paths might be referenced as:
  • /usr/bin/echo = /opt/qradar/bin/ca_jail/usr/bin/echo
  • /usr/bin/curl = /opt/qradar/bin/ca_jail/usr/bin/curl
  • /usr/bin/refSet.sh = /opt/qradar/bin/ca_jail/usr/bin/refSet.sh
 
If another bash script is created to run a command, executable permissions need to be added with the command:
"chmod +x"
Note: If your right-click function references any related files, such as a .json file or other files that contain required data, you must enable permissions with the chmod command. 
 
Using a curl command to the API, such as the one in the example where an IP address is added to a Reference Set of IP addresses, a script can be used. The "argument" field is passed to the script, and that receives a variable assignment of $1. This variable is used within the script itself.
  1. Use a text editor such as vi and create this script.
    #! /bin/bash
    /usr/bin/curl -Sk -X POST -H 'Version: 16.0' -H 'SEC: <token>' -H 'Accept: 
    application/json' 'https://<console_IP>/api/reference_data/sets/<referenceSetName>
    ?value='$1
  2. In the script, the placeholders are:
    • The "Version" is the version of the API found on the navigation menu ( Navigation menu icon ), and choosing Interactive API for Developers.
      image 12054
    • The <token> is the value of the authorization token generated.
    • The <console_IP> is the IP of the Console.
    • The <referenceSetName> is the reference set we are adding the IP address to. 
  3. The completed script looks similar to:
    #! /bin/bash
    /usr/bin/curl -Sk -X POST -H 'Version: 16.0' -H 'SEC: dae1dcd8-xxxx-xxxx-xxxx-979f16954716' -H 'Accept: application/json' 'https://192.168.1.68/api/reference_data/sets/Example_plug-in_option?value='$1
    
    Note: The name of the reference set must match the one created exactly.
  4. Save the script as /usr/bin/refSet.sh
  5. To set access permissions for the script to run, type:
    ​chmod +x /usr/bin/refSet.sh
  6. In order to make the right-click menu, use the script, and use the Source IP as the variable. The variables must exist as entries in the /opt/qradar/conf/arielRightClick.properties file. For example,
    plug-inActions=sourceIPScriptAction
    sourceIPScriptAction.arielProperty=sourceIP
    sourceIPScriptAction.text=Add IP address
    sourceIPScriptAction.command=/usr/bin/refSet.sh
    sourceIPScriptAction.arguments=$sourceIP$
    Note: The value after sourceIPScriptAction.text can be user-defined.
  7. Save any changes to the /opt/qradar/conf/arielRightClick.properties file.
    Important: To load configuration changes in the next step, you must restart the web server (Tomcat). When you restart Tomcat, this action logs out all users, stops Log Activity exports in progress, and can prevent scheduled reports from starting. QRadar Support recommends administrators restart services during scheduled maintenance.
  8. To restart services and load changes in to the user interface, type:
    systemctl restart Tomcat
    
    Results
    Wait for the Tomcat service to start. The restart process typically takes several minutes to complete. When the user interface is available, you can attempt to run your right-click action.
  9. After Tomcat is done restarting, the script you created under /usr/bin/ is now also found under /opt/qradar/bin/ca_jail/usr/bin/.

Testing your right-click plug-in

 
To run the script:
  1. Log in to the QRadar user interface.
  2. Click the Log Activity tab.
  3. From the View list box, select a time interval.
  4. Right-Click on a Source IP to add to the Reference set.
    Note: In this example, the right-click action is defined for the Source IP column.
  5. Select Plug-in Options > Add IP address.
    image 12204
  6. A message is displayed with the result of the action.
    image 12212
  7. Click Close.
  8. Click the Admin tab.
  9. In the System Configuration section, click Reference Set Management.
  10. Select the reference set created for your right-click action.
    image 12215
  11. Verify the source IP address is added to the reference set.
    image 12213

    Results
    The right-click plug-in adds the information from the Log Activity tab to the reference set for use in rules or custom event properties.

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":"TS006686801","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
26 September 2022

UID

ibm16508864