FortiSOAR Rapid Development Kit v2.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 creating 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: 2.0.0

PyCharm Version Tested on: 2022.2 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:

• Made the FortiSOAR RDK compatible with the latest PyCharm version. The minimum version of PyCharm that the FortiSOAR RDK is compatible with is 2022.2.
• Added a new Validate Connector action that generates a report in the HTML format. Earlier the feature had a placeholder by the name of Connector Inspect. For more information, see Validate Connector.
• Improved the security in the RDK as follows:
  • Use of encrypted formats to locally store all the Password type fields.
  • Masks all Password type fields on the UI, and on the FortiSOAR terminal output.
• Ability to export the connector's .tgz to a location specified on your system. Previously, the connector's .tgz could be exported only to a directory in the same project.
• Added the ability to delete all the arguments from the Configuration and Operations tabs. Previously, you could not delete the last argument from the Configuration and Operations tabs.
• Updated the Home Page of the RDK as follows:
  • Updated the label for the button to specify the python path as follows:
    • If the Python path is not configured then the button will be displayed as Configure Python Path.
    • If the Python path is configured then the button will be displayed as Update Python Path.
  • Improved the UI of the Configure Python Path or Update Python Path dialog by displaying it as a pop-up dialog making it easier to browse or specify the python path in the Python Path field within the dialog.
• Added the Connector does not contain any dependencies to install message, which the RDK displays when the connector's requirement.txt file is empty or the dependencies are commented.
• Added support for the connection logo to be in the .png file type as well. The only format that was supported earlier was .jpg The connector logo is now available to in the .png and .jpg formats.
• Improved the Generate documents functionality for imported connectors to store the generated documents in the docs folder within the connector's folder. Previously, for imported connectors, the docs folder was getting generated outside the connector's folder.
• Renamed the API Operation tab to Operations.
• Added the following validations:
  • Validation that the version specified for the connector is added and is in the correct format while creating a connector. Earlier, the validation was applicable only when the connector was being edited. The version of the connector must follow the x.y.z pattern.
  • Validations for the following fields are added and these fields accept only alphanumeric and &, _, or -; special characters:
    • The Display Name and API Name fields of the connector on the Details tab.
    • All the configuration parameters that are present on the Configuration tab.
    • The Display Name and API Name fields of the actions of the connector.
    • All the input parameters that are present on the Operations tab.
• Populated Select an Option by default when a field of type Select is added to the connector. Additionally, for the Select field type, the argument field Options is marked as mandatory.
• Added a warning dialog when playbook is generated on an imported connector.

  Warning: Existing playbook will be overwritten.

  Do you want to continue?

Installing or Upgrading 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-2.0.0-52.zip) that is attached to this document, extract its contents on your system, and then perform the following steps in your PyCharm Utility.
2. Open your PyCharm utility and select Plugins.
3. On the Plugins screen, click the Manage Repositories, Configure Proxy, or Install Plugin From Disk icon, and then select the Install Plugin from Disk option.
4. In the Choose Plugin File dialog, navigate to where the FortiSOAR RDK zip file is located on your system, and click OK to install the FortiSOAR RDK.
5. Configure the Python path to install the latest dependencies. For more information, see the Configuring the Python path topic.

To upgrade FortiSOAR RDK, use the same steps as listed above, however after you have chosen the FortiSOAR RDK.zip file to be installed and clicked OK, you must click the Restart IDE button to restart the PyCharm IDE to upgrade FortiSOAR RDK. Update the Python path to install the latest dependencies. For more information, see the Configuring the Python path topic.

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.

To configure the Python path for your project, click FortiSOAR RDK from the Tool Bar Menu and click the Update Python Path option, if you have previously configured Python; if you have not configured Python, then click the Configure Python Path. In the Python Path field, specify or navigate to the path where Python is installed and click OK:

Once the FortiSOAR RDK is installed, you will see the FortiSOAR RDK option in the Main Menu and Tool Window on the right sidebar 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 Threat Intelligence as the Category, you will see that the value of the category parameter in the info.json file is updated to Threat Intelligence. Similarly, the logo parameter is updated to demo.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.

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.

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 and 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, and then click Open. This imports the connector in the current project directory, where you can update the connector as per your requirements using the processes described in Creating a new FortiSOAR Connector topic.

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-2.0.0-52.zip