Resilient Python SDK

The Resilient Python SDK includes two library modules, and several utility commands. The libraries are:

  • resilient, a utility library for accessing the REST API,
  • resilient-circuits, a framework for developing and running custom functions and actions.

Supported Python versions include 2.7.9 and later, and version 3.4 and later.

The resilient-circuits library requires the resilient library. To install both:

pip install resilient-circuits

Configuration Files

It’s very convenient (although optional) to use a configuration file that holds all the Resilient connection information. The API utilities all use a configuration file if one is available, at a path specified by APP_CONFIG_FILE environment variable, or by default at ~/.resilient/app.config.

Your REST API application code connects to Resilient using HTTPS. This often means that you need to explicitly tell your code how to trust the server’s TLS certificate. Dealing with certificates can be tricky!

To create a new configuration file template for all the required values for your integration:

resilient-circuits config -c

Then edit the configuration file for your own connection details. For example:

[resilient]

host=resilient

port=443

email=api@example.com

password=MySecretPassw0rd

org=Local
cafile=/home/integration/.resilient/serverpubcert.pem
logdir=/tmp

REST API Utilities: gadget and finfo

The gadget utility is a simple wrapper for the Resilient REST API, with commands that can create, read, list, update and search incident data, and access other REST API endpoints. Try gadget --list to see a list of the id and name of each incident.

The finfo utility uses the /types REST API to list the fields and other data-types from your Resilient server. Try finfo without any arguments to see a list of the defined incident fields.

The resilient-circuits Integration Framework

The resilient-circuits framework makes it extremely simple to build and deploy custom integration functions and actions using Python.

The Circuits Framework is a lightweight event-driven and asynchronous application framework for the Python programming language. Circuits also includes a lightweight, high performance and scalable HTTP/WSGI compliant web server as well as various I/O and networking components. The resilient-circuits library uses the Circuits component architecture for Action Processors.

Components

Each component typically performs one or more activities for a single integration. That might be a single function, such as searching for data and returning results, or a collection of methods that work together. Additionally, special-purpose components include polling timers and web services. Components can use the Circuits framework to send messages to each other. A component is a Python class.

Multiple components are collected together into a package that can be easily distributed and installed. A typical package includes at least one Resilient-Circuits component, some configuration settings, and the Python machinery for installing with pip. Additionally, a package can include Resilient customizations such as custom incident fields, datatables, workflows and rules.

When a component is running, the framework takes care of subscribing to message destinations and reading the events as they occur. When an action is triggered in Resilient, from a menu-item or automatic conditions or workflow, the action message is delivered to the framework, which runs the corresponding Python method. The Python method also has ready access to the Resilient REST API.

Components are discovered and loaded automatically when resilient-circuits starts. All the installed packages are loaded from the Python environment. Additionally, any Python file in your local components directory directory will be loaded, and connected to Resilient. In your configuration file (app.config), specify the path to a directory where these local components will be found:

[resilient]

# Directory where any custom Python components will be found
componentsdir=/home/integration/components

The Resilient-Circuits Command Line

To list the Resilient-Circuits packages and components that are installed in your Python environment:

resilient-circuits list

To include the path to each package and the full name of each component:

resilient-circuits list -v

Note: packages in your “local components” directory are not included in this list.

To start the integration framework running:

resilient-circuits run

It will connect to Resilient, find and load your components, and wait. When Resilient calls an integration function, these components will be run. (For production usage, ‘resilient-circuits run’ will usually be started and stopped automatically as a service or daemon).

Optionally you can set the logging level,

resilient-circuits run --loglevel DEBUG

Test Mode

For development, you can run in “test mode”, which allows interactive testing of functions and actions:

resilient-circuits run --test-actions

In a separate terminal, run the test client:

resilient-circuits test

The test client connects to the main resilient-circuits process and allows you to simulate calling functions and action messages.

Creating and Installing Component Packages

The SDK can generate boilerplate code, and package it together with Resilient customizations, to easily create an extension that can be distributed as a Python installer or published to App Exchange. This boilerplate is based on an export. Before running codegen, be sure to create an export with your most recent platform customizations, from Adminstrator Settings –> Organization –> Export.

To generate a single component (in your “components directory”) that provides boilerplate Python code for a function:

resilient-circuits codegen -f func_name

To generate an entire Python package including components, tests, and customization data:

resilient-circuits codegen -p package_name -f func_name_1 funct_name_2... 

Many additional options control the type of customization data that will be included in your package, including custom fields, data tables, workflows, rules, and scripts. Use resilient-circuits codegen --help to see all these options.

To import all these customizations into Resilient:

resilient-circuits customize

The user will be prompted before importing the customizations from each installed package.