Fortinet black logo

Introduction to connectors

Copy Link
Copy Doc ID 9c4adef8-f2c7-11ec-bb32-fa163e15d75b:929681
Download PDF

Introduction to connectors

Connectors are used to send and retrieve data from various third-party sources. Using connectors, you can connect to external cyber security tools and perform various automated interactions using FortiSOAR™ playbooks.

FortiSOAR has already developed several connectors that can be used to integrate with many external cyber security tools like SIEMs, such as Splunk, and Ticketing systems such as Jira. Connector-specific documentation that is included with each connector covers the process of installing, configuring, and using these connectors. You can see a list of published connectors on the Fortinet Support Site.

FortiSOAR also provides you with several pre-installed connectors or built-ins that you can use within FortiSOAR playbooks, as a connector step, and perform automated operations. For more information on FortiSOAR Built-in connectors, see the "FortiSOAR Built-in connectors" article.

Note

From FortiSOAR release 7.2.1 onwards, integrations are run using the fsr-integrations user instead of the nginx user. Therefore, code snippets that try to write on a file system that is outside /opt/cyops-integrations or /tmp might be impacted and you also need to ensure appropriate permissions have been given to the fsr-integrations user.
Writing on file systems using code snippets outside /tmp is highly discouraged.

You can write a custom connector that can retrieve data from custom sources. You can then use the connector either standalone or within FortiSOAR playbooks and perform automated operations. You can write a custom connector manually, or you can use the FortiSOAR Connector SDK to develop your custom connector. For more information on writing custom connectors, see the Building your own connector chapter.

Use the Connector Store (Content Hub) in the FortiSOAR UI to easily view, search, install, update, and uninstall connectors that are part of the FortiSOAR repository. You can also specify connector configuration using a jinja variable that contains the connector configuration name.

Note

In Release 7.2.0, the Connector navigation take you to the Content Hub with the relevant 'Connectors' filter selected for browsing ease.

Connector Store

Use the Connector Store to easily view, search, install, upgrade, and uninstall connectors that are part of the FortiSOAR repository. Therefore, you can now perform these operations using the FortiSOAR UI instead of the required CLI access. The Content Hub contains all out-of-the-box reference material and product add-ons such as connectors, widgets, and solution packs; whereas the Connector Store has been filtered to display only Connectors.

Caution

You must ensure that repo.fortisoar.fortinet.com is reachable from your FortiSOAR instance. Otherwise, you will see a blank page when you click Content Hub or Automation > Connectors in the left navigation.
In release 7.2.0 update.cybersponse.com has been renamed to https://repo.fortisoar.fortinet.com/. Both these repositories will be available for a while to allow users who are on a release prior to FortiSOAR release 7.2.0 to access connectors and widgets. However, in time, only https://repo.fortisoar.fortinet.com/ will be available.

Following are the permissions that you must be assigned to perform operations on connectors:

  • To work with connectors, i.e., view the connectors listed in the Content Hub and changes made to the Content Hub, you must be assigned a role that has a minimum of Read access on the Application, Connectors, Playbooks, and Content Hub modules, a minimum of Create, Read, Update permissions on the Solution Packs module.
  • To install a connector from the Content Hub or to upload a connector to the Content Hub you must be assigned a role that has a minimum of Read permission on the Security module.
  • Apart from the above, to work with connectors, you need appropriate permissions on the Connectors and Playbooks modules. For example, to install a connector or create a new custom connector, you must be assigned a role that has a minimum of Create and Read access on the Connectors module and Read access on the Playbooks modules, or to upgrade or configure a connector, you must be assigned a role that has a minimum of Update and Read access on the Connectors module and Read access on the Playbooks module.

To open the Connector Store, go to Automation > Connectors, or to go to Content Hub, click Content Hub in the left menu. The Connector Store is filtered to display only connectors, whereas the Content Hub displays all the add-ons. In this chapter the screenshots included are from the Content Hub page; similar screens are displayed on the Connector Store page.
The Discover tab displays all the add-ons, i.e., Connectors, Widgets, and Solution Packs, available in the Content Hub. Use the Filter panel to filter the connectors by clicking the > arrow in the Content Type list and then selecting Connectors:
Market Place > Filtered by Connectors

You can search for a connector by its name in the Search field and sort the content alphabetically (A-Z) or by date. Using the Filters panel, you can filter the connectors displayed in all the tabs based on varied criteria. For more information on Content Hub, see the Content Hub chapter in the "User Guide.' Connectors that are installed appear with a tick on their card. For example, the Active Directory connector in the above image.

To install a connector, click that connector's card, for example, AbuseIPDB, which opens a popup with the connector name:
Connector Name popup to install a connector

The connector popup contains details such as the name and version of the connector, whether the connector is certified or not, who is the publisher of the connector, and the link to the connector documentation. The Summary tab contains a brief description of the connector, and the Contents tab contains a list of actions the connector can perform.

Click Install in the connector name popup to begin the installation of the connector after confirmation, as shown in the following image:
Installing a connector

Once installation is complete, FortiSOAR displays the "Connector Installed successfully" message, and the connector gets added to the Manage page. After installing the connector, you must configure the connector by entering the required configuration details in the connector popup:
Connector Configuration Popup

You can also configure the connector on the Manage page by clicking the connector name card, which will also display the same connector popup. For more information, see the Installing or importing and configuring a connector in FortiSOAR section.

Some connectors have dependencies on additional python packages, which if not installed would hamper the functioning of the connector. By default, the dependencies are resolved from pypi.org and repo.fortisoar.fortinet.com. Dependencies could fail to install due to reasons such as the blocking of users' pypi or not having the latest deps repository on repo.fortisoar.fortinet.com. In such cases where the connectors get installed but the dependencies fail to install, FortiSOAR displays a Connector Dependencies Failed To Install message on the connector configuration popup as shown in the following image:
Connector Configuration popup with Dependencies fail message
You can try to reinstall the dependencies by clicking the Install link.

