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.
Native Unicode Support
No longer need to/nor able to use the
Note: If you intend to use the unicode keyword in scripts for cross-compatible scripts, consider simply mapping
unicode = str
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 :
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.
For a full list visit the knowledge centre
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.
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.
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.