Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Communicating with JSA Hosts from Python

 

You can communicate with JSA Hosts from Python by using the REST endpoints that JSA exposes.

  1. JSA-USER--This header contains the JSA user name.

  2. JSA-USER-ROLE--This header contains the user role assigned to the user.

  3. JSA-SECURITY-PROFILE--This header contains the security profile that defines which networks, log sources, and domains that the user can access

Qpylib Library

The qpylib library provides functions that encapsulate much of the logic that is required to initiate this communication.

For REST API calls, use the qpylib.REST(RESTtype, request_url, headers, data, json, params, version) function. This function prepends the IP address of the host console to the request URL.

This REST function acts as a wrapper for the Python requests library. It returns a requests.Response object.

The following table describes the fields that you can access from this object:

Table 1: Response Fields

Field Name

Description

status_code

Status code for the response. Useful for determining the success of a request. For example, if you are checking for a 200 response.

url

URL of the request.

headers

Dictionary object that contains the response headers.

text

Raw text output of the response. Useful for debugging purposes.

The function parameters are explained in the following table:

Table 2: Function Parameters

Parameter Name

Explanation

RESTtype

String REST request type. Accepts 'GET', 'PUT', 'POST' and 'DELETE'.

request_url

URL of the REST endpoint. The qpylib library prepends the appropriate console IP address to the URL so that only the URL from /api/ is needed. For example: /api/gui_app_framework/applications.

headers (optional)

Optional headers to be added to the request. Headers must be contained within a Python dictionary object, for example, {'Accept': 'application/json'}.

data (optional)

Optional data that can be contained within a request's body. Data must be in the format that is appropriate to the REST endpoint. For example, data must be converted to a JSON string by using the JSON Python library (json.dumps()) when a REST endpoint accepts application/json.

json (optional)

Optional parameter that accepts Python dictionary objects that are converted to a JSON String that is included in the request's body.

params (optional)

Optional parameter that accepts Python dictionary objects that are converted to URL query parameters.

version (optional)

Optional parameter that specifies which version of the JSA RESTful API to use. The value must be a string that matches a supported version of the JSA RESTful API (for example, 5.0). If no version is specified, no version header is sent and the most recent version is used by default.

The Response object also contains functions that simplify access to the data contained in the response body. You can use the json() function to retrieve a dictionary object that contains the response body, or a list of dictionary objects if the endpoint returns a collection.

Example: Get JSA Offenses

import qpylib offenses_endpoint = '/api/siem/offenses' headers = {'content-type' : 'application/json'} response = qpylib.REST('GET', offenses_endpoint, headers=headers) offenses_json_list = response.json() # List containing dictionary objects for each JSA offense # Iterate over each offense JSON in the list and print its id. format_string = 'Found offense id [{0}].' for offense_json in offenses_json_list: offense_id = str(offense_json['id']) # Access fields print(format_string.format(offense_id))

Example: Get JSA Offenses With Queries

import qpylib offenses_endpoint = '/api/siem/offenses' headers = {'content-type' : 'application/json'} params= { 'filter' : 'inactive=false' } response = qpylib.REST('GET', offenses_endpoint, headers=headers, params=params) offenses_json_list = response.json()

Example: Post JSA Offense Closing Reason

import qpylib offense_closing_reasons_endpoint = '/api/siem/offense_closing_reasons' headers = {'content-type' : 'application/json'} json_dict = { 'reason' : 'Demonstrating posting data to JSA'} response = qpylib.REST('POST', offense_closing_reasons_endpoint, headers=headers, json=json_dict)