Dependencies of connectors that are not installed from FortiSOAR Content Hub might fail to install even after a retry since the dependencies for such connectors are not present in the FortiSOAR repository. In such cases, you can download the dependencies from pypi.org and install the dependencies using the information present in https://pip.pypa.io/en/latest/user_guide/#installing-from-local-packages.
To install a package in FortiSOAR, use the following command:
sudo -u fsr-integrations /opt/cyops-integrations/.env/bin/pip install <package>

Installing or importing and configuring a connector in FortiSOAR

Use the Connector Store to install and configure connectors in FortiSOAR.

To install a connector, you must be assigned a role that has a minimum of Create access to the Connectors module. To configure connectors into FortiSOAR, you must be assigned a role that has a minimum of Update access to the Connectors module.

The following procedure describes how to install and configure connector using Connector Store:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Connector Store > Discover.
    On the Discover page, you will see all the connectors, both which are installed and which are not installed. Installed connectors appear with a with a tick on their card. You can search for a connector by its name in the Search box and sort the connectors either alphabetically or by date.
    To install a connector, click that connector's card, which opens a popup with the connector name on which click Install. This process is described in the Connector Store section.
    Once installation is complete, FortiSOAR displays the "Connector Installed successfully" message, and the connector gets added to the Manage page in the 'Active' state; however, you can change the state of the connector from active to inactive by toggling the ACTIVE button.
    To import a connector (.tgz) file into FortiSOAR, click the Manage tab and on the Manage page, click Upload > Upload Connector to display the Upload Connector popup as shown in the following image:
    Importing a connector in FortiSOAR />
    You can drag and drop the connector .tgz file onto the popup or browse to the .tgz file to install the connector in FortiSOAR. If you have an existing version of the connector on your system, then you can click the Replace existing version checkbox, to replace that version of the connector.
    You must check that all the connector dependencies are available or install the additional dependencies to ensure that the connector functions as expected.
  3. To configure a connector, on the Manage page, click the connector card to open the Connector Configuration popup. Enter the required configuration details in the connector configuration popup, as shown in the following image:
    Connector Configuration Popup
    Once you add the configuration details in the connector popup and click Save, FortiSOAR opens a modal window that displays the progress of the configuration and the status of the health check while saving the connector configuration:
    Connector Configuration Modal Window - Successful configuration
    All errors or warnings related to connector configuration, including missing dependencies, invalid configurations, and health check status, are displayed in the modal window:
    Connector Configuration Modal Window - Failed Health Check
    The health check status and missing dependencies are also displayed on the connector configuration popup. You can choose to try to reinstall the dependencies by clicking the Install link that appears alongside the Connector Dependencies Failed To Install message on the modal window or the connector configuration popup as described in the Connector Store section.
    Note: Once you have installed a connector dependency on a FortiSOAR node using the Install link on the connector's Configurations dialog, then that dependency is installed seamlessly on the other nodes of the HA cluster.
    Notes on Configuration:
    • If you are configuring the connector for the first time, then in the Configuration Name field add a name of the configuration.
      Note: You can add multiple configurations for your connector, therefore, you must add a unique Name for each configuration in the Configuration Name field.
    • If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR fetches the configuration and input parameters of the latest available version of that connector. For example, if you have 1.0.0 and 2.0.0 versions of the Database connector and you are configuring the 2.0.0 version of the Database connector, then while configuring the 2.0.0 version, FortiSOAR will fetch the configuration and input parameters from the 1.0.0 version of the Database connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    • To add a new configuration, click the +Add New Configuration button, and then add the name of the configuration and specify the configuration parameters. You can click the < Back to Configuration Selection button to go back to the Configuration page:
      Adding a new connector configuration
    • If you want to update an existing configuration, then select the configuration from the Select Configuration drop-down list and update the configuration parameters. If there is only one configuration, then that configuration will be selected automatically.
      Selecing a connector configuration
    • You can also check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR instance. This connector will point to this configuration by default.
      Important: In the case of the SMTP connector, you must ensure that this option is selected for the configuration that is to be used for sending system notifications.
    • The password type fields in FortiSOAR include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords. If your administrator has configured an external vault to securely store your organization's sensitive data and credentials, then you can use the Dynamic Values dialog to enter the credentials for your connector as shown in the following image:
      Connector Configuration - Vault Option
      For information on Dynamic Values, see the Dynamic Values chapter in the "Playbooks Guide." For information on Password Vault, see the Security Management chapter in the "Administration Guide."
    • You can also define the ownership of connector configurations by setting the visibility of a connector's configuration to 'Private'. For more information, see the Defining the ownership of a connector's configuration section.
    • You can configure connectors for the current FortiSOAR node, an agent, which is used to remotely run actions, or both. For more information on agents and how to run remote actions using agents, see the Segmented Network support in FortiSOAR chapter in the "Administration Guide." You can configure on the current node (Self) or on a remote Agent node (Agent) by clicking the Self, which is the default, or Agent buttons besides Target. You can configure multiple configurations for a connector on both the current node and the agent node. To configure and execute connector actions on the "Agent" node, click Agent, and from the Select Agent drop-down list select the agent on which you want to run the connector actions. If there is only one agent installed, then that agent will be selected automatically.
    • Connectors also include a Verify SSL field, that specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True. For more information, see How the connector framework verifies the server certificate when it's self-signed.
    • To view the documentation associated with a connector, click the Documentation link on the top-right corner of the connector configuration pane.

Points to be considered for connector configurations while upgrading to a newer version of the connector

