FortiSOAR Rapid Development Kit v1.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: 1.0.0

PyCharm Version Tested on: 2022.2.3

Authored By: Fortinet

Certified: Yes

Installing the FortiSOAR Rapid Development Kit

Download the FortiSOAR RDK (fortisoar-rdk-pycharm-1.0.0-19.zip) that is attached to this document and extract its contents on your system and then perform the following steps in your PyCharm Utility.

Open your PyCharm utility and select Plugins. On the Plugins screen, click Settings and then select the Install Plugin from Disk option. In the Choose Plugin File dialog, navigate to where the FortiSOAR RDK zip file is located on your system, and then click OK.

Once the FortiSOAR add-on gets 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)

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 Configure Python Path option. In the Python Path field, specify or navigate to the path where Python is installed on your system and click Update:

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 and update the info.json file. For example, if you have selected the Certified option, you will see that the value of the "cs_approved" parameter in the info.json file is updated to "true". Similarly, the "category" parameter is updated to "Threat Intelligence":

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 project 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 project 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.
• Connector Inspect: Performs code review for your connector operations. This will be available in the next version of the RDK.
• 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, in the same project directory. 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 for the configuration field, click Save to save the configuration parameter in the "configurations":{ section of the info.json file. You can similarly add more configuration parameters such as Server Port, etc.

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. To add a new configuration, click Add New, and 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.demo.com" to "www.example.com" and in the server_port field, you can enter "443", and then click Save:

You can add multiple configurations for a connector and can click the View All button 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 within 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.

You can add new operations in a similar manner, 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.

Points to be considered while importing and updating a connector not developed using FortiSOAR RDK

You must note the following if you are importing and editing a connector developed outside FortiSOAR RDK, i.e., exporting an existing connector from FSR such as 'VirusTotal' and then importing it to FortiSOAR RDK:

• If you add a new operation to the existing connector using FortiSOAR RDK, ensure that you clear the Generate Default Operation Code option before you click Create in the 'Operations' tab. If you leave the 'Generate Default Operation Code' option selected, then all the existing connector operations get overwritten as this option overwrites the contents of the operations.py file. Therefore, in this case, the info.json file gets populated with the information of the new operation; however, you require to manually add the functions and mappings of the existing (previous) operations to the operations.py file.
• Similarly, If you update an existing operation in the existing connector using FortiSOAR RDK, the change gets reflected in the info.json file; however, the operation.py file has to be manually updated.

fortisoar-rdk-pycharm-1.0.0-19.zip