Context-specific metadata provider example

Metadata providers are used to show extra context-sensitive information in IBM® QRadar®.

Metadata is displayed when the user's mouse pointer hovers over an item in the user interface. For example, you might want to know the user name that is associated with an IP address, which you can view by hovering your mouse pointer over the IP address.

The following image shows an example of context-sensitive information that is displayed when you hover your mouse pointer over an IP address in the table.

You can create custom metadata providers for three types of metadata:

ip displayed for an IP address throughout QRadar.
userName displayed for a user name throughout QRadar.
ariel:<FIELD_NAME>, where <FIELD_NAME> is the name of a field in the QRadar Event or Flow viewer - displayed for a field in the event or flow viewer.

The following example demonstrates how to write a simple app that provides extra metadata when you hover your mouse pointer over IP addresses in QRadar.

manifest.json

The manifest.json file contains the following code:

{
     "name":"IP Metadata Provider Example",   
     "description":"Sample IP metadata provider functionality.",
     "version":"1.0",

     rest_methods: [      
      {
              name:"getIPMetadata",            
              url:"/ip_metadata_provider",
              method:"GET",          
              argument_names:["context"]
       }
     ],  
 
     "metadata_providers" : [
         {            
             "rest_method":"getIPMetadata",
             "metadata_type":"ip"    
         }
     ]
 }

The following table describes the block fields that are included in the Manifest.json file.

Table 1. Manifest.json file block fields
Field	Description
rest_methods	Describes the rest method that is used to return the additional metadata.
metadata_providers	Describes the metadata type and the rest method that returns the additional metadata.

The manifest file shows that the app provides metadata for QRadar IP addresses that use the REST method getIPMetadata. This REST method is exposed by the /ip_metadata_provider endpoint within the app. This endpoint represents a GET request and expects an argument context. The context argument is appended to the GET request as a query string that contains the context-specific IP address (/ip_metadata_provider?context=127.0.0.1).

views.py

The views.py script contains the following code:

import json
from app  import app
from flask  import render_template
from flask  import request
from qpylib  import qpylib
 
@app.route( '/ip_metadata_provider', methods=[ 'GET'])
def getIPMetadata():         
     context = request.args.get('context')
  
     metadata_dict = {
          'key' :  'exampleIPMetadataProvider',
          'label' : ' Extra Metadata:',
          'value' :  'Metadata value',
          'html' : render_template( 'metadata_ip.html', ip_address=context)    
                       }

    return json.dumps(metadata_dict)

The views.py file shows a simple implementation for the getIPMetadata REST method that was defined previously in the manifest.json. As noted, the context is passed to the endpoint by a query string. Use the Flask request module to parse out the value of the context query. The value of the context query is parsed by using the script: context = request.args.get('context'). This variable contains the context-specific IP address.

Metadata providers are required to return JSON with the fields that are shown in the following table:

Table 2. Metadata providers fields
Field	Description
key	Unique key for the metadata provider
label	Description of the metadata, which is displayed in a pop-up layer in QRadar.
value	Plain text context-sensitive data to be provided
html	HTML context-sensitive data to be provided.

In this example, a Python dictionary object is created to contain these fields. For the html field, a template file, metadata_ip.html , is created in the /app/templates directory. The context that is retrieved from the query string as the variable ip_address is passed to it.

metadata_ip.html

In this example, you render the context-specific IP address. The metadata_ip.html file contains a Jinja template string that is replaced with the value that is passed in from the render_template call in views.py.

{{  ip_address  }}