If you are upgrading a connector to a newer version, you must be assigned a role that has a minimum of Upgrade access to the Connectors module. For example, if you are upgrading the Symantec Security Analytics connector version from v1.0.0 to v2.0.0, then keep a note of the following points:

  • Existing (older) connector configuration fields retain their value, i.e., the value from the older configuration will be displayed in the configuration pane of the newer connector version. New connector configuration field(s), if any, will be added to the connector configuration pane.
  • If the newly added configuration field is mandatory, and FortiSOAR has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field. For more information on the connector framework and the info.json file, see the Building your own connector chapter.
    For information on common connector framework issues, see the Common connector framework errors section in the Debugging common playbook and connector issues article present in the Fortinet Knowledge Base.
  • If the newly added configuration field is mandatory, and FortiSOAR has not specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain a blank value for this configuration field. If you also do not specify a value for this mandatory configuration field, then the connector configuration pane will display Partially Configured, and an error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."
  • If the field type of a mandatory configuration field is changed from the older version to the newer version, for example from a text field to a drop-down list, then the value of that field will not be retrieved from the older version. However, if FortiSOAR has specified its default value (in the info.json file of the connector), then that value will be displayed for this configuration field in the configuration pane of the newer version of the connector. If however FortiSOAR has not defined the default value and you also do not specify a value for this mandatory configuration field, then the configuration pane of the newer version of the connector will contain a blank value for this configuration field, and the connector configuration pane will display Partially Configured. An error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."
  • If the newly added configuration field is optional, and FortiSOAR has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field. If there is no default value is set, then its value is set as blank.

Installing or Updating a FortiSOAR connector using the CLI

All connectors published by FortiSOAR are delivered using a FortiSOAR repository. Use the Connector Store to easily install, update and install connectors that are part of the FortiSOAR repository.

Tooltip The recommended way to install a connector is by using the Connector Store.

You could also set up your FortiSOAR repository and use the yum command to install connectors as a root user:

# yum install cyops-connector-<connectorname>

Note

After you install a connector using the yum command the new connector is not reflected until you refresh the Connectors page.

To update a FortiSOAR-published connector use the following command:

# yum update cyops-connector-<connectorname>

To remove a FortiSOAR-published connector use the following command:

# yum remove cyops-connector-<connectorname>

Note

If you delete a FortiSOAR-published connector using the Connector page in FortiSOAR then you cannot reinstall the RPM of the same connector because the RPM of the connector does not get deleted. Therefore, to remove a FortiSOAR-published connector, you must use the yum remove cyops-connector-<connectorName> command.

Some of the connectors have dependencies on additional python packages. During connector installation, these dependencies are also installed using pip. The default pip settings point to the pypi.python.org repository for downloading these packages. We have also added an alternate repository on repo.fortisoar.fortinet.com to host the connector dependencies. If your instance restricts access to pypi.python.org, the installer fallbacks to this alternate repository for installing the dependencies. However, the connector installation might take longer if there are multiple dependencies since it first tries to fetch each of those from pypi.python.org. In such a case, it is recommended to switch to repo.fortisoar.fortinet.com as the main repository for the python packages also. You can switch the main repository to repo.fortisoar.fortinet.com so by editing the pip.conf file located at: /opt/cyops-integrations/.env/pip.conf as follows:
index-url=https://repo.fortisoar.fortinet.com/connectors/deps/simple/. If some dependencies fail while installing the connector, you can use the connector configuration popup to try and reinstall the failed dependencies as described in the Connector Store section.

You can also change other relevant pip settings such as altering the timeout or retry count setting. See https://pip.pypa.io/en/stable/user_guide/#config-file for a listing of the relevant pip settings. For example, to increase the timeout value add the following in the pip.conf file: timeout = 60.

For information on installing connectors on an FSR agent, see the Segmented Network Support chapter in the "Administration Guide."

Working with connectors

On the Manage page, you will see the list of installed connectors in the card view. You can perform the following operations on this page:

  • You can search for a connector by its name in the Search box and sort the connectors either alphabetically or by date. Also, when you select Connectors as the Content Type by default, Non Configured connectors are displayed in the Manage tab. You can select Configured from the drop-down to view the configured connectors.
    My Content Page
  • Similarly, you can filter the installed connectors that have an upgraded version, by selecting Upgrade Available from the second drop-down list. For example, version 5.0.0 of the Fortinet FortiGate connector is installed on your system and Fortinet has released a newer version of this connector, then you will see the Fortinet FortiGate connector filtered by the Upgrade Available filter, and you can also see Update Available link on the connector's card:
    Connector Card-Upgrade Available button
    To update a connector, click the Update Available link on the connector card. When you click on a connector that has an updated version, you will see a 'What's new?' section on the configuration page, besides the Update to <version number> button. Clicking the What's New? link displays the highlights of the new version, which you can view to understand what you can expect when you upgrade your connector version. Click the Update to <version number> button to upgrade your connector.
    Connector Updates screen

You can perform the following operations on the connector configuration popup (click the connector card in the Manage page to open the connector configuration popup) of a configured connector:

  • To perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint, or API. If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog. If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.
  • To modify a connector according to your requirements, click the Edit on the connector configuration popup. However, to edit a connector, you must make a local copy of the connector and then make the changes in the same, and then you can save and publish the connector as defined in the Building your own connector chapter.
  • To uninstall a connector, click the Uninstall button, in the connector configuration popup. FortiSOAR displays a Confirmation dialog, click Confirm to uninstall the connector. FortiSOAR displays the "Connector uninstalled successfully" message and the connector is removed from the Manage page. To uninstall a connector, you must be assigned a role that has a minimum of Delete access on the Connectors module.
  • To export the .tgz file of the connector, click the Export button.
  • To view the list of actions that can be performed by the connector and the playbook file that is bundled with the connector, click the Actions & Playbooks tab. Clicking the 'Actions' option on this tab, you can also restrict specific connector actions to specific roles, i.e., users with only those roles would be able to perform that action. For more information, see the Restricting specific connector actions to specific roles section,
  • To view the list of agents on which the connector is installed, click the Agents tab. For more information on agents and how to run remote actions using agents, see the Segmented Network support in FortiSOAR chapter in the "Administration Guide."

