Fortinet Document Library

Version:


Table of Contents

FortiSOAR™ Connector SDK

0.0.0
Copy Link

The FortiSOAR™ Connector SDK consists of a simulator for writing and testing your connector. You can use this CLI to help you develop your custom connector without requiring a FortiSOAR™ instance. The FortiSOAR™ Connector SDK is available on Fortinet Developer Network (FNDN) as an installable. For more information on the building blocks of creating a connector such as info.json, connector.py, etc, see the Building a custom connector chapter in the FortiSOAR™ product documentation.

Note: This version of the SDK supports FortiSOAR™ 6.x.x releases.

You can use the FortiSOAR™ Connector SDK to write a custom connector and also to perform these additional functions:

  • Add or update the connector metadata, the configuration details, and operations supported for the connector.
  • Import and configure the connector using the SDK.
  • List all connectors imported with the SDK.
  • Run a health check on these installed connectors.
  • List the supported operations for a given connector.
  • List the configurations for a given connector.
  • Execute operation on a connector.
  • Remove a connector.

Prerequisites for running the Connector SDK

You can run the Connector SDK on Linux, Windows, or MacOS. The SDK is a Python Django project and therefore for faster debugging you can also set it up as Django project in any Python IDE.

To run the SDK, you require Python 3.6+, an SQLite database, and OpenSSL. For example, to run the Connector SDK on a Centos 7 - Minimal Edition, you can install the following rpms:

  • Python3.6+ compiled with sqlite-devel and openssl-devel
  • virtualenv-15.1.0
  • Openssl-devel
  • GCC

Setting up the FortiSOAR™ Connector SDK project

The FortiSOAR™ Connector SDK is available on FNDN as an installable. You require to sign into FNDN to access the Connector SDK. Download the FortiSOAR™ Connector SDK and extract its contents. Ensure that the .tgz file is extracted in your SDK Folder. 

You must perform the following steps for a one-time setup of the FortiSOAR™ Connector SDK project:

  1. Create a virtual environment with python 3.6+ using the following command:
    virtualenv -p <path_to_python> <path_to_virtualenv>
    For example: virtualenv -p /usr/local/bin/python3/3.6.3/bin/python3 ~/workspace/integrations-sdk/.env
  2. Activate the environment.
    For example, source ~/workspace/integrations-sdk/.env/bin/activate
  3. Install the requirements.
    <path_to_pip> install -r requirements.txt
    For example: /usr/local/bin/python3/3.6.3/bin/pip install -r requirements.txt
  4. Setup the database
    cd integrations
    ./setupsdk.py

