Custom integration

The CUSTOM section enables you to connect to any third-party system in order to automatically trigger an incident response in that third-party system as the result of a security event detected by FortiEDR. After you define a Custom Integration connector (and its actions) and configure a relevant Playbook policy, an automatic incident response action will be triggered in the third-party system upon the triggering of a security event.

Custom integration is only available to users with Admin or IT users and have the Custom script option enabled. For more information about user roles and permissions, see Users.

To set up a custom integration connector in FortiEDR:

1. Click the Add Connector button and select Custom Connector from the dropdown list. The following displays:

   

2. Fill in the following fields:

   Field	Description
   Jumpbox	Select the FortiEDR Jumpbox that will communicate with the third-party system. A FortiEDR deployment must include a Jumpbox that has connectivity to the external system of this custom integration connector. This Jumpbox must be exclusive to this organization and cannot function as a Core.
   Name	Specify a name of your choice to be used to identify this custom connector.
   Host	Specify the IP or DNS address of the relevant third-party application.
   Port	Specify the port that is used for API communication with the relevant third-party application.
   API Key/Credentials	Specify authentication details of the relevant third-party application. To use an API token, click the API Key radio button and copy the token value into the text box. To use API credentials, click the Credentials radio button and enter the relevant third-party application’s API username and password.

3. In the Actions area on the right, define the action to be taken by this custom connector, as follows:
   • To trigger an action on a custom connected third-party system, click the + Add Action button to display the following popup window:

     

     1. In the Action dropdown menu, select one of the previously defined actions (which were defined in FortiEDR as described Custom integration).

        -OR-

     2. Click the Create New Action button in this popup window to define a new action that can be triggered according to the definitions in the Playbook, as described in the next section below. The following displays:

        

        Fill out the fields of this window as follows in order to define a new action to be triggered in response to an incident.

        In order to trigger this action, a Playbook policy must be defined that triggers this action to execute the script when a security event is triggered. The definition of this new action here automatically adds this action as an option in a Playbook policy. This action however, is not selected by default in the Playbook policy. Therefore, you must go to the Playbook policy and select it in order for it to be triggered when a security event is triggered.

        Field	Definition
        Name	Enter any name for this action.
        Description	Enter a description of this action.
        Upload	Upload a Python script that calls an API from the third-party system in order to perform the relevant action. Python 2.7 or later is supported. The Python script must be created according to the coding conventions that can be displayed by clicking the icon next to the Action Scripts field. The following displays providing an explanation of the coding conventions and provides various links that you can click to see more detail and/or to download sample files.

     3. Click Save. The new action is then listed in the Actions area.
4. Select this action to associate it with the custom connector.
5. You can click the Test button next to it to execute this action.

   A new row is added to the CUSTOM section of the Automated Incident Response – Playbooks page. In order for this custom integration connector to trigger an action, you must define it in the Playbook, as described below.

   The actions that you define here can also be selected as an action for a Firewall integration connector or Network Access Control (NAC) integration connector. These integration connectors might use the same API. Alternatively, you may need to upload a different script that will be used to perform the same action on different third-party products. You can associate several scripts with the same action and select the appropriate one per connector. For example, an IM notification action could have two scripts – one for notifications via Slack and the other for notifications via Teams.

Playbooks configuration

To configure an automated incident response that triggers an action using this custom integration connector upon the triggering of a security event:

1. Navigate to the SECURITY SETTINGS > Playbooks page.
2. Open the Playbook policy that is applied on devices for which you want the custom action (defined above) to apply.
3. In the CUSTOM section, place a checkmark in the relevant Classification columns next to the row of that action.
4. In the dropdown menu next to the action, select the connector with which to perform the action or click Select All, as shown below:

   

   The example above showed how to configure two custom connectors by using the same action named IM notification in the Playbook – one for notifications via Teams and the other for notifications via Slack.

   FortiEDR is now configured to trigger this action in the third-party system upon the triggering of a security event. This automatic incident response action appears in the CLASSIFICATION DETAILS area of the Events page of the FortiEDR Console.