How the connector framework verifies the server certificate when it is self-signed

The connector framework is explained in the Building your own connector chapter.

All connector calls are made by the python requests library reading the certificate from /opt/cyops-integrations/.env/lib/python3.6/site-packages/certifi/cacert.pem. Therefore, for any connector, when you set verify_ssl to true, and it's a self-signed cert, then the cacert must be appended to this file. If it's a chain of trust, then you must add the entire chain in the pem format. You must also ensure that the server address added in the connector configuration matches the CN in the certificate.

Note

A .key file has the path to a PEM encoded file containing the private key. A .pem file has the path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.

If you are using the HTTPS proxy for external connections, then you must ensure that the proxy certificate is added here also, if the Verify SSL is set to true in the connector configuration.

Some commands that you can use to get the pem certificate chain:

# openssl s_client -connect {HOSTNAME}:{PORT} -showcerts
OR
If you have the certificate already in a .crt, .cer, .der format, then you need to convert to the pem format: # openssl x509 -inform der -in certificate.cer -out certificate.pem

Role-based Access Control for connector actions

From version 7.0.0 onwards, FortiSOAR introduces Role-based Access Control (RBAC) for connectors, i.e., 'Connector Administrators', i.e., users with Connector Read and Update permissions and Security Read permission can allow access to only certain teams or users, based on roles, to perform certain connector actions. For example, the administrator might want to allow a "Block IP" action to be performed by only certain teams or users in the organization.

The ownership of connector configurations can also be defined, by marking the connector configuration as 'Private'; thereby, controlling who can view and execute that particular connector configuration.

Note

You must configure access control for connector configurations and actions separately for the tenant nodes. Access control for connector configurations and actions cannot be configured from the master.

Restricting specific connector actions to specific roles

By default, all users and roles with appropriate permissions, as defined in the Connector Store section, can view and execute all the connector actions; however, connector administrators can restrict specific actions to specific roles as follows:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Connector Store > Manage.
  3. Select the connector whose connector actions you want to restrict to certain users, based on the roles or specific set of roles that have been assigned to open the Connector Configurations page.
  4. Click the Actions & Playbooks tab:
    Connector Configuration Page - Actions and Playbooks Tab - Assign Roles to Action icon
  5. From the Actions tab, in the row that contains the action that you want to restrict, click the Assign Role(s) to Action icon to display the Assign Role(s) to Action dialog:
    Connector Configuration - Assign Roles to Action icon
  6. Select the roles that would be able to perform this action and then click OK.
    Once a particular action is assigned to specific roles, you can see a Roles Assigned bar in that action's role, which specifies the roles that the users should be assigned to perform that connector action:
    Connector Configuration - Roles Assigned
    Therefore, in this case, if there are users who are not assigned the 'Full App Permissions', 'Playbook Administrator' or 'SOC Analyst' role, and if they try to invoke this action directly on a record, they will be unable to run that action as the action will be disabled:
    Connector action disabled for users not having appropriate permissions

Notes:

  • When a connector is upgraded to a higher version, if there are any roles defined for any connector action in the previous version of the connector, those roles are carried forwarded to the upgraded version.

  • The Playbook designer displays all the connector actions irrespective of the roles of the user creating the playbook. Also, while executing a connector action from the playbook, FortiSOAR does not perform any role check. You can create a playbook as a 'Private' playbook to restrict access. For more information, see the "Playbooks Guide."

  • When a connector action is being executed directly on a record, the roles of the logged-in user will be matched against the roles permitted for the action.

Defining the ownership of a connector's configuration

The ownership of connector configurations can also be defined by setting the visibility of a connector's configuration to 'Private'. By default, the connector configuration is set to 'Public', i.e., it can be viewed by anyone who has appropriate permissions, as defined in the Connector Store section. By setting a connector's configuration to 'Private', you are assigning ownership of that connector configuration to particular teams and thereby only allowing the assigned team owners the right to view and execute that particular connector configuration.

Note

You must configure access control for connector configurations and actions separately for the tenant nodes. Access control for connector configurations and actions cannot be configured from the master.

To set the visibility of connector configurations to 'Private' to restrict the teams who can view and execute that particular connector configuration, do the following:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Automation > Connectors > Installed.
  3. Select the connector whose configuration you want to set to 'Private', i.e., whose configuration you want to restrict to certain teams. By default, connector configurations are set to 'Public'.
  4. To mark a connector configuration as 'Private', click the Private button beside the Visibility parameter:
    Connector Configuration Page - Visibility Parameter
  5. To assign the connector configuration to a particular team, once you have clicked Private, click the Teams (Teams icon) icon to display the Assign Owners dialog.
  6. In the Assign Owners dialog, you will see that the logged-in user's teams are assigned ownership, by default. Click the Red Cross beside the teams whose ownership you want to remove, and select the teams that you want to configure as owners for this connector configuration from the Owners drop-down list and then click Assign:
    Connector Visibility - Assign Owners dialog
  7. Click Submit to assign ownership of this connector configuration.
    Now, in this case, if there are users who are not part of the 'SOC Analysts' team, and if they want to run the actions of the VirusTotal connector on a record, for example, they will observe that the "New Default" configuration will not be visible and only the "Default" configuration is visible:
    Configurations visible in case of Connector RBAC
    Therefore, users can see only those connector configurations to which they have access, as is the case with the above example, the 'New Default' configuration is visible only to users that belong to the 'SOC Analysts' team. However, users belonging to teams other than 'SOC Analysts' can execute playbooks containing a connector step with the 'New Default' configuration that has been created by 'SOC Analysts' users.