Using the FortiSOAR™ Connector SDK

  1. To get started with building and testing new connectors, and create the connector directory, run the following command:
    <path_to_python> cs_sdk.py --option create_template --name <connector_name> --version <connector_version>
    For more details on the options available with cs_sdk.py, use the help command: ./cs_sdk.py -h or ./cs_sdk.py --help.
    By default, the connector directory gets created in the same location as your cs_sdk.py file. If you want to override the default location, you must enter the target directory.
    Once the connector directory is created, the Connector SDK displays the following message:
    Well done! Your directory <directory name> is created. Use ‘--option add_info --name <connector_name> --version <connector_version>’ to add the connector metadata.
  2. To add the info.json for your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_info --name <connector_name> --version <connector_version>
    Enter the following details for creating the info.json for your connector:
    Connector Name:
    Description:
    Version:
    Publisher:
    Category:
    Is the connector approved by Fortinet (Y/Yes/N/No):
    Is the connector compatible with FortiSOAR (Y/Yes/N/No):
    File path to a small icon for the connector:
    File path to a large icon for the connector:
    Once the info.json for your connector is updated based on the information you have provided, the Connector SDK displays the following message:
    Well done! The connector info.json has been updated with the above information for the connector. Use ‘--option add_config_params --name <connector_name> --version <connector_version>’ to add the connector configuration parameters.
  3. To add configuration parameters for your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_config_params --name <connector_name> --version <connector_version>
    Enter the following details for adding the configuration input parameters for your connector:
    Field Name:
    Title:

    Is it a required field (Y/Yes/N/No:
    Is it a user-editable field (Y/Yes/N/No):
    Is it a field visible to the user (Y/Yes/N/No):
    Would you like to add another field (Y/Yes/N/No):
    //Repeats till the user enters No for the 'Would you like to add another field' option
    Once you have added input parameters required to configure your connector, the Connector SDK displays the following message:
    Well done! The configuration input parameters have been added successfully.
    Implement the health check function for the connector at <connector_locn>/health_check.py.
    Use ‘--option add_operation --name <connector_name> --version <connector_version>’ to add operations on the connector.
  4. To add operations that would be supported by your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_operation --name <connector_name> --version <connector_version>
    Enter the following details for adding the operations that would be supported by your connector:
    Operation Name:
    Title:

    Operation description:
    Is the operation enabled on the connector (Y/Yes/N/No):
    //Specify the input parameters required for the above operations:
    Parameter name:
    Is a required parameter (Y/Yes/N/No):
    Is a visible parameter (Y/Yes/N/No):
    Is an editable parameter (Y/Yes/N/No):
    Default value for the parameter:
    Add another parameter (Y/Yes/N/No):
    //Repeats till the user enters No for the 'Add another parameter' option
    Once you have completed adding all the parameters for the supported operation, displays Connector SDK following message:
    Well done! The operation has been added. Add the operation’s implementation in <connector_location>/<operation_name>.py:
    To add another operation that is supported by your connector:
    Add another operation (Y/Yes/N/No):
    //This adds another operation that would be supported by your connector. It repeats till the user enters No for the 'Add another operation' option
    Once you have added all the operations supported by your connector, the Connector SDK displays the following message:
    Well done! The supported operations have been added successfully.
    Ensure that you add the function implementations for the supported operations before importing the connector with the SDK.
  5. Start the application server using the following command:  
    python manage.py runserver
  6. To import your connector in the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option import --name <connector_name> --version <connector_version> --bundle <path to connector archive> --path <path to connector folder>
    <path to connector archive>: The .tgz file of the connector bundle.
    Or
    <path to connector folder>: The absolute path to the connector folder. The SDK will create a .tar file and import it into FortiSOAR™.
    If you have used cs_sdk.py to generate the connector template, then the SDK already has the path. In that case, this is an optional parameter that takes precedence over the existing path.
    Once your connector is imported with the SDK, the Connector SDK displays the following message:
    Well done! The connector has been successfully imported. 
    You can use the following commands for various operations:
    Use ‘--option configure --name <connector_name> --version <connector_version>’ to provide the configuration inputs and set up the connector.
    Use ‘--option remove --name <connector_name> --version <connector_version>’ to remove the connector.
    Use ‘--option export --name <connector_name> --version <connector_version>’ to export the connector into a .tgz file.  
  7. To set up the connector and provide configuration inputs, run the following command:
    <path_to_python> cs_sdk.py --option configure --name <connector_name> --version <connector_version>
    Enter the following details for adding configuration inputs for your connector:
    Field 1:
    Field 2: . . .
    The field names that you are prompted for are based on the data provided in the info.json of the connector.
    Once your connector is configured, the Connector SDK displays the following message:
    Well done! The connector has been configured.
    The check_health response is: <output from health check function>
    You can use the following commands for various operations:
    ‘--option check_health--name <connector_name> --version <connector_version> --config <config_name>’ to check the connector health again
    ‘--option execute’ to execute any operation on the connector
    ‘--option list_operation’ to list operations available on any connector
    ‘--option list_connectors’ to list all imported connectors
    ‘--option list_configs’ to list all configurations for all imported connectors
    ‘--option list_configs --name <connector_name> --version <connector_version>’ to list all configurations for the specified connector
  8. To execute an operation supported by your connector, run the following command:
    <path_to_python> cs_sdk.py --option execute --name <connector_name> --version <connector_version> --config <config_name> --operation <operation_name>
    Enter the configuration parameters required to execute the operation:
    Field 1:
    Field 2: . . .
    Once the operation has been executed, the Connector SDK displays the <output from the execute function>.
  9. To export the connector, run the following command:  
    <path_to_python> cs_sdk.py --option export --name <connector_name> --version <connector_version>
    This creates a .tgz file of the exported connector.
  10. To remove the connector from the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option remove ---name <connector_name> --version <connector_version>
  11. To list the connectors available within the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option list_connectors
  12. To list the operations available for a connector, run the following command:
    <path_to_python> cs_sdk.py --option list_operations --name <connector_name> --version <connector_version>

The FortiSOAR™ Connector SDK consists of a simulator for writing and testing your connector. You can use this CLI to help you develop your custom connector without requiring a FortiSOAR™ instance. The FortiSOAR™ Connector SDK is available on Fortinet Developer Network (FNDN) as an installable. For more information on the building blocks of creating a connector such as info.json, connector.py, etc, see the Building a custom connector chapter in the FortiSOAR™ product documentation.

Note: This version of the SDK supports FortiSOAR™ 6.x.x releases.

You can use the FortiSOAR™ Connector SDK to write a custom connector and also to perform these additional functions:

Prerequisites for running the Connector SDK

You can run the Connector SDK on Linux, Windows, or MacOS. The SDK is a Python Django project and therefore for faster debugging you can also set it up as Django project in any Python IDE.

To run the SDK, you require Python 3.6+, an SQLite database, and OpenSSL. For example, to run the Connector SDK on a Centos 7 - Minimal Edition, you can install the following rpms:

Setting up the FortiSOAR™ Connector SDK project

The FortiSOAR™ Connector SDK is available on FNDN as an installable. You require to sign into FNDN to access the Connector SDK. Download the FortiSOAR™ Connector SDK and extract its contents. Ensure that the .tgz file is extracted in your SDK Folder. 

You must perform the following steps for a one-time setup of the FortiSOAR™ Connector SDK project:

  1. Create a virtual environment with python 3.6+ using the following command:
    virtualenv -p <path_to_python> <path_to_virtualenv>
    For example: virtualenv -p /usr/local/bin/python3/3.6.3/bin/python3 ~/workspace/integrations-sdk/.env
  2. Activate the environment.
    For example, source ~/workspace/integrations-sdk/.env/bin/activate
  3. Install the requirements.
    <path_to_pip> install -r requirements.txt
    For example: /usr/local/bin/python3/3.6.3/bin/pip install -r requirements.txt
  4. Setup the database
    cd integrations
    ./setupsdk.py

Using the FortiSOAR™ Connector SDK

  1. To get started with building and testing new connectors, and create the connector directory, run the following command:
    <path_to_python> cs_sdk.py --option create_template --name <connector_name> --version <connector_version>
    For more details on the options available with cs_sdk.py, use the help command: ./cs_sdk.py -h or ./cs_sdk.py --help.
    By default, the connector directory gets created in the same location as your cs_sdk.py file. If you want to override the default location, you must enter the target directory.
    Once the connector directory is created, the Connector SDK displays the following message:
    Well done! Your directory <directory name> is created. Use ‘--option add_info --name <connector_name> --version <connector_version>’ to add the connector metadata.
  2. To add the info.json for your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_info --name <connector_name> --version <connector_version>
    Enter the following details for creating the info.json for your connector:
    Connector Name:
    Description:
    Version:
    Publisher:
    Category:
    Is the connector approved by Fortinet (Y/Yes/N/No):
    Is the connector compatible with FortiSOAR (Y/Yes/N/No):
    File path to a small icon for the connector:
    File path to a large icon for the connector:
    Once the info.json for your connector is updated based on the information you have provided, the Connector SDK displays the following message:
    Well done! The connector info.json has been updated with the above information for the connector. Use ‘--option add_config_params --name <connector_name> --version <connector_version>’ to add the connector configuration parameters.
  3. To add configuration parameters for your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_config_params --name <connector_name> --version <connector_version>
    Enter the following details for adding the configuration input parameters for your connector:
    Field Name:
    Title:

    Is it a required field (Y/Yes/N/No:
    Is it a user-editable field (Y/Yes/N/No):
    Is it a field visible to the user (Y/Yes/N/No):
    Would you like to add another field (Y/Yes/N/No):
    //Repeats till the user enters No for the 'Would you like to add another field' option
    Once you have added input parameters required to configure your connector, the Connector SDK displays the following message:
    Well done! The configuration input parameters have been added successfully.
    Implement the health check function for the connector at <connector_locn>/health_check.py.
    Use ‘--option add_operation --name <connector_name> --version <connector_version>’ to add operations on the connector.
  4. To add operations that would be supported by your connector, run the following command:
    <path_to_python> cs_sdk.py --option add_operation --name <connector_name> --version <connector_version>
    Enter the following details for adding the operations that would be supported by your connector:
    Operation Name:
    Title:

    Operation description:
    Is the operation enabled on the connector (Y/Yes/N/No):
    //Specify the input parameters required for the above operations:
    Parameter name:
    Is a required parameter (Y/Yes/N/No):
    Is a visible parameter (Y/Yes/N/No):
    Is an editable parameter (Y/Yes/N/No):
    Default value for the parameter:
    Add another parameter (Y/Yes/N/No):
    //Repeats till the user enters No for the 'Add another parameter' option
    Once you have completed adding all the parameters for the supported operation, displays Connector SDK following message:
    Well done! The operation has been added. Add the operation’s implementation in <connector_location>/<operation_name>.py:
    To add another operation that is supported by your connector:
    Add another operation (Y/Yes/N/No):
    //This adds another operation that would be supported by your connector. It repeats till the user enters No for the 'Add another operation' option
    Once you have added all the operations supported by your connector, the Connector SDK displays the following message:
    Well done! The supported operations have been added successfully.
    Ensure that you add the function implementations for the supported operations before importing the connector with the SDK.
  5. Start the application server using the following command:  
    python manage.py runserver
  6. To import your connector in the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option import --name <connector_name> --version <connector_version> --bundle <path to connector archive> --path <path to connector folder>
    <path to connector archive>: The .tgz file of the connector bundle.
    Or
    <path to connector folder>: The absolute path to the connector folder. The SDK will create a .tar file and import it into FortiSOAR™.
    If you have used cs_sdk.py to generate the connector template, then the SDK already has the path. In that case, this is an optional parameter that takes precedence over the existing path.
    Once your connector is imported with the SDK, the Connector SDK displays the following message:
    Well done! The connector has been successfully imported. 
    You can use the following commands for various operations:
    Use ‘--option configure --name <connector_name> --version <connector_version>’ to provide the configuration inputs and set up the connector.
    Use ‘--option remove --name <connector_name> --version <connector_version>’ to remove the connector.
    Use ‘--option export --name <connector_name> --version <connector_version>’ to export the connector into a .tgz file.  
  7. To set up the connector and provide configuration inputs, run the following command:
    <path_to_python> cs_sdk.py --option configure --name <connector_name> --version <connector_version>
    Enter the following details for adding configuration inputs for your connector:
    Field 1:
    Field 2: . . .
    The field names that you are prompted for are based on the data provided in the info.json of the connector.
    Once your connector is configured, the Connector SDK displays the following message:
    Well done! The connector has been configured.
    The check_health response is: <output from health check function>
    You can use the following commands for various operations:
    ‘--option check_health--name <connector_name> --version <connector_version> --config <config_name>’ to check the connector health again
    ‘--option execute’ to execute any operation on the connector
    ‘--option list_operation’ to list operations available on any connector
    ‘--option list_connectors’ to list all imported connectors
    ‘--option list_configs’ to list all configurations for all imported connectors
    ‘--option list_configs --name <connector_name> --version <connector_version>’ to list all configurations for the specified connector
  8. To execute an operation supported by your connector, run the following command:
    <path_to_python> cs_sdk.py --option execute --name <connector_name> --version <connector_version> --config <config_name> --operation <operation_name>
    Enter the configuration parameters required to execute the operation:
    Field 1:
    Field 2: . . .
    Once the operation has been executed, the Connector SDK displays the <output from the execute function>.
  9. To export the connector, run the following command:  
    <path_to_python> cs_sdk.py --option export --name <connector_name> --version <connector_version>
    This creates a .tgz file of the exported connector.
  10. To remove the connector from the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option remove ---name <connector_name> --version <connector_version>
  11. To list the connectors available within the Connector SDK, run the following command:
    <path_to_python> cs_sdk.py --option list_connectors
  12. To list the operations available for a connector, run the following command:
    <path_to_python> cs_sdk.py --option list_operations --name <connector_name> --version <connector_version>