IBM Support

Named Services

How To


Summary

A named service is a feature that allows other apps and parts of the QRadar UI to interact with an app. These named services can fit a variety of use-cases, including:

A background process exposing HTTP endpoints to query, such as a NodeJS express server.
A background process that does work within an app container without exposing endpoints.
Standard Flask endpoints grouped as a named service to allow them to be queried.

This page will explain how an app can interact with named services, which QRadar UI elements can make use of named services, and some notes on best practices with named services.

Steps

Interacting With a Named Service

Named services can be called by using a URL to direct to the named service. There are two methods for building a URL that will route a request to a named service.

Directly Using Named Service of an App

URL built using app ID and named service name:

https://<console_ip>/console/plugins/app_proxy:<app_id>:<named_service_name>/<endpoint>

This explicitly calls the named service on a specific app. This requires prior lookup of the app ID.

This method can be used with QPyLib:

from qpylib import qpylib

# These values could be fetched from somewhere
app_id = 1001
named_service = 'test_named_service'
endpoint = 'my_endpoint'

response = qpylib.REST('GET', '/console/plugins/app_proxy:{0}:{1}/{2}'.format(app_id, named_service, endpoint))

Using QRadar to Perform App Lookup of Named Service

URL built using only the named service name, letting QRadar look up an app that provides it:

https://<console_ip>/console/plugins/app_proxy:<named_service_name>/<endpoint>

This is implicitly fetching the app to query for a named service, QRadar will handle this lookup and use the first app that provides a matching named service.

This method can be used with QPyLib:

from qpylib import qpylib

named_service = 'test_named_service'
endpoint = 'my_endpoint'

response = qpylib.REST('GET', '/console/plugins/app_proxy:{0}/{1}'.format(named_service, endpoint))

QRadar UI and Named Services

Named services can be called from different parts of the QRadar UI, allowing an app to be integrated across different parts of QRadar.

Areas

An area can be set up to use a named service to populate page data:

"areas": [
    {
        "id": "AreaUsingNamedService",
        "text": "Area Using a Named Service",
        "description": "Area that uses 'custom_named_service' named service to populate itself",
        "url": "/custom_endpoint",
        "required_capabilities": [],
        "named_service": "custom_named_service"
    }
]

This uses the custom_named_service named service to provide page data from the /custom_endpoint endpoint.

REST Methods

REST methods can configured to route to named services:

"rest_methods": [
    {
        "name": "custom_endpoint",
        "url": "/custom_endpoint",
        "method": "GET",
        "named_service": "custom_named_service"
    }
]

This uses the custom_named_service named service to provide a data for a REST method under the /custom_endpoint endpoint.

Configuration Pages

Configuration pages can be populated by using a named service:

"configuration_pages": [
    {
        "text": "Config Page Using Named Service",
        "description": "Config Page that uses 'custom_named_service' named service to populate itself",
        "url": "/custom_endpoint",
        "required_capabilities": [],
        "named_service": "custom_named_service"
    }
]

This uses the custom_named_service named service to provide page data from the /custom_endpoint endpoint.

GUI Actions

Named services can be used with GUI actions in two ways. The first is to use the named service to load the GUI action icon:

"gui_actions": [
    {
        "id": "NamedServiceRightClickIP",
        "text": "Icon from named service",
        "description": "Test right click with icon loaded from named service",
        "icon": "static/images/icon_from_named_service.png",
        "javascript": "alert('Right clicked IP!')",
        "groups": [
            "ipPopup"
        ],
        "required_capabilities": [],
        "named_service": "custom_named_service"
    }
],

This uses the custom_named_service named service to handle loading the icon_from_named_service.png icon for a right click menu option when an IP is right clicked.

The second use of named services with GUI actions is to use a REST method alongside a GUI action, allowing a request to be sent to the REST method when the action is done:


"rest_methods": [
    {
        "name": "EndpointForRightClick",
        "url": "/endpoint_for_right_click_action",
        "method": "GET",
        "named_service": "custom_named_service"
    }
],
"gui_actions": [
    {
        "id": "NamedServiceRightClickIP",
        "text": "Trigger named service",
        "description": "Test right click that calls an endpoint behind a named service",
        "rest_method": "EndpointForRightClick",
        "javascript": "alert(result)",
        "groups": [
            "ipPopup"
        ],
        "required_capabilities": []
    }
]

This sets up a REST method called EndpointForRightClick that uses the custom_named_service named service to provide the /endpoint_for_right_click_action endpoint. A GUI action NamedServiceRightClickIP is defined that uses this REST method which is triggered when this right click option is selected, with some JavaScript to print out the response from the REST method endpoint.

Page Scripts

Page scripts can be loaded by using a named service:

"page_scripts": [
    {
        "app_name": "SEM",
        "page_id": "OffenseList",
        "scripts": [
            "/static/js/script_1.js",
            "/static/js/script_2.js"
        ],
        "named_service": "custom_named_service"
    }
]

This loads two scripts, /static/js/script_1.js and /static/js/script_2.js, from the named service custom_named_service in the QRadar UI on the offenses page.

Fragments

Page scripts can be populated by using a named service:

"fragments": [
    {
        "app_name": "SEM",
        "page_id": "OffenseList",
        "location": "header",
        "rest_endpoint": "/custom_endpoint",
        "named_service": "custom_named_service"
    }
]

This uses the custom_named_service named service to provide page data from the index endpoint for a fragment in the QRadar UI on the header of the offenses page.

Custom Columns

Custom columns can be populated by using a named service:

"custom_columns": [
    {
        "app_name": "SEM",
        "page_id": "OffenseList",
        "label": "Custom Column Using Named Service",
        "rest_endpoint": "/custom_endpoint",
        "named_service": "custom_named_service"
    }
]

This uses the custom_named_service named services to provide page data from the index endpoint for a custom column on the offense list table in the QRadar UI.

Document Location

Worldwide

[{"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":"a8m0z000000cwt3AAA","label":"QRadar Apps"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)"}]

Document Information

Modified date:
30 March 2021

UID

ibm16437515