Introduction to connectors

Connectors are used to send and retrieve data from various third-party sources. Using connectors, you can connect to external cyber security tools and perform various automated interactions using FortiSOAR™ playbooks.

FortiSOAR has already developed several connectors that can be used to integrate with many external cyber security tools like SIEMs, such as Splunk, and Ticketing systems such as Jira. Connector-specific documentation that is included with each connector covers the process of installing, configuring, and using these connectors. You can see a list of published connectors on the Fortinet Support Site.

FortiSOAR also provides you with several pre-installed connectors or built-ins that you can use within FortiSOAR playbooks, as a connector step, and perform automated operations. For more information on FortiSOAR Built-in connectors, see the "FortiSOAR Built-in connectors" article.

Note

From FortiSOAR release 7.2.1 onwards, integrations are run using the fsr-integrations user instead of the nginx user. Therefore, code snippets that try to write on a file system that is outside /opt/cyops-integrations or /tmp might be impacted and you also need to ensure appropriate permissions have been given to the fsr-integrations user.
Writing on file systems using code snippets outside /tmp is highly discouraged.

You can write a custom connector that can retrieve data from custom sources. You can then use the connector either standalone or within FortiSOAR playbooks and perform automated operations. You can write a custom connector manually, or you can use the FortiSOAR Connector SDK to develop your custom connector. For more information on writing custom connectors, see the Building your own connector chapter.

Use the Connector Store (Content Hub) in the FortiSOAR UI to easily view, search, install, update, and uninstall connectors that are part of the FortiSOAR repository. You can also specify connector configuration using a jinja variable that contains the connector configuration name.

Note

In Release 7.2.0, the Connector navigation take you to the Content Hub with the relevant 'Connectors' filter selected for browsing ease.

Connector Store

Use the Connector Store to easily view, search, install, upgrade, and uninstall connectors that are part of the FortiSOAR repository. Therefore, you can now perform these operations using the FortiSOAR UI instead of the required CLI access. The Content Hub contains all out-of-the-box reference material and product add-ons such as connectors, widgets, and solution packs; whereas the Connector Store has been filtered to display only Connectors.

Caution

You must ensure that repo.fortisoar.fortinet.com is reachable from your FortiSOAR instance. Otherwise, you will see a blank page when you click Content Hub or Automation > Connectors in the left navigation.
In release 7.2.0 update.cybersponse.com has been renamed to https://repo.fortisoar.fortinet.com/. Both these repositories will be available for a while to allow users who are on a release prior to FortiSOAR release 7.2.0 to access connectors and widgets. However, in time, only https://repo.fortisoar.fortinet.com/ will be available.

Following are the permissions that you must be assigned to perform operations on connectors:

  • To work with connectors, i.e., view the connectors listed in the Content Hub and changes made to the Content Hub, you must be assigned a role that has a minimum of Read access on the Application, Connectors, Playbooks, and Content Hub modules, a minimum of Create, Read, Update permissions on the Solution Packs module.
  • To install a connector from the Content Hub or to upload a connector to the Content Hub you must be assigned a role that has a minimum of Read permission on the Security module.
  • Apart from the above, to work with connectors, you need appropriate permissions on the Connectors and Playbooks modules. For example, to install a connector or create a new custom connector, you must be assigned a role that has a minimum of Create and Read access on the Connectors module and Read access on the Playbooks modules, or to upgrade or configure a connector, you must be assigned a role that has a minimum of Update and Read access on the Connectors module and Read access on the Playbooks module.

To open the Connector Store, go to Automation > Connectors, or to go to Content Hub, click Content Hub in the left menu. The Connector Store is filtered to display only connectors, whereas the Content Hub displays all the add-ons. In this chapter the screenshots included are from the Content Hub page; similar screens are displayed on the Connector Store page.
The Discover tab displays all the add-ons, i.e., Connectors, Widgets, and Solution Packs, available in the Content Hub. Use the Filter panel to filter the connectors by clicking the > arrow in the Content Type list and then selecting Connectors:
Market Place > Filtered by Connectors

You can search for a connector by its name in the Search field and sort the content alphabetically (A-Z) or by date. Using the Filters panel, you can filter the connectors displayed in all the tabs based on varied criteria. For more information on Content Hub, see the Content Hub chapter in the "User Guide.' Connectors that are installed appear with a tick on their card. For example, the Active Directory connector in the above image.

To install a connector, click that connector's card, for example, AbuseIPDB, which opens a popup with the connector name:
Connector Name popup to install a connector

The connector popup contains details such as the name and version of the connector, whether the connector is certified or not, who is the publisher of the connector, and the link to the connector documentation. The Summary tab contains a brief description of the connector, and the Contents tab contains a list of actions the connector can perform.

Click Install in the connector name popup to begin the installation of the connector after confirmation, as shown in the following image:
Installing a connector

Once installation is complete, FortiSOAR displays the "Connector Installed successfully" message, and the connector gets added to the Manage page. After installing the connector, you must configure the connector by entering the required configuration details in the connector popup:
Connector Configuration Popup

You can also configure the connector on the Manage page by clicking the connector name card, which will also display the same connector popup. For more information, see the Installing or importing and configuring a connector in FortiSOAR section.

Some connectors have dependencies on additional python packages, which if not installed would hamper the functioning of the connector. By default, the dependencies are resolved from pypi.org and repo.fortisoar.fortinet.com. Dependencies could fail to install due to reasons such as the blocking of users' pypi or not having the latest deps repository on repo.fortisoar.fortinet.com. In such cases where the connectors get installed but the dependencies fail to install, FortiSOAR displays a Connector Dependencies Failed To Install message on the connector configuration popup as shown in the following image:
Connector Configuration popup with Dependencies fail message
You can try to reinstall the dependencies by clicking the Install link.

