Overview

The v38.2 release of Resilient SOAR includes the new Python 3 scripting feature which enables security developers to create Python 3 scripts as a part of an incident or case response right in the UI. Scripting in Resilient is not new and until now developers could write scripts using our Python 2 scripting engine. On 1 January 2020, Python 2 officially reached end-of-life. The Resilient implementation of Python 2 is based on a technology called Jython which does remain supported however, the need arose for a more modern runtime to execute scripts.

The newly released python 3 scripting runtime is designed to expose everything that is available with our python 2 implementation as well as exposing some new capabilities which will be discussed throughout this post.

Functionality

Native Unicode Support

No longer need to/nor able to use the unicode() keyword
Note: If you intend to use the unicode keyword in scripts for cross-compatible scripts, consider simply mapping unicode to str

unicode = str

unicode("Test"+"test")

Support for importing more modules

One of the biggest improvements introduced by the new python 3 runtime is the ability to import more modules during script invocation. Previously only 2 modules were exposed in the Python 2 implementation : re and java.util.Date. Importation restrictions do still remain which are covered in the restrictions section. In addition, the Python 3 scripting runtime maintains a list of modules which have been approved for importation in a script.

Supported Modules:

• json
• datetime
• beautifulsoup
• xml
• collections
• html2txt

For a full list visit the knowledge centre

Runtime Restrictions

There are different catagories of restrictions which are enforced on the runtime to minimize the potential for it to be used as a vector in an attack. The mechanisms used to implement the runtime restrictions have been vetted by the IBM Ethical Hacking team during an internal pentesting session.

• Script module importation restrictions: Specific modules are approved and prohibited for use
• Environment restrictions: No network access or access to the file or operating system

The following are additional restrictions which are configurable:

• Time restrictions: 5 seconds per script invocation
• Script length restrictions: 50000 lines per script
• Script memory restrictions: 64MB per script invocation
• Parallel scripts restrictions: 20 scripts limit on parallel execution

Custom classes of Exceptions are raised when one of these restrictions are breached such as a ResilientSecurityException when a script attempt to import a restricted module, a ResilientExecutionLimitException when the script exceeds either the line limit or time restrictions or a ResilientMemoryLimitException when the script exceeds the memory limit.

Experience

Differentiation between python 2 and 3 scripts

Improved Logging and Debugging information

The UI script result window, logs and modals which showed for rules now includes a stack trace which has been modified to hide the location of the file system while still giving a trace of the issue to help track down the source of an exception. Exception tracebacks in the python 3 runtime include a reference to where the error happened in the script as well as a trace of calls which led to the error.

Logging for the scripting service now includes more statistics for each script invocation such as the time the script took to run, the CPU time usage for the script, the RAM usage for the script and also the number of lines executed by the script. The last statistic excludes lines executed in modules to better track how much of the user defined script was executed.

Repository of sample scripts

Provided on our public Github organisation is a revamp to the resilient-scripts repository. This revamp includes scripting examples for the new python 3 scripting feature to give examples of how to use the new features.

Visit the example script repository for some examples to get started.

In-product scripting UI updates, help and examples

Python 2 is currently still supported by in-product scripting and while Python 3 is now the default for new scripts it remains possible to use Python 2 and change the type between 2 and 3 at will. Scripts created in either Python 2 or 3 now coexist on the Scripts page and are differentiated by a newly exposed UI colum which shows the scripts language. Additionally a help link is exposed on the Scripts page which links to the repository of sample scripts referenced above.

Updating the Script Language for a script can be done from the script editor page when editing a script where a dropdown select option is exposed for the Language field in the script editor.

Getting started with in-product scripting in either python 2 or 3 requires some knowledge of how the feature represents an incident or a task with the use of context objects. The knowledge centre is the location where much of the Resilient and Cloud Pack for Security information is stored. This includes resources for in-product scripting on the feature itself, the use of scripting context objects and their exposed methods. The Scripts page in the customization settings now includes a link to the knowledge centre with a focus on in-product scripting information.

Conclusion

The new Python 3 scripting runtime enables security developers to use a more modern and supported version of python as a part of their response plan. As of v38.2 you should be able to avail of the python 3 scripting option when you create a new script or edit an existing one.

Special Thanks to Bastian Graebener for his help in preparing the blog.