FortiSOAR Rapid Development Kit v3.0.0

FortiSOAR Rapid Development Kit

Use the FortiSOAR Rapid Development Kit (RDK) to efficiently create third-party integrations (connectors) and other utility code snippets for FortiSOAR. This add-on simplifies the process of the following:

• Creating a new FortiSOAR connector for a third-party product.
• Importing an existing FortiSOAR-compatible connector and then making updates or changes to the connector.
• Developing code snippets that can be used in FortiSOAR playbooks to perform advanced operations or logical manipulations.

Version information

FortiSOAR Rapid Development Kit Version: 3.0.0

PyCharm Version Tested on: 2024.1 and later.

For issues with Python 3.12 and PyCharm 2022.2 through 2023.1, refer to the Troubleshooting section.

Authored By: Fortinet

Certified: Yes

Release Notes

The following enhancements have been made to the FortiSOAR RDK:

• We've used PyCharm's Python Run and Debug configuration for a connectors' operation and configuration. The Run and Debug configurations are available as buttons on the PyCharm dock. Each connector appears as an expandable folder and has two configurations — one for connector health check and another for various connector operations.
• Under the Home tab, the Update Python Path contains the Python environment for PyCharm's Python Run and Debug configuration.
• Now, the configuration and operations input fields dynamically adjust according to changes in another argument with OnChange enabled.
• A new multi-select input field can now be used for configuration or operation parameters that requires selection of multiple values.
• Changed Input Dialog title from FortiSOAR Connector to FortiSOAR RDK.
• When importing connectors, the info.json file now opens automatically, by default. This streamlines the process and provides quick access to essential connector information.
• Clicking Configure Python Path from the RDK home page now has a smart behavior. If the Python path is empty, the default Python path from the project environment is loaded seamlessly.
• We've applied the sleek FortiSOAR theme to the dialog inputs for both Create New Connector and Update Python Path. Now your interactions with these features are not only functional but visually appealing.
• If no configuration is required for a particular connector, a user-friendly message appears:

  No Configurations required for this Connector.

  This note is available for both the Config and Execute tabs.

• We've removed the pillow and pytest libraries from the RDK engine during installation using the Configure Python Path button on the Home Page. This ensures a cleaner and more efficient setup. The Configure Python Path option is available only during the first-time setup.
• The Run button has been retired from Check Health and other operations. Instead, the Python run/debug configurations are available for seamless execution. To create a Python run/debug configuration, simply click the Save button.

Installing the FortiSOAR Rapid Development Kit

To install the FortiSOAR RDK for the first time, follow these steps:

1. Download the FortiSOAR RDK fortisoar-rdk-pycharm-3.0.0-89 (Also attached at the end of this document).
2. Open your PyCharm utility (v2024.1) and select Plugins.
3. Select the option Install Plugin from Disk.
4. In the Choose Plugin File dialog, navigate to where the FortiSOAR RDK zip file is located on your system, and select it.
5. Click Apply and then OK to begin installing the FortiSOAR RDK.
6. Configure the Python path to install the latest dependencies. For more information, see the Configuring the Python path topic.

Upgrading the FortiSOAR Rapid Development Kit

To upgrade the FortiSOAR RDK, apart from performing steps in the preceding section, consider the following:

For more information, see Configuring the Python path.

1. Click the Restart IDE button, after installation of the zip file, to restart the PyCharm IDE and upgrade FortiSOAR RDK.
2. Update the Python path to install the latest dependencies.

Configuring the Python path

Before you begin working on creating connectors or updating existing connectors, ensure that the Python path of your project is correctly configured.

1. Click FortiSOAR RDK from the Tool Bar Menu.
2. Click Update Python Path, if you have previously configured Python.

   NOTE: The Update Python Path appears as Configure Python Path for first-time setup.

3. Specify the Python installation path, or navigate to the path where Python is installed.
4. Click OK.

The following image shows the screen when configuring Python path for first time use:

After the installation of FortiSOAR RDK completes, the FortiSOAR RDK option in the Main Menu and Tool Window on the right sidebar appears, as shown in the following image:

Actions supported in FortiSOAR Rapid Development Kit

Open your project and click the FortiSOAR RDK option from the Tool Window on the right sidebar to perform the following actions using the FortiSOAR add-on:

• Create a new FortiSOAR connector
• Import an existing FortiSOAR connector
• Configure Python Path

Using the FortiSOAR RDK option from the Main Menu you can perform the following actions:

• Create a new FortiSOAR connector (New FortiSOAR Connector option)
• Import an existing FortiSOAR connector (Import FortiSOAR Connector option)

Creating a new FortiSOAR Connector

To create a new FortiSOAR connector, click FortiSOAR RDK from the Tool Bar Menu and then select the Create New FortiSOAR Connector option, to open the New FortiSOAR Connector dialog.