Dependencies of connectors that are not installed from FortiSOAR Content Hub might fail to install even after a retry since the dependencies for such connectors are not present in the FortiSOAR repository. In such cases, you can download the dependencies from pypi.org and install the dependencies using the information present in https://pip.pypa.io/en/latest/user_guide/#installing-from-local-packages.
To install a package in FortiSOAR, use the following command:
sudo -u fsr-integrations /opt/cyops-integrations/.env/bin/pip install <package>

Installing or importing and configuring a connector in FortiSOAR

Use the Connector Store to install and configure connectors in FortiSOAR.

To install a connector, you must be assigned a role that has a minimum of Create access to the Connectors module. To configure connectors into FortiSOAR, you must be assigned a role that has a minimum of Update access to the Connectors module.

The following procedure describes how to install and configure connector using Connector Store:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Connector Store > Discover.
    On the Discover page, you will see all the connectors, both which are installed and which are not installed. Installed connectors appear with a with a tick on their card. You can search for a connector by its name in the Search box and sort the connectors either alphabetically or by date.
    To install a connector, click that connector's card, which opens a popup with the connector name on which click Install. This process is described in the Connector Store section.
    Once installation is complete, FortiSOAR displays the "Connector Installed successfully" message, and the connector gets added to the Manage page in the 'Active' state; however, you can change the state of the connector from active to inactive by toggling the ACTIVE button.
    To import a connector (.tgz) file into FortiSOAR, click the Manage tab and on the Manage page, click Upload > Upload Connector to display the Upload Connector popup as shown in the following image:
    Importing a connector in FortiSOAR />
    You can drag and drop the connector .tgz file onto the popup or browse to the .tgz file to install the connector in FortiSOAR. If you have an existing version of the connector on your system, then you can click the Replace existing version checkbox, to replace that version of the connector.
    You must check that all the connector dependencies are available or install the additional dependencies to ensure that the connector functions as expected.
  3. To configure a connector, on the Manage page, click the connector card to open the Connector Configuration popup. Enter the required configuration details in the connector configuration popup, as shown in the following image:
    Connector Configuration Popup
    Once you add the configuration details in the connector popup and click Save, FortiSOAR opens a modal window that displays the progress of the configuration and the status of the health check while saving the connector configuration:
    Connector Configuration Modal Window - Successful configuration
    All errors or warnings related to connector configuration, including missing dependencies, invalid configurations, and health check status, are displayed in the modal window:
    Connector Configuration Modal Window - Failed Health Check
    The health check status and missing dependencies are also displayed on the connector configuration popup. You can choose to try to reinstall the dependencies by clicking the Install link that appears alongside the Connector Dependencies Failed To Install message on the modal window or the connector configuration popup as described in the Connector Store section.
    Note: Once you have installed a connector dependency on a FortiSOAR node using the Install link on the connector's Configurations dialog, then that dependency is installed seamlessly on the other nodes of the HA cluster.
    Notes on Configuration:
    • If you are configuring the connector for the first time, then in the Configuration Name field add a name of the configuration.
      Note: You can add multiple configurations for your connector, therefore, you must add a unique Name for each configuration in the Configuration Name field.
    • If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR fetches the configuration and input parameters of the latest available version of that connector. For example, if you have 1.0.0 and 2.0.0 versions of the Database connector and you are configuring the 2.0.0 version of the Database connector, then while configuring the 2.0.0 version, FortiSOAR will fetch the configuration and input parameters from the 1.0.0 version of the Database connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    • To add a new configuration, click the +Add New Configuration button, and then add the name of the configuration and specify the configuration parameters. You can click the < Back to Configuration Selection button to go back to the Configuration page:
      Adding a new connector configuration
    • If you want to update an existing configuration, then select the configuration from the Select Configuration drop-down list and update the configuration parameters. If there is only one configuration, then that configuration will be selected automatically.
      Selecing a connector configuration
    • You can also check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR instance. This connector will point to this configuration by default.
      Important: In the case of the SMTP connector, you must ensure that this option is selected for the configuration that is to be used for sending system notifications.
    • The password type fields in FortiSOAR include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords. If your administrator has configured an external vault to securely store your organization's sensitive data and credentials, then you can use the Dynamic Values dialog to enter the credentials for your connector as shown in the following image:
      Connector Configuration - Vault Option
      For information on Dynamic Values, see the Dynamic Values chapter in the "Playbooks Guide." For information on Password Vault, see the Security Management chapter in the "Administration Guide."
    • You can also define the ownership of connector configurations by setting the visibility of a connector's configuration to 'Private'. For more information, see the Defining the ownership of a connector's configuration section.
    • You can configure connectors for the current FortiSOAR node, an agent, which is used to remotely run actions, or both. For more information on agents and how to run remote actions using agents, see the Segmented Network support in FortiSOAR chapter in the "Administration Guide." You can configure on the current node (Self) or on a remote Agent node (Agent) by clicking the Self, which is the default, or Agent buttons besides Target. You can configure multiple configurations for a connector on both the current node and the agent node. To configure and execute connector actions on the "Agent" node, click Agent, and from the Select Agent drop-down list select the agent on which you want to run the connector actions. If there is only one agent installed, then that agent will be selected automatically.
    • Connectors also include a Verify SSL field, that specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True. For more information, see How the connector framework verifies the server certificate when it's self-signed.
    • To view the documentation associated with a connector, click the Documentation link on the top-right corner of the connector configuration pane.

Points to be considered for connector configurations while upgrading to a newer version of the connector

