.. Security Flow documentation master file, created by
   sphinx-quickstart on Mon Jul  6 11:34:58 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
   Nevelex Labs Proprietary
   Copyright 2020 Nevelex Labs, LLC

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
:class:`~securityflow.SecurityFlow` class.

.. code-block:: python

    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 :class:`~securityflow.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 :func:`~securityflow.SecurityFlow.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:

.. code-block:: python

    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 :func:`~securityflow.SecurityFlow.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:

.. code-block:: python

    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 :func:`~securityflow.SecurityFlow.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:

.. code-block:: python

  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
================

.. automodule:: securityflow
    :members:
    :no-undoc-members:
    :private-members:

External References
===================

.. seealso::
    Module :py:mod:`requests`
        For additional exceptions which may be thrown on any call into the `SecurityFlow` API.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`