Code Snippet Connector v2.0.0

Overview

FortiSOAR™ provides you with a number of pre-installed connectors or built-ins, such as the Code Snippet or Database connectors that you can use within FortiSOAR™ playbooks, as a connector step, and perform automated operations. These connectors are bundled and named based on the type of operations the connectors can perform. For example, the Database connector would contain actions that you can perform with respect to the database like querying the database. It is easy to extend and enhance these connectors.

Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as FortiSIEM, Splunk, etc., and Ticketing systems such as Jira. You can see a list of published connectors on the FortiSOAR Connectors Documentation site.

The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the "Connectors Guide", which is part of the FortiSOAR™ documentation or see the Installing a connector and Configuring a connector articles.

FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. Use the Content Hub to upgrade your connectors to the latest version. For more information on the connector store, see the Introduction to connectors chapter and see the FortiSOAR Built-in connectors article.

Important: Before you upgrade your FortiSOAR™ version, it is highly recommended that you take a backup of your FortiSOAR™ Built-in connector's (SSH, IMAP, Database, etc.) configuration since the configuration of your FortiSOAR™ Built-in connectors might be reset if there are changes to the configuration parameters across versions.

Code Snippet

Use the Code Snippet connector to run a python function as part of playbooks. You can add the "Code Snippet" connector in a playbook as a connector step and execute a python code as part of a playbook.

To configure this connector, click Content Hub (or Connector Store) page, click the Manage tab, and then click the Code Snippet connector card. On the connector popup, click the Configurations tab to enter the required configuration details. For more information, see Configuring the connector.

Using the Code Snippet connector, you can perform any operation on your FortiSOAR system by writing a python function, including functions to manipulate files on the system and run system operations that could enable you to get user login information, Therefore, it is highly recommended to leave the Allow Universal Imports checkbox unchecked (default) so that users can import only a restricted list of python modules, which are specified by the administrators. To use any python module, users are required to include the import statement.

In the Modules to Import field, administrators can specify the list of modules that they want to import. Users can then use these modules, without having to include the import statement in the python code. Note that, in this case, users will not be allowed to import modules that are not part of the list of specified modules.

If administrators do not want to restrict the python modules that users can use, i.e., select the Allow Universal Imports checkbox (not recommended), then in such a case administrators assign ownership of connector configuration by setting a particular configuration to 'Private', allowing administrators to control who can view and execute the particular connector configuration. Setting a connector configuration to 'Private' allows only the assigned team owners to view and execute the connector configuration. The above image displays only one team can execute the 'Default' Configuration of the Code Snippet connector.
Similarly, you can also restrict the roles that are allowed to execute the python code, by clicking the Action tab, and then in the Execute Python Code (and Execute Python Code (Deprecated) row, click the Assign Role(s) to Action icon to display the Assign Role(s) to Action dialog, where you can select the roles that would be able to perform the action. For example, in the following image only the 'Security Administrator' role can run the Execute Python Code action:

In release 2.0.0 of the connector, the Python Function field's interface that is part of the Execute Python Code action has been enhanced to a code text editor making the experience of adding and editing the code more user-friendly.
Important: The enhanced Execute Python Code action is compatible with FortiSOAR release 7.2.1 or later.

To get a better working view and make the editor go full-screen, click the Fullscreen button. To exit the full screen, press ESC.

Prior to release 2.0.0, the Python Function field used to be a text box, which is still available if you select the Execute Python Code (Deprecated) action.

NOTES:

• If the value of the variable that you are defining in the python code is a string, then you must add double quotes. For example:
  description = "{{vars.input.records[0].description | striptag}}"
• If the value of the variable that you are defining in the python code is a dictionary or array, then you can use it without double-quotes. For example:
  description = {{vars.input.records[0].description | striptag}}
• You must add the print statement to the python code. The print statement values can then be provided as an output of the "Code Snippet" connector step and can be consumed by the next playbook step.

In a "Code Snippet" connector step if you need to import a Python library that is not shipped by default with the product, you can install it using the following steps:

1. Import the Python library (custom module).
2. To use the custom module install the custom module in the integrations virtual environment, using the following command:
   sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install <module name>
   For example, if you want to add a module named "whois", use the following command:
   sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install whois

Code Snippet Connector Release Notes

Version 2.0.0

• The interface of the Python Function field that is part of the Execute Python Code action of the Code Snippet connector is enhanced to a code text editor, making the experience of adding and editing code more user-friendly. You add custom python scripts to run within a playbook in the Python Function field.
  Important: The enhanced Execute Python Code action is compatible with FortiSOAR release 7.2.1 or later.

Version 1.2.5

• Enhanced the Code Snippet connector to display the failure trace if there are errors in the code snippet steps, thereby making debugging easier.
• Enhanced the output handling for the Code Snippet connector.
• Updated this connector to be compatible with FortiSOAR Release 7.2.0, i.e., made changes to this connector so that system users running the integrations runtime require only minimal permissions on the file system.
• Enhanced the Code Snippet connector to block the import of OS-related packages (os, sys, subprocess) by default, so that users cannot run arbitrary Python codes that could result in system code execution.
  If users want to allow importing of OS-related packages using the code snippet connector, then they have to customize the /opt/cyops-integrations/integrations/configs/config.ini file by adding the allow_os_packages = true statement in the config.ini file.
  Important: This is a breaking change, i.e., if you have imported OS-related packages using a previous version of the connector in a release prior to FortiSOAR release 7.2.0, the same will be blocked in release 7.2.0.

Version 1.2.4

• Fixed an important security issue and now the Allow All Imports checkbox is not selected by default. For more information about the same, see the Code Snippet section.

Version 1.2.3

• Updated the branding for the Code Snippet connector such as updating the connector publisher to "Fortinet" and updating the names, descriptions, and action names of playbooks based on the branding changes.

Version 1.2.2

• Fixed important bugs such as solving the issue of python dependencies in the earlier versions of the connector, which were causing failures. The connector logo has also been updated in version 1.2.2 of the Code Snippet connector.

Version 1.2.1

• Includes an enhanced log for the Code Snippet connector. Also, the sample playbooks that are shipped with this connector are shipped in the Inactive state. You can activate the playbooks as per your requirement.

Version 1.2.0

• Contains no changes to the functionality of this connector; however, it contains changes to the internal code of this connector.