If you are upgrading a connector to a newer version, you must be assigned a role that has a minimum of Upgrade access to the Connectors module. For example, if you are upgrading the Symantec Security Analytics connector version from v1.0.0 to v2.0.0, then keep a note of the following points:

  • Existing (older) connector configuration fields retain their value, i.e., the value from the older configuration will be displayed in the configuration pane of the newer connector version. New connector configuration field(s), if any, will be added to the connector configuration pane.
  • If the newly added configuration field is mandatory, and FortiSOAR has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field. For more information on the connector framework and the info.json file, see the Building your own connector chapter.
    For information on common connector framework issues, see the Common connector framework errors section in the Debugging common playbook and connector issues article present in the Fortinet Knowledge Base.
  • If the newly added configuration field is mandatory, and FortiSOAR has not specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain a blank value for this configuration field. If you also do not specify a value for this mandatory configuration field, then the connector configuration pane will display Partially Configured, and an error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."
  • If the field type of a mandatory configuration field is changed from the older version to the newer version, for example from a text field to a drop-down list, then the value of that field will not be retrieved from the older version. However, if FortiSOAR has specified its default value (in the info.json file of the connector), then that value will be displayed for this configuration field in the configuration pane of the newer version of the connector. If however FortiSOAR has not defined the default value and you also do not specify a value for this mandatory configuration field, then the configuration pane of the newer version of the connector will contain a blank value for this configuration field, and the connector configuration pane will display Partially Configured. An error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."
  • If the newly added configuration field is optional, and FortiSOAR has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field. If there is no default value is set, then its value is set as blank.

Installing or Updating a FortiSOAR connector using the CLI

All connectors published by FortiSOAR are delivered using a FortiSOAR repository. Use the Connector Store to easily install, update and install connectors that are part of the FortiSOAR repository.

Tooltip The recommended way to install a connector is by using the Connector Store.

You could also set up your FortiSOAR repository and use the yum command to install connectors as a root user:

# yum install cyops-connector-<connectorname>

Note

After you install a connector using the yum command the new connector is not reflected until you refresh the Connectors page.

To update a FortiSOAR-published connector use the following command:

# yum update cyops-connector-<connectorname>

To remove a FortiSOAR-published connector use the following command:

# yum remove cyops-connector-<connectorname>

Note

If you delete a FortiSOAR-published connector using the Connector page in FortiSOAR then you cannot reinstall the RPM of the same connector because the RPM of the connector does not get deleted. Therefore, to remove a FortiSOAR-published connector, you must use the yum remove cyops-connector-<connectorName> command.

Some of the connectors have dependencies on additional python packages. During connector installation, these dependencies are also installed using pip. The default pip settings point to the pypi.python.org repository for downloading these packages. We have also added an alternate repository on repo.fortisoar.fortinet.com to host the connector dependencies. If your instance restricts access to pypi.python.org, the installer fallbacks to this alternate repository for installing the dependencies. However, the connector installation might take longer if there are multiple dependencies since it first tries to fetch each of those from pypi.python.org. In such a case, it is recommended to switch to repo.fortisoar.fortinet.com as the main repository for the python packages also. You can switch the main repository to repo.fortisoar.fortinet.com so by editing the pip.conf file located at: /opt/cyops-integrations/.env/pip.conf as follows:
index-url=https://repo.fortisoar.fortinet.com/connectors/deps/simple/. If some dependencies fail while installing the connector, you can use the connector configuration popup to try and reinstall the failed dependencies as described in the Connector Store section.

You can also change other relevant pip settings such as altering the timeout or retry count setting. See https://pip.pypa.io/en/stable/user_guide/#config-file for a listing of the relevant pip settings. For example, to increase the timeout value add the following in the pip.conf file: timeout = 60.

For information on installing connectors on an FSR agent, see the Segmented Network Support chapter in the "Administration Guide."

Working with connectors

On the Manage page, you will see the list of installed connectors in the card view. You can perform the following operations on this page:

  • You can search for a connector by its name in the Search box and sort the connectors either alphabetically or by date. Also, when you select Connectors as the Content Type by default, Non Configured connectors are displayed in the Manage tab. You can select Configured from the drop-down to view the configured connectors.
    My Content Page
  • Similarly, you can filter the installed connectors that have an upgraded version, by selecting Upgrade Available from the second drop-down list. For example, version 5.0.0 of the Fortinet FortiGate connector is installed on your system and Fortinet has released a newer version of this connector, then you will see the Fortinet FortiGate connector filtered by the Upgrade Available filter, and you can also see Update Available link on the connector's card:
    Connector Card-Upgrade Available button
    To update a connector, click the Update Available link on the connector card. When you click on a connector that has an updated version, you will see a 'What's new?' section on the configuration page, besides the Update to <version number> button. Clicking the What's New? link displays the highlights of the new version, which you can view to understand what you can expect when you upgrade your connector version. Click the Update to <version number> button to upgrade your connector.
    Connector Updates screen

You can perform the following operations on the connector configuration popup (click the connector card in the Manage page to open the connector configuration popup) of a configured connector:

  • To perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint, or API. If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog. If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.
  • To modify a connector according to your requirements, click the Edit on the connector configuration popup. However, to edit a connector, you must make a local copy of the connector and then make the changes in the same, and then you can save and publish the connector as defined in the Building your own connector chapter.
  • To uninstall a connector, click the Uninstall button, in the connector configuration popup. FortiSOAR displays a Confirmation dialog, click Confirm to uninstall the connector. FortiSOAR displays the "Connector uninstalled successfully" message and the connector is removed from the Manage page. To uninstall a connector, you must be assigned a role that has a minimum of Delete access on the Connectors module.
  • To export the .tgz file of the connector, click the Export button.
  • To view the list of actions that can be performed by the connector and the playbook file that is bundled with the connector, click the Actions & Playbooks tab. Clicking the 'Actions' option on this tab, you can also restrict specific connector actions to specific roles, i.e., users with only those roles would be able to perform that action. For more information, see the Restricting specific connector actions to specific roles section,
  • To view the list of agents on which the connector is installed, click the Agents tab. For more information on agents and how to run remote actions using agents, see the Segmented Network support in FortiSOAR chapter in the "Administration Guide."

