resilient-sdk

Python SDK for developing Apps for IBM SOAR

Installation

To install the IBM SOAR SDK, execute the following command:

$ pip install resilient-sdk

Configuration

Similar to our resilient-circuits library, the SDK it requires an app.config created in the default location: ~/.resilient with the following minimum configurations:

[resilient]
host=my_soar_instance.ibm.com
org=Test Organization
api_key_id=<id>
api_key_secret=<secret>
cafile=false

Note

Commands that interact with the SOAR platform support the --config|-c argument, which precedes the default location. For example:

$ resilient-sdk clone -r "Display name of Rule" "Cloned Rule display name" -c path/to/my/custom_file.config

Using the SDK

Python SDK for developing IBM SOAR Apps that provides various subcommands to help with development

usage:
$ resilient-sdk <subcommand> ...
$ resilient-sdk -v <subcommand> ...
$ resilient-sdk codegen -p <name_of_package> -m 'fn_custom_md' -c '/usr/custom_app.config'
$ resilient-sdk -h

options:
-h, --help			show this help message and exit
-v, --verbose			Set the log level to DEBUG

codegen

Generates boilerplate code used to begin developing an app.

usage:
$ resilient-sdk codegen -p <name_of_package> -m 'fn_custom_md' --rule 'Rule One' 'Rule Two' -i 'custom incident type'
$ resilient-sdk codegen -p <name_of_package> -m 'fn_custom_md' -c '/usr/custom_app.config'
$ resilient-sdk codegen -p <path_current_package> --reload --workflow 'new_wf_to_add'
$ resilient-sdk codegen -p <path_current_package> --gather-results
$ resilient-sdk codegen -p <path_current_package> --gather-results '/usr/custom_app.log' -f 'func_one' 'func_two'

options:
-h, --help			show this help message and exit
-a, --artifacttype		API names of artifact types to include 
-d, --datatable			API names of datatables to include 
-f, --function			API names of functions to include 
-fd, --field			API names of custom fields to include 
-i, --incidenttype		Display names of custom incident types to include (surrounded by "") 
-m, --messagedestination	API names of message destinations to include 
-pb, --playbook			API names of playbooks to include. Only SOAR >= v44.0 supported 
-r, --rule			Display names of rules to include (surrounded by "") 
-s, --script			Display names of scripts to include (surrounded by "") 
-t, --task			API names of custom tasks to include 
-w, --workflow			API names of workflows to include 
-e, --exportfile		Path to a local (.res or .resz) export file 
-o, --output			Path to output directory. Uses current dir by default 
-c, --config			Path to app.config file. Default is ~/.resilient/app.config 
-p, --package			(required) Name of new or path to existing package 
-re, --reload			Reload customizations and create new customize.py 
--gather-results		Uses the log file specified or if no path specified use the default at '~/.resilient/logs/app.log' to try gather results. Only Python >= 3.6 supported

docgen

Generates boilerplate documentation for an app.

usage:
$ resilient-sdk docgen -p <path_to_package>

options:
-h, --help			show this help message and exit
-p				Path to the package containing the setup.py file

package

Package your Python Package into a SOAR app format.

usage:
$ resilient-sdk package -p <path_to_directory>
$ resilient-sdk package -p <path_to_directory> --display-name "My Custom App"
$ resilient-sdk package -p <path_to_directory> --repository-name "ibmresilient" --image-hash "dd2a1678b6e0..."
$ resilient-sdk package -p <path_to_directory> --keep-build-dir --display-name "My Custom App"
$ resilient-sdk package -p <path_to_directory> --validate

options:
-h, --help			show this help message and exit
-p, --package			(required) Path to the directory containing the setup.py file 
--keep-build-dir		Do not delete the dist/build directory 
--display-name			Display name to give the app 
--repository-name		Name of the repository which contains the app container 
--image-hash			The SHA256 hash of the container image to pull for this App 
--no-samples			Do not look for the payload_samples directory or try add them to the export.res file 
--validate			Run the 'validate' command and generate the validation report to include in packaging

clone

Duplicate an existing Action related object (Function, Rule, Script, Message Destination, Workflow) or Playbook with a new api or display name

usage:
$ resilient-sdk clone --workflow <workflow_to_be_cloned> <new_workflow_name>
$ resilient-sdk clone --workflow <workflow_to_be_cloned> <new_workflow_name> --changetype artifact
$ resilient-sdk clone -pb <playbook_to_be_cloned> <new_playbook_name>
$ resilient-sdk clone -pb <playbook_to_be_cloned> <new_playbook_name> --draft-playbook
$ resilient-sdk clone --playbook <playbook_to_be_cloned> <new_playbook_name> --changetype artifact
$ resilient-sdk clone -f <function_to_be_cloned> <new_function_name>
$ resilient-sdk clone -r "Display name of Rule" "Cloned Rule display name"
$ resilient-sdk clone -s "Display name of Script" "Cloned Script display name"
$ resilient-sdk clone -s "Display name of Script" "Cloned Script display name" --changetype task
$ resilient-sdk clone -pre version2 -r "Display name of Rule 1" "Display name of Rule 2" -f <function_to_be_cloned> <function2_to_be_cloned>

