Security Flow’s NL-Python Programming Guide

Documentation of the SecurityFlow class API and supporting enums, classes, and exceptions. These capabilities are available to scripts defined within the NL-Python node.

Importing

Like any Python script, importing of modules is allowed. If a module is needed to be into the virtual environment, the Security Flow Settings screen provides a mechanism for installing packages from PyPi, the Python Package Index.

The following example illustrates importing the requests module. This module is installed by default because it is needed by the SecurityFlow class.

import requests

def sfEntryPoint( arg ):
  return arg

Script Globals

Within the context of the NL-Python node, the following global variables exist.

  • securityflow - An instance of the SecurityFlow class.

  • SF_MSG_ID - The _msgid of the message which triggered the script execution.

  • SF_FLOW_ID - The flow ID of the tab containing the NL-Python node.

  • SF_NODE_ID - The ID of the NL-Python node.

  • SF_NODE_NAME - The name of the NL-Python node.

SecurityFlow Examples

Retrieve Plugin Instance’s Configuration

The getPluginInstanceConfig() method provides a mechanism for retrieving the configuration, including the Oauth2 access token, of a Plugin Instance. This is intended to be used to access the Plugin Instance outside of the standard nodes provided by a Plugin.

A configuration entry is defined as follows (notation is based on Typescript):

{
  [key: string]: [string | boolean | number]
}

There are a few standard key names to expect within a configuration entry. Not all of these are available to any particular Plugin Instance.

  • uniqueId - The unique ID of the Plugin Instance.

  • authorization - The OAuth2 access token.

  • hostname - The host name or IP address for the service.

  • port - The port for connecting to the service.

  • username - The user name for accessing the service.

  • password - The password for accessing the service.

The following script illustrates how to retrieve a configuration and create a basic auth GET request:

import requests

def sfEntryPoint( arg ):
  '''
  Returns the response from a request.
  '''
  if not arg:
    raise Exception( 'No argument provided' )
  # Make a basic auth request
  # You should perform validation to ensure config parameters exist.
  config = securityflow.getPluginInstanceConfig( uniqueId = 'plugin1' )
  auth = (config['username'], config['password'])
  uri = f"https://{config['hostname']}:{config['port']}/restapi/request_endpoint"

  return requests.get(uri, auth=auth, params=arg, timeout=20)

Adding a Note

The addNote() method provides a mechanism for adding a note to the Incident’s timeline.

The following script illustrates how to add a note to the Incident’s timeline:

def sfEntryPoint( arg ):
  '''
  Basic echo script.
  '''
  if not arg:
    raise Exception( 'No argument provided' )
  # Add a Note
  securityflow.addNote( 'This is my new note.' )
  return arg

Adding a Message Audit

The addMessageAudit() method provides a mechanism for adding an audit message to the Incident’s timeline.

The following script illustrates how to add audit messages to the Incident’s timeline:

def sfEntryPoint( arg ):
  '''
  This script records some information which isn't returned
  by the final result.
  '''
  if not arg:
    raise Exception( 'No argument provided' )

  # Add an informational message
  securityflow.addMessageAudit( AuditCode.INFORMATION, 'About to perform some operations.' )

  try:
    # Do something here to get some interim data.
    updates = { 'info': 'the changes from doing something'}
    # Add an update message  This is simply to add a JSON message into the timeline.
    securityflow.addMessageAudit( AuditCode.UPDATE, 'Interim state information.', msgDiff=updates )
    # Do something else to get additional data.
    final = { 'finsihed': 'the final data' }
  except Exception as ex:
    # Add an error message
    securityflow.addMessageAudit( AuditCode.ERROR, 'This is an error message. {}'.format( str( ex ) ) )
    raise ex

  return final

SecurityFlow API

class securityflow.AuditCode(value)

Availability audit operations to add to an incident.

ERROR = 'ERROR'

Add an error message to the Incident timeline.

INFORMATION = 'INFORMATION'

Add an informational message to the Incident timeline.

UPDATE = 'UPDATE'

Add an update message to the Incident timeline. This audit operation requires a message difference.

exception securityflow.DbRequestError(*args, **kwargs)

Some type of unexpected database error for the requested operation.

exception securityflow.ExtraFieldError(*args, **kwargs)

An extra field error is thrown when the operation supplied an extra field which is not needed for the requested operation.

exception securityflow.InvalidAuditCodeError(*args, **kwargs)

The audit code was not supported.

exception securityflow.MissingFieldError(*args, **kwargs)

A missing field error is thrown when the operation fails failed to supply all the required fields.

exception securityflow.SearchError(*args, **kwargs)

A search error is thrown when the operation fails to find a matching incident based on the supplied search value.

class securityflow.SecurityFlow(msgid, flowId, nodeId, nodeName)
Utility class to access Security Flow RESTful APIs to

  • retrieve Plugin Instance Configuration information.

  • create a note in an Incident timeline.

  • add message log entries in an Incident timeline.

_processResponse(response)

Processes the returned response.

Parameters

response (requests.Response) – The response object to analyze.

Returns

the dict on success containing the parsed JSON response, if the operation returns a value.

Return type

dict or None

Raises

  • ValueError – If the response’s error code was unknown or the response wasn’t JSON for non-create operations.

  • requests.HTTPError – If the response was an HTTP error code without a corresponding error code.

  • MissingFieldError – If the response indicated there were missing fields in the request.

  • ExtraFieldError – If the response indicated there were extra fields in the request.

  • SearchError – If the response indicated the search to located the target object to update failed.

  • DbRequestError – If the response indicated there was a database response error.

addMessageAudit(audit, description, msgDiff=None)

Creates a new note in the incident’s timeline.

Parameters

  • audit (AuditCode) – One of the AuditCode operations.

  • description (str) – The message to describe the audit operation.

  • msgDiff (dict or None) – The change to the message. Required if the audit value is AuditCode.UPDATE.

Raises

TypeError – If the audit operation is not an AuditCode or if the message diff is not type dict when required.

Raises

See _processResponse(): for additional exceptions which may be thrown.

addNote(note)

Creates a new note in the incident’s timeline.

Parameters

note (str) – The note to add. Limited to 1024 characters.

Raises

TypeError – If the note is not a str.

Raises

See _processResponse(): for additional exceptions which may be thrown.

getPluginInstanceConfig(id=None, uniqueId=None, friendlyName=None)

Returns the plugin configuration information for the Plugin Instance identified by one of id, uniqueId, or friendlyName. Only one parameters should be set.

On success, this method returns an array of configuration values. A configuration entry is defined as follows (notation is based on Typescript):

{
  [key: string]: [string | boolean | number]
}

There are a few standard key names to expect within a configuration entry. Not all of these are available to any particular Plugin Instance.

  • uniqueId - The unique ID of the Plugin Instance.

  • authorization - The OAuth2 access token.

  • hostname - The host name or IP address for the service.

  • port - The port for connecting to the service.

  • username - The user name for accessing the service.

  • password - The password for accessing the service.

Parameters

  • id (int) – The ID number of the Plugin Instance.

  • unqiueId (str) – The unique ID string for the Plugin Instance.

  • friendlyName (str) – The friendly name string of the Plugin Instance. There is no rule enforcing uniqueness of a friendly name.

Returns

A dict of all the configuration entries for the Plugin Instance.

Return type

dict

Raises

See _processResponse(): for additional exceptions which may be thrown.

exception securityflow.SfBaseException(*args, **kwargs)

Base exception class. Sole purpose is to remove kwargs before calling the Exception class.

External References

See also

Module requests

For additional exceptions which may be thrown on any call into the SecurityFlow API.

Indices and tables