How the connector framework verifies the server certificate when it is self-signed

The connector framework is explained in the Building your own connector chapter.

All connector calls are made by the python requests library reading the certificate from /opt/cyops-integrations/.env/lib/python3.6/site-packages/certifi/cacert.pem. Therefore, for any connector, when you set verify_ssl to true, and it's a self-signed cert, then the cacert must be appended to this file. If it's a chain of trust, then you must add the entire chain in the pem format. You must also ensure that the server address added in the connector configuration matches the CN in the certificate.

Note

A .key file has the path to a PEM encoded file containing the private key. A .pem file has the path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.

If you are using the HTTPS proxy for external connections, then you must ensure that the proxy certificate is added here also, if the Verify SSL is set to true in the connector configuration.

Some commands that you can use to get the pem certificate chain:

# openssl s_client -connect {HOSTNAME}:{PORT} -showcerts
OR
If you have the certificate already in a .crt, .cer, .der format, then you need to convert to the pem format: # openssl x509 -inform der -in certificate.cer -out certificate.pem

Role-based Access Control for connector actions

From version 7.0.0 onwards, FortiSOAR introduces Role-based Access Control (RBAC) for connectors, i.e., 'Connector Administrators', i.e., users with Connector Read and Update permissions and Security Read permission can allow access to only certain teams or users, based on roles, to perform certain connector actions. For example, the administrator might want to allow a "Block IP" action to be performed by only certain teams or users in the organization.

The ownership of connector configurations can also be defined, by marking the connector configuration as 'Private'; thereby, controlling who can view and execute that particular connector configuration.

Note

You must configure access control for connector configurations and actions separately for the tenant nodes. Access control for connector configurations and actions cannot be configured from the master.

Restricting specific connector actions to specific roles

By default, all users and roles with appropriate permissions, as defined in the Connector Store section, can view and execute all the connector actions; however, connector administrators can restrict specific actions to specific roles as follows:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Connector Store > Manage.
  3. Select the connector whose connector actions you want to restrict to certain users, based on the roles or specific set of roles that have been assigned to open the Connector Configurations page.
  4. Click the Actions & Playbooks tab:
    Connector Configuration Page - Actions and Playbooks Tab - Assign Roles to Action icon
  5. From the Actions tab, in the row that contains the action that you want to restrict, click the Assign Role(s) to Action icon to display the Assign Role(s) to Action dialog:
    Connector Configuration - Assign Roles to Action icon
  6. Select the roles that would be able to perform this action and then click OK.
    Once a particular action is assigned to specific roles, you can see a Roles Assigned bar in that action's role, which specifies the roles that the users should be assigned to perform that connector action:
    Connector Configuration - Roles Assigned
    Therefore, in this case, if there are users who are not assigned the 'Full App Permissions', 'Playbook Administrator' or 'SOC Analyst' role, and if they try to invoke this action directly on a record, they will be unable to run that action as the action will be disabled:
    Connector action disabled for users not having appropriate permissions

Notes:

  • When a connector is upgraded to a higher version, if there are any roles defined for any connector action in the previous version of the connector, those roles are carried forwarded to the upgraded version.

  • The Playbook designer displays all the connector actions irrespective of the roles of the user creating the playbook. Also, while executing a connector action from the playbook, FortiSOAR does not perform any role check. You can create a playbook as a 'Private' playbook to restrict access. For more information, see the "Playbooks Guide."

  • When a connector action is being executed directly on a record, the roles of the logged-in user will be matched against the roles permitted for the action.

Defining the ownership of a connector's configuration

The ownership of connector configurations can also be defined by setting the visibility of a connector's configuration to 'Private'. By default, the connector configuration is set to 'Public', i.e., it can be viewed by anyone who has appropriate permissions, as defined in the Connector Store section. By setting a connector's configuration to 'Private', you are assigning ownership of that connector configuration to particular teams and thereby only allowing the assigned team owners the right to view and execute that particular connector configuration.

Note

You must configure access control for connector configurations and actions separately for the tenant nodes. Access control for connector configurations and actions cannot be configured from the master.

To set the visibility of connector configurations to 'Private' to restrict the teams who can view and execute that particular connector configuration, do the following:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Automation > Connectors > Installed.
  3. Select the connector whose configuration you want to set to 'Private', i.e., whose configuration you want to restrict to certain teams. By default, connector configurations are set to 'Public'.
  4. To mark a connector configuration as 'Private', click the Private button beside the Visibility parameter:
    Connector Configuration Page - Visibility Parameter
  5. To assign the connector configuration to a particular team, once you have clicked Private, click the Teams (Teams icon) icon to display the Assign Owners dialog.
  6. In the Assign Owners dialog, you will see that the logged-in user's teams are assigned ownership, by default. Click the Red Cross beside the teams whose ownership you want to remove, and select the teams that you want to configure as owners for this connector configuration from the Owners drop-down list and then click Assign:
    Connector Visibility - Assign Owners dialog
  7. Click Submit to assign ownership of this connector configuration.
    Now, in this case, if there are users who are not part of the 'SOC Analysts' team, and if they want to run the actions of the VirusTotal connector on a record, for example, they will observe that the "New Default" configuration will not be visible and only the "Default" configuration is visible:
    Configurations visible in case of Connector RBAC
    Therefore, users can see only those connector configurations to which they have access, as is the case with the above example, the 'New Default' configuration is visible only to users that belong to the 'SOC Analysts' team. However, users belonging to teams other than 'SOC Analysts' can execute playbooks containing a connector step with the 'New Default' configuration that has been created by 'SOC Analysts' users.