Passing context-specific information to a page script

You use a GUI Action to pass information about offenses, assets, vulnerabilities from a QRadar® table to a page script.

For example, you can extract selected information from QRadar and pass it to a script for further processing. You can create a simple app that allows users to select offenses that are listed as rows in the table on the Offenses tab and pass that information to a page script. By clicking a button on the Offenses tab toolbar, a JavaScript alert that contains the extracted information is displayed.

You can also pass information about vulnerabilities, network activity, assets, and information from any table in most QRadar pages.

The following manifest.json file example shows details of entries that you make in this file:

manifest.json

In the app's manifest.json file, the REST method that is used by the views.py script is defined. The REST method also specifies that application name, page ID, and application context must be defined.

appName: The application name is defined in the page_scripts block and indicates to QRadar which tab contains the data to be passed to the script.
pageId: The page ID is defined in the page_scripts block and indicates to QRadar which page within the tab contains the data to be passed to the script.
appContext: The application context refers to the row or rows that are manually selected by the user on the tab and page that is defined by the application name and page ID. In this case, it is the table on the Offense List page on the Offenses tab. Each row contains data on a particular offense and it is this data that is passed to the custom script.

{
	"name":"offense log pass ids",
	"description":"An example of passing ids",
	"version":"1.0",
	"uuid":"a4095969-1c88-4e35-aecb-4eea7b061cd3",

	"rest_methods": [ 1 
		{
            "name":"listFunction",
            "url":"/listFunction",
            "method":"GET",
            "argument_names":["appName","pageId","appContext"] 2 
		}
	],

	"gui_actions": [ 3 
		{
			"id":"OffenseListToolbarButton",
			"text":"Offense pass Ids !",
			"description":"Pass Ids for offenses !",
			"icon":"static/images/bookmarks_small.png",
			"rest_method":"listFunction", 4 
			"javascript":"my_toolbar_button_action(result)", 5 
			"groups":["OffenseListToolbar"] 6 
		}
	],

	"page_scripts": [ 7 
		{
			"app_name":"SEM",
			"page_id":"OffenseList",
			"scripts":["static/js/custom_script.js"]
		}
	]
}

The following list describes the contents in the code snippet from the manifest.json file.

Use the rest_methods block to define the API name, app.route URL, and API method that you add to views.py.
Use the argument names to precisely locate the data that is passed to the script. The app name and page ID values are defined in the QRadar tab and page. In this case, the Offenses tab and main Offense List page.
The appContext argument is a placeholder that holds the actual offense data that is selected when the user clicks a row or rows in the Offense List table. This data is passed to JavaScript for processing.
Use the gui_action block to define the button that passes data to the screen when the user clicks it.
Use the rest_methods block to define the REST methods that are used in the views.py script to list the data from each selected row.
Use the JavaScript function to create an alert dialog that displays the JSON string that is passed by the appContext argument from the listFunction method.
Use the GUI Action group location to define where the button appears. In this case, the button appears on the main Offense List page toolbar.
Use the page_scripts block for the app_name and page_id arguments that are passed to the REST API method, and for the location of the JavaScript file that processes the data.

app/views.py

The app's app/views.py defines the application route and function that retrieves the appContext data and passes it as JSON to the custom script.

__author__ = 'IBM'

from flask import render_template, request
from app import app
from qpylib import qpylib
import json

@app.route('/')
@app.route('/index')
def index():
    return render_template("index.html", title = "Offense Context App!")

@app.route('/listFunction', methods=['GET']) 1      
def listFunction():
    qpylib.log("listFunction", "info")
    rows = request.args.get("appContext") 2 
    qpylib.log("selectedRows=" + rows, "info")

    #You can process the data and return any value here,
    #It is passed into JavaScript.
    return json.dumps({'context_passed_to_python_route':rows}) 3

The following list describes the contents in the code snippet from the views.py script.

The function URL and REST method that is defined in the rest_methods block of the app manifest file.
The row variable that gets the content of the selected rows by using the appContext argument.
The Flask json.dumps method formats the data that is contained in the rows variable as JSON. This data is passed to the custom_script.js file that displays it in a simple alert.

app/static/js/custom_script.js

The following short JavaScript creates an alert and formats the JSON content into strings for each row.

function my_toolbar_button_action(offense)
{
	alert(JSON.stringify(offense));
}