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.