options:
-h, --help			show this help message and exit
-c, --config			Path to app.config file. Default is ~/.resilient/app.config 
-f, --function			API names of functions to include 
-m, --messagedestination	API names of message destinations to include 
-pb, --playbook			API names of playbooks to include. Only IBM SOAR >= v44.0 supported 
--draft-playbook		If specified with the '--playbook' option will clone the Playbook into a Draft state, allowing you to change it's Activation Type. Only IBM SOAR >= v44.0 supported 
-r, --rule			Display names of rules to include (surrounded by "") 
-s, --script			Display names of scripts to include (surrounded by "") 
-w, --workflow			API names of workflows to include 
-pre, --prefix			The prefix to be placed at the start of cloned Action Objects. Used when cloning more than 1 of each Action Object Type. 
-type, --changetype		The new type of the clone action object. Used when cloning a workflow or script to have the newly cloned workflow at a different object type.

extract

Extract data in order to publish a .res export file

usage:
$ resilient-sdk extract -m 'fn_custom_md' --rule 'Rule One' 'Rule Two'
$ resilient-sdk extract --script 'custom_script' --zip
$ resilient-sdk extract --script 'custom_script' --zip -c '/usr/custom_app.config'
$ resilient-sdk extract --script 'custom_script' --name 'my_custom_export'

options:
-h, --help			show this help message and exit
-a, --artifacttype		API names of artifact types to include 
-d, --datatable			API names of datatables to include 
-f, --function			API names of functions to include 
-fd, --field			API names of custom fields to include 
-i, --incidenttype		Display names of custom incident types to include (surrounded by "") 
-m, --messagedestination	API names of message destinations to include 
-pb, --playbook			API names of playbooks to include. Only SOAR >= v44.0 supported 
-r, --rule			Display names of rules to include (surrounded by "") 
-s, --script			Display names of scripts to include (surrounded by "") 
-t, --task			API names of custom tasks to include 
-w, --workflow			API names of workflows to include 
-e, --exportfile		Path to a local (.res or .resz) export file 
-o, --output			Path to output directory. Uses current dir by default 
-z, --zip			Generate a .zip of the generated file 
-c, --config			Path to app.config file. Default is ~/.resilient/app.config 
-n, --name			Name to prepend to generated file

validate

Tests the content of all files associated with the app, including code, before packaging it

usage:
$ resilient-sdk validate -p <name_of_package>
$ resilient-sdk validate -p <name_of_package> -c '/usr/custom_app.config'
$ resilient-sdk validate -p <name_of_package> --validate
$ resilient-sdk validate -p <name_of_package> --tests
$ resilient-sdk validate -p <name_of_package> --tests --tox-args resilient_password="secret_pwd" resilient_host="ibmsoar.example.com"
$ resilient-sdk validate -p <name_of_package> --tests --settings <path_to_custom_sdk_settings_file>
$ resilient-sdk validate -p <name_of_package> --pylint --bandit --selftest

options:
-h, --help			show this help message and exit
-c, --config			Path to app.config file. Default is ~/.resilient/app.config 
--settings			Path to .sdk_settings.json file. Default is ~/.resilient/.sdk_settings.json 
-p, --package			(Required) Path to existing package 
--validate			Run validation on package files. No dynamic checks. 
--tests				Run tests using package's tox.ini file in a Python 3.6 environment (if 'tox' is installed and tox tests are configured for the package) 
--pylint			Run a pylint scan of all .py files under package directory. 'pylint' must be installed) 
--bandit			Run a bandit scan of all .py files under package directory. 'bandit' must be installed) 
--selftest			Validate and run the selftest.py file in the package directory. 'resilient-circuits' and the package must be installed in Python environment) 
--tox-args			Pytest arguments to pass to tox when validating tests. Format is <attr1>="<value>". Example: '--tox-args my_arg1="value1" my_arg2="value2"'

Usage

Run validate without any options to:

  1. Verify that App files conform to our latest standard

  2. Test that resilient-circuits starts and that the App’s selftest passes

  3. Run any unit tests found with tox (if installed)

  4. Run a pylint scan (if installed) using our defined pylint config file

  5. Run a bandit scan (if installed) to identify any common security issues

  • To ensure that all files in your App conform to our latest standard, run:

$ resilient-sdk validate -p <path_to_package> --validate

  • To perform basic testing of the App, run:

$ resilient-sdk validate -p <path_to_package> --selftest

  • validate also has the ability to accept an app.config file in any location. For example:

$ resilient-sdk validate -p <path_to_package> --selftest -c '/usr/custom_app.config'

  • Once completed, a Markdown summary file is added to the dist directory and included in the .zip file when packaged

Note

You can run each validation individually by specifying its related option.

Change Log

2022-07: version 45.1

  • No major changes. Just bumping build number to coincide with other builds

2022-05: version 45.0

  • Added new option --draft-playbook to the clone command that if specified with the --playbook option will clone the Playbook into a Draft state, allowing you to change it’s Activation Type

  • codegen and extract now exclude the creator from the generated export.res file

  • Minor updates to templates produced with codegen

2022-04: version 44.1

  • No major changes. Just bumping build number to coincide with other builds

2022-02: version 44.0

  • Added support to codegen, docgen, package, extract and clone for Playbooks

  • Bump Jinja2 to ~=3.0 for Python >=3.6

  • Officially support Python 3.9

2022-01: version 43.1

  • Added new validate functionality to the SDK

  • Added genson 1.2 dependency to generate JSON schemas

  • codegen now produces output_json_example.json and output_json_schema.json files for each function in the payload_samples directory to aid with building Playbooks

  • codegen has a new argument --gather-results which will scan an app.log file to get the results for the output_json_example.json file

  • When docgen is now ran, it will look for an output_json_example.json file for each function and use that for the README.md Function Output Examples

  • Added global-exclude *.bak to the MANIFEST.in file in the codegen template so .bak files are not included when packaged

2021-11: version 43.0

  • Added examples to codegen template

  • Formatted Sphinx documentation and hosted it at https://ibm.biz/soar-python-docs

  • A packaged App will now include additional files with additions to the MANIFEST.in file

2021-11: version 42.3

  • Enforce unix style line endings (\n) when writing files

  • codegen to include apikey_permissions.txt in MANIFEST.in file

2021-10: version 42.2

  • Bug fix for clone to support Python 2.7

  • Ability to use different app.config file per command using -c flag

2021-08: version 42.1

  • No major changes. Just bumping build number to coincide with other builds

2021-08: version 42.0

  • codegen now generates a template for App’s to be developed to run in a Python >= 3.6 environment.

  • Bug fixes.

  • Support for collecting incident types in codegen and extract. See the command line parameters -i and --incidenttype.

2021-06: version 41.1

  • To address a security vulnerability, the Dockerfile codegen template now assigns user 1001 to the non-root group 1001. User 1001 is used to run a container.

  • Added a new Atomic Function template generated with codegen, which is a condensed version of our Original Function template. It includes comments on best practices.

2021-05: version 41.0

  • List all setup.py "install_requires" dependencies in docgen README template

  • Bug fixes

2021-03: version 40.2

  • Bug fix for to use setuptools_scm < 6.0.0 for Python 2.7 environments

2021-03: version 40.1

  • Adjust entrypoint.sh template to ensure resilient-circuits is restarted when a fatal error occurs when running on App Host

  • Added timestamp to logs on App Host

2021-02: version 40.0

  • The function template that is produced when you run codegen now includes references to the resilient-lib library.

  • When the var RES_SDK_DEV is set, codegen now creates the payload_samples directory with JSON examples for the Resilient UI and mock results for a “mock server”.

  • Added --no-samples flag to package and when set do not look for the payload_samples directory or try add them to the export.res file.

  • Added --image-hash flag to package to specify the SHA256 of an image that the app.zip refers to.

2020-10: version 39.0

  • The docgen command creates a single README and updated the README to include information on App Hosts.

  • Added the Resilient platform version to the customize.py template.

  • The package command replaces tags on Resilient objects in export.res instead of extending them.

  • Added environmental variable RES_SDK_DEV.

  • Added --set-version argument to the dev command.

  • Added display_name attribute to the setup.py file.

  • The codegen, codegen --reload and dev --set-version commands create a /util/data/export.res file that contains the import definition which was previously base64 encoded text in customize.py.

  • Before running the codegen --reload on packages created with Resilient SDK < 39.0.0, ensure the MANIFEST.in file includes the line: recursive-include <package_name>/util *

  • The codegen and package commands return errors if the package name contains uppercase characters.

  • Added a clone command to clone an Action Object.

2020-07: version 37.2

  • Updates to Dockerfile template

  • Support for newest export formats

  • Bug fixes.

2020-05: version 37.0

  • Package created. Using 37 as original version

  • Added support for API key permissions in app.json using permissions file.

  • Added support for new apphost config section.

  • Customization and config properties files now extracted from setup.py.

  • Rename app:package command to package.

  • Bug fixes.

2020-04: version 36.2.dev

  • Package dev version created. Using 36.2 as original version

  • Added support for API key permissions in app.json using permissions file.

  • Added support for new apphost config section.

  • Customization and config properties files now extracted from setup.py.

  • Rename app:package command to package.

  • Bug fixes.