In the New FortiSOAR Connector dialog, specify the following parameters:

Once you complete entering the required values in the New FortiSOAR Connector dialog, click OK. Clicking OK displays, a success message and opens the info.json file of the connector. This also opens the Details tab in FortiSOAR RDK with the API Name you have specified, demo in our example:

FortiSOAR RDK - Details Tab

Use the Details tab to view (and edit) the details of the connector. The Details tab displays the parameters you specified in the New FortiSOAR Connector dialog. You can edit those parameters (except the API Name), and you can specify the following optional parameters:

Once you update the parameter values on the Details tab, click Save to save these changes, which will in turn update the info.json file of the connector. For example, if you have selected Email Server as the Category, you see that the value of the category parameter in the info.json file is updated to Email Server. Similarly, the logo parameter is updated to large.png:

On the Details tab, you can also perform the following actions:

• Generate Playbooks: Generates Sample Playbooks based on the operations you have defined. This action generates a playbooks.json file in the playbooks folder in your connector directory.
• Generate Documents: Generates Documentation for the connector based on the descriptions you have provided for various input parameters, configuration parameters, and operations. This action generates documentation files in both the .html and .md formats in the docs folder in your connector directory.
• Run Unit Test: Runs unit tests you have defined for the various operations of the connector. You can write test cases in the tests folder in your project directory. Each operation has its own separate test file, which is automatically added when you add any new operation in the format test_<operation_name>.py. For existing connectors, you must manually create this file, if you want to run unit tests for your newly added operations.
• Validate Connector: Performs code review for your connector, its operation, playbooks, etc., and generates the report in HTML format. The output is stored in the validate-output folder in the connector's folder:

  

  The validate connector performs the following checks:
  • The connector contains at least one action.
  • The names of the actions, playbooks, and playbook collections must be in the camel case.
  • The description for the actions must not be empty and must be in the sentence case.
  • The description for the playbooks and playbook collections must be in the sentence case.
  • The playbooks are in the Inactive state.
  • The size of the images used as small_icon.png and large_icon.png are correct.
  • The online help document for the connector is present.
  • The tags are added to all the playbooks.
  • The playbooks are not in the DEBUG mode.
  • The values for the Connector Publisher and CS Approved are correct.
  • The versions of packages listed in the requirements.txt file must be unrestricted.
• Install Requirements: Installs prerequisites that are required for the connector to optimally work. These requirements are added to the requirements.txt file in your project.
• Export: Exports the connector in the .tgz format to a location specified on your system. You can use this .tgz file to import the connector into a FortiSOAR instance.
• Deploy On FortiSOAR: Uploads the connector directly to your FortiSOAR instance. This will be available in the next version of the RDK.
• Contribute: Provides information on how to contribute to FortiSOAR Content Hub and opens the Partner Managed FortiSOAR Content GitHub Page.

FortiSOAR RDK - Configuration Tab

Use the Configuration tab to add configuration parameters for your connector. The parameters you define on this tab get displayed on the Connector Configuration popup when you click the connector card in Content Hub.

To add a new configuration parameter, click the Add Config Fields tab:

Click Add Argument to display a form in which you can add the details for the configuration parameters:

Once you have added all the required parameters such as Server URL, API Token, etc for the configuration fields, click Save to save the configuration parameter in the "configuration":{ section of the info.json file:

Next, click the Configure tab, from the Select Configuration drop-down list select the configuration with which you want to associate the created configuration parameters.

In the Add New Configuration section, in the Config Name field, enter the name of the configuration, for example, Default Config. You can also edit or add the default values of the configuration parameters that you had specified while adding the configuration parameters, for example in the server_url field, you can update www.example.com to www.demo.com and in the api_token field, you can enter the default configuration password, and then click Save.

NOTE: RDK masks the value of Password type fields, such as the api_token field in the following sample image:

To add a new configuration, click Add New. You can add multiple configurations for a connector and can click the Select Configuration drop-down list to view all the defined configurations:

You can also perform the following actions on the Configure tab:

• Run: Runs the check_health function and displays its output enabling you to determine if the configuration parameters are correctly defined:

  

• Reset: Reloads the fields as per their last saved value.

To configure Run and Debug in PyCharm for running a health check on a connector configuration, refer Setting up Run and Debug for connector configuration health check.

FortiSOAR RDK - Operations Tab

Use the Operations tab, to add actions that can be performed by your connector, and in the Add New Operation form, specify the following parameters for the new operation:

Once you have entered all the required parameters for the operation, click Create. This creates a new .py file with the operation name, for example, get_ip_reputation.py, and also adds the operation details in the "operations":{ section of the info.json file:

To add arguments to the operation, click the Arguments tab. On the Arguments tab, click Add Argument, and then in the displayed form add the parameters for the argument:

To add another input parameter, click Add Argument and follow the same procedure. Once you have added all the required parameters for the input parameter field for the operation, click Save to save the input parameters. This adds the parameters and their details to the "operation":{ section of the info.json file: in the "parameters":{ section. For example, the IP address parameter in the Get IP Reputation operation:

To test run the added operation with some sample input parameters, click the Execute Tab, and from the Select Config drop-down list select the configuration to be used to execute the operation. This runs the operation and displays its output enabling you to determine if the input parameters are correctly defined. For example, select Default Config from the Select Configuration drop-down list and enter an example IP address such as 1.1.1.1 in the ip_address field, and click Run:

Click Reset to reload the fields as per their last saved value.

If you have defined an output schema, then that gets displayed in the Captured Output Schema section, and you can also choose to save the output schema, by clicking the Save Output Schema button located at the base of the Captured Output Schema section:

You can similarly add new operations, by clicking the All tab and then clicking Add New Operation, and then further adding the details and arguments to that operation:

You can also perform the following actions on the All tab:

• Edit: Click Edit to edit the details and arguments (parameters) of an existing operation.
• Delete: Click Delete to delete an existing operation.
• Execute Action: Click to navigate to the Execute tab, where you can test-run the operation.
• Run Unit Test: Click Run Unit Test to run the unit tests that you have defined for the operation enabling you to immediately find out if there are any issues in the added operation.

To configure Run and Debug in PyCharm for various connector actions, refer Setting up Run and Debug for connector configuration health check.

Importing an existing FortiSOAR Connector

To import an existing FortiSOAR-compatible connector and then make updates or changes to this connector:

• Click FortiSOAR RDK from the Tool Bar Menu.
• Select the Import FortiSOAR Connector option.
• In the Open dialog, navigate to the location on your system where the .tgz file of the connector is saved.
• Click Open to import the connector in the current project directory.

You can now update the connector as per your requirements using the processes described in Creating a new FortiSOAR Connector.

To configure Run and Debug in PyCharm, refer to Configuring run and debug in PyCharm's Python.

Configuring run and debug in PyCharm's Python

We've used PyCharm's Python Run and Debug configuration for a connectors' operation and configuration. The Run and Debug configurations are available as buttons on the PyCharm dock.

Each connector appears as an expandable folder and has two configurations — one for connector health check and another for various connector operations.

The following sections explain setting up in Pycharm's Python:

• Connector configuration health check
• Various Connector Operations

Setting up Run and Debug for connector configuration health check

This section explains setting up the run and debug configurations for the health check of a connector. Once configured, PyCharm's run and debug feature can be used to verify a connector's configuration.

Once you have created or imported a connector, perform the following steps to set up Run and Debug in Pycharm's Python.

1. Navigate to Configuration > Configure tab of connector.
2. Specify relevant values in input fields for configuring the connector.
3. Click Save under Configuration > Configuration. A folder with the connector name appears under the Run/Debug option. The folder contains the run/debug configuration for the connector health check.

The Run and Debug buttons are now ready to use.

Setting up Run and Debug for connector operations

This section explains setting up the run and debug configurations for various connector operations. Once configured, PyCharm's run and debug feature can be used to run and debug a connector's operation.

Once you have created or imported a connector, perform the following steps to setup Run and Debug in Pycharm's Python.

1. Navigate to Operations.
2. Click + Add New Operation or edit an existing operation.
3. Navigate to the Connector tab > Execute under the selected operation's tab.
4. Specify relevant values in input fields for configuring the connector operation.
5. Click Save under Connector tab > Execute. A folder, with the operation name, within the connector's folder appears under the Run/Debug option. The folder contains the run/debug configurations for the edited operation.
6. Edit each operation and save the setting under PyCharm's Python run/debug configuration.

The Run and Debug buttons are now ready to use.

Troubleshooting

While configuring or updating the Python path from RDK Home, you may encounter the following error:

AttributeError: module 'pkgutil' has no attribute 'ImpImporter'.
    Did you mean: 'zipimporter'?

Following sections outline the troubleshooting steps to support Python version 3.12 with PyCharm 2022.2, 2022.3 & 2023.1 on both, Mac OS and Windows.

Resolution for Mac OS

Perform the following steps:

1. Run the following commands on PyCharm's local terminal to upgrade pip in your local Python Virtual Environment:

   source .venv/bin/activate

   python3.12 -m ensurepip --upgrade

2. Navigate to RDK Home and click Update Python Path button to update the python path with python3.12

Resolution for Windows

Perform the following steps:

1. Run the following commands on PyCharm's local terminal to upgrade pip in your local Python Virtual Environment:

   venv/Scripts/activate

   py -m ensurepip --upgrade

2. Navigate to RDK Home and click Update Python Path button to update the python path with python3.12

fortisoar-rdk-pycharm-3.0.0-89