Version:

Version:

Version:

Version:


Table of Contents

Administration Guide

Download PDF
Copy Link

Segmented Network Support

Overview

FortiSOAR supports segmented networks, which facilitates investigation in a multi-segmented network by allowing secure remote execution of connector actions. If your requirement is to be able to remotely run connector actions, then you can use the "FSR Agent".

Automated ingestion, enrichment, or triage actions using a SOAR platform require network connectivity to various endpoints on which you want to run connector actions. These devices or endpoints, can at times, be in a different network segment than the one where the FortiSOAR node is deployed. To connect to such endpoints in segmented networks, FortiSOAR provides a lightweight component, called the "FSR Agent". A FSR Agent can be deployed in a network segment and configured to receive and execute connector actions from a FortiSOAR node using its secure message exchange. The FSR Agent only needs an outbound network connectivity to the secure message exchange server on its TCP port. It does not need a VPN setup or an inbound network connectivity.

A FSR Agent is small, lightweight, consumes minimal system resources and it is very easy to deploy and maintain. A FSR Agent can represent a standalone agent that can be deployed at a specific endpoint, or a FSR Agent can represent a dedicated tenant. If your requirement is action execution in a segmented network, then a FSR Agent is good enough. However, if you need incident management capabilities, or require to ingest large volumes of data from a source in a remote network, then you must have a dedicated FSR tenant instance.

In cases such as a multi-segmented network where deploying a dedicated FortiSOAR node per segment is not feasible or required you can use the lightweight FSR Agent. You can install multiple agents on your FortiSOAR enterprise node using which you can run remote connector actions on various segments of your network.

Note

You do not require any additional licensing for the FortiSOAR secure message exchange.

For the process of deploying FortiSOAR Agents, see the Deploying FortiSOAR chapter in the "Deployment Guide."

FortiSOAR Agent CLI

Use the FortiSOAR Agent CLI (csagent) to perform various administrative functions on the agent such as, importing a connector, setting configurations for a connector, starting or stopping services, listing connectors, checking the health of the agent, etc. For more details on the options available with csagent, use the help command: csagent --help and also see the Running connector actions on a FSR agent section.

Invoke connector actions using FSR agents in segmented networks

Once you have installed the FSR agent, you can install and configure connectors on the agent and then run remote actions on the FSR agent using connectors.

Minimal permissions required

To use FSR agents to run connector actions:

  • Execute permissions on Connectors.
  • Read permissions on Application and Agents.
Note

A role named "FortiSOAR SNS" is created on upgrade with the permissions listed above. Upgraded users can assign this role to the admin users to start configuring and using agents for various actions. The "FortiSOAR SNS" role must be added to the Agent and Playbook appliance roles.

Installing a connector on an FSR agent

Connectors, including custom connectors or older versions of connectors, which do not have their rpms available on the FortiSOAR server, and which are installed on the FortiSOAR instance can be installed on FSR agents using the FortiSOAR UI. Also, connectors that were created and published using the "Create New Connector" wizard can be installed on FSR agents using the FortiSOAR UI. For more information on the "Create New Connector" wizard, see the "Connectors Guide"
You can also choose to install some pre-defined connectors when you are installing an FSR agent. For information on installing FSR agents see the Deploying FortiSOAR chapter in the "Deployment Guide."

Note

For releases prior to 7.2.0, you can deploy connectors that do not have their rpm available on the FortiSOAR server using the CLI on the agent system details of which are included in the Installing and configuring a custom connector on an FSR agent prior to release 7.2.0 section.

To install connectors on the FSR agent, do the following on the FortiSOAR node:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Content Hub > Manage or Automation > Connectors > Manage. For more information on Content Hub, see the Content Hub chapter in the "User Guide."
    Important: Only connectors that are installed on the FortiSOAR node can be installed on FSR agents.
  3. Click the connector that you want to install on the FSR agent, which opens the Connector Configuration popup.
  4. On the Connector Configuration popup click the Agent tab.
    To install the connector on a new FSR agent, click Install Connector on New Agent, and from the Agents dialog, which contains a list of installed FSR agents, select the FSR agent on which you want to install the connector and click Install.
    Prior to version 7.0.1 the connector rpm, by default, used to get downloaded to the /tmp directory, which could be restricted for writing into it by other users causing the installation to fail. Therefore, from version 7.0.1 onwards, the connector rpm, by default, is downloaded to the /opt/cyops-integrations/cyops_connector_rpm directory. Also, you can configure the directory to which you want the connector rpm to the downloaded. For more information see the Configuring the directory in which to download the connector rpm section.
    Note: The Agents dialog lists only those FSR agents whose Status is "Remote Node Connected."

The Agent tab displays the names of the FSR agents on which the connector is installed, the version of the connector installed, and the connector status. You can also use this tab to install that connector on a new FSR agent, and activate, deactivate, delete, or upgrade the connector on the FSR agent:

Connector Configuration - Agent tab

You can activate, deactivate, or uninstall the connector for a particular FSR agent by clicking the Activate Connector, Deactivate Connector, or Uninstall Connector buttons respectively. If the version of the connector on the FortiSOAR instance and the FSR agent is the same, then the Upgrade Connector button will not be visible in the FSR agent row. However, the version of the connector on the FortiSOAR instance is higher than the version of the connector installed on the FSR agent, then you can upgrade the connector by clicking the Upgrade Connector button.

Note

Activating, deactivating, uninstalling, or upgrading the connector for an FSR agent only activates, deactivates, uninstalls, or upgrades that connector for that particular FSR agent and not for any other FSR agent or the FortiSOAR instance.

To configure connectors, see the Configuring Connectors section.

Configuring the directory in which to download the connector rpm

The connector rpm, by default, is downloaded to the /opt/cyops-integrations/cyops_connector_rpm directory. To configure the directory in which you want the connector rpm to be downloaded do the following:

  1. On the FSR agent:
    1. Create the new directory in which you want the connector rpm to be downloaded.
      Important: Ensure that this newly created directory is given nginx user permission.
    2. Open the /opt/cyops-integrations/integrations/configs/config.ini file and set the conn_rpm_temp_dir parameter value as the directory in which you want the connector rpm to be downloaded.
    3. Save the file and restart the uwsgi service.
  2. On the FortiSOAR (base) node:
    1. Open the /opt/cyops-integrations/integrations/configs/config.ini file and set the conn_rpm_temp_dir parameter value as the directory in which you want the connector rpm to be downloaded.
    2. Save the file and restart the uwsgi service.

Installing and configuring a custom connector on an FSR agent prior to release 7.2.0

From release 7.2.0 onwards, you can install connectors whose rpms are unavailable on the FortiSOAR server on an FSR agent, and also connectors that were created and published using the "Create New Connector" wizard, as mentioned in the Installing a connector on a FSR agent section.
Prior to release 7.2.0, to install and configure a custom connector on a FSR agent, do the following:

  1. Import the custom connector on your FortiSOAR (base) node.
  2. Create a FSR agent installer but do not select the custom connector. For information on creating a FSR agent installer see the 'Adding an FSR agent' section in the Deploying FortiSOAR chapter of the "Deployment Guide."
  3. Run the FSR agent installer on the FSR agent and confirm that the FSR agent is successfully installed. For information on running the FSR agent installer see the 'Installing a FSR agent' section in the Deploying FortiSOAR chapter of the "Deployment Guide."
  4. Copy the custom connectors' .tgz file to the FSR agent's system.
  5. Run the following commands to install and configure custom connectors:
    1. To import a custom connector, use the following command:
      csagent --option import
      With the import command, you can add the following parameters:
      [--name Name]: Name of the connector that you want to import.
      [--version Version Number]: Version number of the connector that you want to import.
      [--path Path]: Path of the folder that contains the connector you want to import.
      [--path Bundle]: Path of the archive that contains the connector you want to import.
      For example, to import version 1.0.0 of the SNS connector, use the following command:
      csagent --option import --name sns_con --version 1.0.0 --bundle /root/sns_con.tgz
    2. To configure a custom connector, use the following command:
      csagent --option configure --name <connector_name> --version <connector_version>
      Once you run the above command you require to specify the values for the name and parameters of the configuration:
      Name of the configuration: ....
      Field 1: ....
      Field 1: ....
      To set the default configuration for the connector, use the csagent --option configure --default command.

Running connector operations on a FSR agent using csagent

Apart from installing and configuring a custom connector (prior to release 7.2.0), you can also perform the following connector operations using csagent:

  • check_health: Checks the health, i.e., the status of the connector, i.e., if the connector is 'Disconnected' or 'Available'. To check the health of a connector, you need to provide the connector name, version, and configuration name with this command:
    csagent --option check_health --name <connector_name> --version <connector_version> --config <configuration_name>

  • execute: Executes a connector operation, i.e., runs a particular action for the specified connector. To execute a connector operation, you need to provide the connector name, version, and configuration name, and also specify the name of the operation that you want to run with this command:
    csagent --option execute --name <connector_name> --version <connector_version> --config <configuration_name> -operation <operation_name>
    After you enter the above command, you will have to specify the parameters (if required) for the operation.

  • remove: Deletes a particular version of the specified connector. To remove a connector, you need to provide the connector name and version with this command:
    csagent --option remove --name <connector_name> --version <connector_version>

  • list_operations: Lists the supported operations for a particular version of the specified connector. To list the operations of a connector, you need to provide the connector name, version, and configuration name with this command:
    csagent --option list_operations --name <connector_name> --version <connector_version> --config <configuration_name>

  • list_configs: Lists the configurations available for a particular version of the specified connector. To list the configurations of a connector, you need to provide the connector name and version with this command:
    csagent --option list_configs --name <connector_name> --version <connector_version>

  • list_connectors: Lists all the connectors that are installed on the system, along with their version numbers and status:
    csagent --option list_connectors

  • services: Starts, stops, or restarts the services on the system:
    csagent --option services --action <start|stop|restart>

Configuring connectors

You can configure connectors for the current FortiSOAR node, the FSR agent, or both. You can configure the connector on the current node (Self) or on a remote FSR 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 FSR agent node.

Tooltip

Configuration details, such as passwords, credentials, or other sensitive data can be stored by your administrator using "Password Vault". However, you will not be able to use these stored credentials to configure a connector on a FSR agent since vaults do not work on agents.

To configure connector, on the Connectors page, click the connector that you want to configure to open the Connector Configuration popup in which you can add connector configurations. To configure and execute connector actions, on the "Self" node, click Self, which is the default, if you are configuring the connector for the first time or if you want to add a new configuration, then click Add new configuration from the Select Configuration drop-down list and then add the name of the configuration and specify the configuration parameters. 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.

To configure and execute connector actions on the "FSR Agent" node, click Agent, and from the Select Agent drop-down list select the FSR agent on which you want to run the connector actions. If there is only one FSR agent installed, then that FSR agent will be selected automatically.

Note

The Select Agent drop-down lists only those FSR agents whose Status is "Remote Node Connected."

If you are configuring the connector for the first time or if you want to add a new configuration, then click Add new configuration from the Select Configuration drop-down list and then add the name of the configuration and specify the configuration parameters. 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. For more information on configuring connectors, see the Introduction to Connectors chapter in the "Connectors" Guide.

Running remote actions

Once you have completed configuring the connectors, you can run remote actions on the FSR agent by using playbooks, or by running connector actions directly on records.

In case you are running remote actions using playbooks, you can add the connector as a step and then choose whether to execute that step on the current FortiSOAR node or remotely on the FSR agent node by clicking the Self or Agent buttons besides Target. By default, Self is selected, which means that the action will run on the current FortiSOAR node, then you must select the configuration using which you want to run the action since the FortiSOAR node can have multiple configurations, from the Configuration drop-down list.

From version 6.4.3 onwards, Listener-based connector configuration on the FSR agent is also supported. Listener-based connectors listen for live events on a server, and then these events are notified to FortiSOAR by triggering a playbook. For example, the Exchange connector, which has enabled its listener-based configuration starts a live listener for the specified email account. Therefore, if any new emails are received in the configured account or folder, the connector fetches that emails and triggers playbooks, such as the ingestion playbook, which is specified in the configuration.

Important: For Listener-based connectors to work and to trigger playbooks such as triggering the data ingestion playbook, the FSR agent appliance must have "Execute" permissions on 'Playbooks'.

From version 6.4.3 onwards, file-based operations are supported on the FSR agent, enabling you to perform connector actions that require file resources from FortiSOAR. For example, the "Get Unread Emails" action of the Exchange connector, has an option where you can choose to upload an attachment received in an email to FortiSOAR. You can perform the following operations:

  • Upload a file to FortiSOAR
  • Download a file from FortiSOAR.
  • Support of any generic API request for GET, PUT, POST, and DELETE methods
    Note: To perform the operations, roles having appropriate permissions to the required modules must be assigned to the agent. For example, to download an attachment, the agent would require a minimum of 'Read' permission on the "Attachment" module.

However, note that any file that is downloaded on the agent using the download file action of the Utilities connector will not be available to any of the next steps in the playbook. For example, if you create a playbook add then add the Utilities connector operation "File: Download File From URL" step for a FSR Agent configuration, add the download URL, and save the step. Next, you add the "File: Create Attachment From File" step in which provide the file reference from "Download" step and save and run the playbook. The playbook will fail with an error such as "Connector step is failing with error 'Invalid input :: Given filename/filepath /tmp/f68ab00fb7da4dfd9db4bb95abb1471e doesn't exists'". This is expected behavior since when a file download operation is performed on a FSR agent, the operation cleans the file when the response is returned to the base FortiSOAR node. Therefore, if any following step expects the downloaded file to be present at the agent will cause that step to fail.

You can click Agent and then from the Choose Agent drop-down list, you can select the FSR agent on which you want to run the action and you must also select the configuration using which you want to run the action since FSR agents can have multiple configurations. If you want the FSR agent configuration to be resolved dynamically, you can click {} in the Configuration field and then specify the connector configuration by either typing the connector configuration name or ID or specifying a Jinja variable that contains the connector configuration name or ID.

Playbook Designer - Adding execution options for the Connector step

In case of a multi-tenant configuration, on the master node, if you click Agent, then you can also select the Pick From Record's Ownership option in the Choose Agent drop-down list, which would then read the record of the tenant and accordingly select the FSR agent to be run the action.

If you have only one configuration for the connector or have specified a default configuration, then that configuration automatically gets selected.

Note

The Configuration drop-down lists only those FSR agents whose Status is "Remote Node Connected."

Next, you can select the action that you want to run, for example "Get IP Reputation", and provide the necessary input parameters for this action and save this step. Then you can continue to build the playbook as per your requirements.

Once you have developed the playbook that you want to execute using a remote FSR agent, and when you execute the same, you will observe in the 'Executed Playbook Log', that the playbook goes into the "Awaiting" state when it reaches the Connector step. This happens because this step is being executed on the remote FSR agent and then the playbook is consuming the result received back from the remote FSR agent for further processing.

Similarly, you can run direct connector actions on FSR agent records. To run direct connector actions on records, open the detail view of a record, for example, the detail view of an alert record and click the Actions button. The Actions list will display the active connectors. Search for actions that you want to perform using the Search Action box. For example, if you want to search for a reputation of an IP address, then you can type IP in the Search Action box, and the connectors that have any action related to an IP address will be displayed:

Searching for actions

As shown in the above image, VirusTotal, IBM XForce, URL Scan.io, etc connectors have "IP" in their actions. Click the down arrow to view the actions associated with IP for each connector. For example, if you click VirusTotal, you will see the "Get IP Reputation" action, which for example we want to perform on the FSR agent. Select the Get IP Reputation action, which displays the VirusTotal dialog. From version 6.4.1 onwards, you are required to specify whether you want to run the action on the current FortiSOAR node or remotely on the FSR agent node by clicking the Self or Agent buttons besides Target. By default, Self is selected, which means that the action will run on the current FortiSOAR node, then you must select the configuration using which you want to run the action since the FortiSOAR node can have multiple configurations. If you click Agent, then you can select the FSR agent on which you want to run the action and you must also select the configuration using which you want to run the action since FSR agents can have multiple configurations.

Specifying the execution mode for the action - Agent Mode

For our example, select Agent, then in the Input tab either enter an IP address or use the value of a record field. From the Relationships to Include list, you can also select the relationships such as Comments, Graphs, etc that you want to include in the output, and then click Execute Action. The action will then be executed on the remote FSR agent, and you will be able to see the output of the action in the Output tab.

Note: RBAC is applicable for FSR Agents, i.e., if you do not have appropriate permissions for FSRAgents, then FSR agents will not be visible for running connector action on records.

Output tab containing results of the action executed on the remote agent

Once you run the connector action, and if you have save the action output, then the action log is displayed in the collaboration panel as shown in the following image:

Executed action output in collaboration panel

From version 6.4.3 onwards, if you run the connector action on the FSR agent, then collaboration panel also displays the name of the FSR agent after the connector name. For example, "VirusTotal on <agent name> | At 08/07/2020 12:15 PM"

For more information on Running connector actions on a record, see the Working with Modules - Alerts & Incidents chapter in the "User Guide."

Upgrading a FSR Agent

You can upgrade a FSR agent from FortiSOAR version 6.4.1 onwards.

Tooltip

If you have upgraded your base FortiSOAR node, then updating your FSR agent to the version of your base FortiSOAR node is highly recommended to ensure compatibility with the base product version and to benefit from the latest enhancements. Also, note that you cannot upgrade your FSR agent node to the latest FortiSOAR version until you have upgraded your base FortiSOAR node.

Before you upgrade an agent ensure the following:

You can upgrade an agent using the following two methods:

  • Automatic Upgrade - Minimum applicable FSR Agent and FortiSOAR Node version for automatic upgrade is 6.4.3.
  • Manual Upgrade - Minimum applicable FSR Agent version for manual upgrade is 6.4.1.

Performing an Automatic Upgrade

You can perform an automatic upgrade for a FSR Agent that is on version 6.4.3 (or later).

To perform an automatic upgrade, do the following:

  1. Log on to your base FortiSOAR node as an administrator and click the Settings icon to open the System page.
  2. In the Agent Configurations section, click Agents in the left menu.
  3. On the Agents page, in the Agent Actions column, click the Update link:
    Agents Page - Update link
    Clicking the Update link opens the Agent Upgrade dialog.
  4. The Agent Upgrade dialog contains the current version information of your FSR Agent and the version it to which it will be upgraded, as well as other information such as prerequisites to the upgrade and expected downtime:
    Agents Upgrade Dialog
    Click Start Automatic Upgrade to display a confirmation dialog, and once you click Confirm, the FSR Agent begins to get automatically upgraded. You can see messages related to the upgrade on the same screen and once the FSR Agent is successfully upgraded to the same version as your base FortiSOAR node, you will no longer see the Update link in the Agent Actions column.

Performing a Manual Upgrade

If automatic upgrade of your FSR Agent fails due to any reason, then you can try to manually upgrade your FSR Agent using the following steps:

  1. Log on to your base FortiSOAR node as an administrator and click the Settings icon to open the System page.
  2. In the Agent Configurations section, click Agents in the left menu.
  3. On the Agents page, in the Agent Actions column, click the Update link. Clicking the Update link opens the Agent Upgrade dialog.
  4. On the Agent Upgrade dialog, click Perform Manual Upgrade, which in turn displays a message to download and deploy the installer:
    Agents Upgrade Dialog - Manual Upgrade
  5. Click Download Agent Installer to download the upgrade file named as <agent-name>-install.bin to your VM.
  6. Copy and paste the <agent-name>-install.bin to your FSR agent's VM (FSR Agent Node).
  7. SSH to the FSR agent's VM as a root user and run the following command:
    # sh install.bin or # ./install.bin
    Now, your FSR agent is upgraded to the same version as your base FortiSOAR node, and the Update link is no longer displayed in the Agent Actions column.

Troubleshooting

Files to be used for troubleshooting

Use the "connectors.log" to troubleshoot FortiSOAR connectors. This log is located at: /var/log/cyops/cyops-integrations/connectors.log.

Use the "config.ini" file to update the connector settings, such as changing the logging level of connectors. This file is located at: /opt/cyops-integrations/integrations/configs/config.ini. Once you complete updating the "config.ini" file, you must restart the cyops-integrations-agent service.

Use the "agent_config.yml" file on the FSR agent instance for details such as the FortiSOAR node to which the FSR agent requires to be connected, the secure message exchange to be used, etc. This file is located at: /opt/cyops-integrations/integrations/configs/agent_config.yml.

Deactivated FSR agent does not come back to the connected state even after activating the FSR agent

Activating a deactivated FSR agent does not change its connection state from "Remote Node Unreachable" to "Remote Node Connected" if the live connection mechanism does not correctly reflect the status.

Resolution

Restart the cyops-integrations-agent service on the FSR agent.

FSR Agents configuration page displays a "Agent <Agent UUID> does not exist" error when you click the Export Config link

This issue occurs if you have removed the default admin team, i.e., "SOC Team" and have not assigned the new admin team to the agent and playbook appliance.

Resolution

Recommended not to remove the default "SOC Team". However, if you have removed the SOC Team, then you must create a new admin team and assign that team to the agent and playbook appliance. To assign the new admin team to the agent and playbook appliance, click Settings > Appliances to open the Appliances page, and then click the Agent row to edit the agent appliance page. On the Edit Appliance page, in the Team and Role section, in the Teams table, select the new admin team to assign the same to the agent appliance. Perform the same steps for the playbook appliance.

Segmented Network Support

Overview

FortiSOAR supports segmented networks, which facilitates investigation in a multi-segmented network by allowing secure remote execution of connector actions. If your requirement is to be able to remotely run connector actions, then you can use the "FSR Agent".

Automated ingestion, enrichment, or triage actions using a SOAR platform require network connectivity to various endpoints on which you want to run connector actions. These devices or endpoints, can at times, be in a different network segment than the one where the FortiSOAR node is deployed. To connect to such endpoints in segmented networks, FortiSOAR provides a lightweight component, called the "FSR Agent". A FSR Agent can be deployed in a network segment and configured to receive and execute connector actions from a FortiSOAR node using its secure message exchange. The FSR Agent only needs an outbound network connectivity to the secure message exchange server on its TCP port. It does not need a VPN setup or an inbound network connectivity.

A FSR Agent is small, lightweight, consumes minimal system resources and it is very easy to deploy and maintain. A FSR Agent can represent a standalone agent that can be deployed at a specific endpoint, or a FSR Agent can represent a dedicated tenant. If your requirement is action execution in a segmented network, then a FSR Agent is good enough. However, if you need incident management capabilities, or require to ingest large volumes of data from a source in a remote network, then you must have a dedicated FSR tenant instance.

In cases such as a multi-segmented network where deploying a dedicated FortiSOAR node per segment is not feasible or required you can use the lightweight FSR Agent. You can install multiple agents on your FortiSOAR enterprise node using which you can run remote connector actions on various segments of your network.

Note

You do not require any additional licensing for the FortiSOAR secure message exchange.

For the process of deploying FortiSOAR Agents, see the Deploying FortiSOAR chapter in the "Deployment Guide."

FortiSOAR Agent CLI

Use the FortiSOAR Agent CLI (csagent) to perform various administrative functions on the agent such as, importing a connector, setting configurations for a connector, starting or stopping services, listing connectors, checking the health of the agent, etc. For more details on the options available with csagent, use the help command: csagent --help and also see the Running connector actions on a FSR agent section.

Invoke connector actions using FSR agents in segmented networks

Once you have installed the FSR agent, you can install and configure connectors on the agent and then run remote actions on the FSR agent using connectors.

Minimal permissions required

To use FSR agents to run connector actions:

  • Execute permissions on Connectors.
  • Read permissions on Application and Agents.
Note

A role named "FortiSOAR SNS" is created on upgrade with the permissions listed above. Upgraded users can assign this role to the admin users to start configuring and using agents for various actions. The "FortiSOAR SNS" role must be added to the Agent and Playbook appliance roles.

Installing a connector on an FSR agent

Connectors, including custom connectors or older versions of connectors, which do not have their rpms available on the FortiSOAR server, and which are installed on the FortiSOAR instance can be installed on FSR agents using the FortiSOAR UI. Also, connectors that were created and published using the "Create New Connector" wizard can be installed on FSR agents using the FortiSOAR UI. For more information on the "Create New Connector" wizard, see the "Connectors Guide"
You can also choose to install some pre-defined connectors when you are installing an FSR agent. For information on installing FSR agents see the Deploying FortiSOAR chapter in the "Deployment Guide."

Note

For releases prior to 7.2.0, you can deploy connectors that do not have their rpm available on the FortiSOAR server using the CLI on the agent system details of which are included in the Installing and configuring a custom connector on an FSR agent prior to release 7.2.0 section.

To install connectors on the FSR agent, do the following on the FortiSOAR node:

  1. Log on to FortiSOAR.
  2. On the left navigation pane, click Content Hub > Manage or Automation > Connectors > Manage. For more information on Content Hub, see the Content Hub chapter in the "User Guide."
    Important: Only connectors that are installed on the FortiSOAR node can be installed on FSR agents.
  3. Click the connector that you want to install on the FSR agent, which opens the Connector Configuration popup.
  4. On the Connector Configuration popup click the Agent tab.
    To install the connector on a new FSR agent, click Install Connector on New Agent, and from the Agents dialog, which contains a list of installed FSR agents, select the FSR agent on which you want to install the connector and click Install.
    Prior to version 7.0.1 the connector rpm, by default, used to get downloaded to the /tmp directory, which could be restricted for writing into it by other users causing the installation to fail. Therefore, from version 7.0.1 onwards, the connector rpm, by default, is downloaded to the /opt/cyops-integrations/cyops_connector_rpm directory. Also, you can configure the directory to which you want the connector rpm to the downloaded. For more information see the Configuring the directory in which to download the connector rpm section.
    Note: The Agents dialog lists only those FSR agents whose Status is "Remote Node Connected."

The Agent tab displays the names of the FSR agents on which the connector is installed, the version of the connector installed, and the connector status. You can also use this tab to install that connector on a new FSR agent, and activate, deactivate, delete, or upgrade the connector on the FSR agent:

Connector Configuration - Agent tab

You can activate, deactivate, or uninstall the connector for a particular FSR agent by clicking the Activate Connector, Deactivate Connector, or Uninstall Connector buttons respectively. If the version of the connector on the FortiSOAR instance and the FSR agent is the same, then the Upgrade Connector button will not be visible in the FSR agent row. However, the version of the connector on the FortiSOAR instance is higher than the version of the connector installed on the FSR agent, then you can upgrade the connector by clicking the Upgrade Connector button.

Note

Activating, deactivating, uninstalling, or upgrading the connector for an FSR agent only activates, deactivates, uninstalls, or upgrades that connector for that particular FSR agent and not for any other FSR agent or the FortiSOAR instance.

To configure connectors, see the Configuring Connectors section.

Configuring the directory in which to download the connector rpm

The connector rpm, by default, is downloaded to the /opt/cyops-integrations/cyops_connector_rpm directory. To configure the directory in which you want the connector rpm to be downloaded do the following:

  1. On the FSR agent:
    1. Create the new directory in which you want the connector rpm to be downloaded.
      Important: Ensure that this newly created directory is given nginx user permission.
    2. Open the /opt/cyops-integrations/integrations/configs/config.ini file and set the conn_rpm_temp_dir parameter value as the directory in which you want the connector rpm to be downloaded.
    3. Save the file and restart the uwsgi service.
  2. On the FortiSOAR (base) node:
    1. Open the /opt/cyops-integrations/integrations/configs/config.ini file and set the conn_rpm_temp_dir parameter value as the directory in which you want the connector rpm to be downloaded.
    2. Save the file and restart the uwsgi service.

Installing and configuring a custom connector on an FSR agent prior to release 7.2.0

From release 7.2.0 onwards, you can install connectors whose rpms are unavailable on the FortiSOAR server on an FSR agent, and also connectors that were created and published using the "Create New Connector" wizard, as mentioned in the Installing a connector on a FSR agent section.
Prior to release 7.2.0, to install and configure a custom connector on a FSR agent, do the following:

  1. Import the custom connector on your FortiSOAR (base) node.
  2. Create a FSR agent installer but do not select the custom connector. For information on creating a FSR agent installer see the 'Adding an FSR agent' section in the Deploying FortiSOAR chapter of the "Deployment Guide."
  3. Run the FSR agent installer on the FSR agent and confirm that the FSR agent is successfully installed. For information on running the FSR agent installer see the 'Installing a FSR agent' section in the Deploying FortiSOAR chapter of the "Deployment Guide."
  4. Copy the custom connectors' .tgz file to the FSR agent's system.
  5. Run the following commands to install and configure custom connectors:
    1. To import a custom connector, use the following command:
      csagent --option import
      With the import command, you can add the following parameters:
      [--name Name]: Name of the connector that you want to import.
      [--version Version Number]: Version number of the connector that you want to import.
      [--path Path]: Path of the folder that contains the connector you want to import.
      [--path Bundle]: Path of the archive that contains the connector you want to import.
      For example, to import version 1.0.0 of the SNS connector, use the following command:
      csagent --option import --name sns_con --version 1.0.0 --bundle /root/sns_con.tgz
    2. To configure a custom connector, use the following command:
      csagent --option configure --name <connector_name> --version <connector_version>
      Once you run the above command you require to specify the values for the name and parameters of the configuration:
      Name of the configuration: ....
      Field 1: ....
      Field 1: ....
      To set the default configuration for the connector, use the csagent --option configure --default command.

Running connector operations on a FSR agent using csagent

Apart from installing and configuring a custom connector (prior to release 7.2.0), you can also perform the following connector operations using csagent:

  • check_health: Checks the health, i.e., the status of the connector, i.e., if the connector is 'Disconnected' or 'Available'. To check the health of a connector, you need to provide the connector name, version, and configuration name with this command:
    csagent --option check_health --name <connector_name> --version <connector_version> --config <configuration_name>

  • execute: Executes a connector operation, i.e., runs a particular action for the specified connector. To execute a connector operation, you need to provide the connector name, version, and configuration name, and also specify the name of the operation that you want to run with this command:
    csagent --option execute --name <connector_name> --version <connector_version> --config <configuration_name> -operation <operation_name>
    After you enter the above command, you will have to specify the parameters (if required) for the operation.

  • remove: Deletes a particular version of the specified connector. To remove a connector, you need to provide the connector name and version with this command:
    csagent --option remove --name <connector_name> --version <connector_version>

  • list_operations: Lists the supported operations for a particular version of the specified connector. To list the operations of a connector, you need to provide the connector name, version, and configuration name with this command:
    csagent --option list_operations --name <connector_name> --version <connector_version> --config <configuration_name>

  • list_configs: Lists the configurations available for a particular version of the specified connector. To list the configurations of a connector, you need to provide the connector name and version with this command:
    csagent --option list_configs --name <connector_name> --version <connector_version>

  • list_connectors: Lists all the connectors that are installed on the system, along with their version numbers and status:
    csagent --option list_connectors

  • services: Starts, stops, or restarts the services on the system:
    csagent --option services --action <start|stop|restart>

Configuring connectors

You can configure connectors for the current FortiSOAR node, the FSR agent, or both. You can configure the connector on the current node (Self) or on a remote FSR 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 FSR agent node.

Tooltip

Configuration details, such as passwords, credentials, or other sensitive data can be stored by your administrator using "Password Vault". However, you will not be able to use these stored credentials to configure a connector on a FSR agent since vaults do not work on agents.

To configure connector, on the Connectors page, click the connector that you want to configure to open the Connector Configuration popup in which you can add connector configurations. To configure and execute connector actions, on the "Self" node, click Self, which is the default, if you are configuring the connector for the first time or if you want to add a new configuration, then click Add new configuration from the Select Configuration drop-down list and then add the name of the configuration and specify the configuration parameters. 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.

To configure and execute connector actions on the "FSR Agent" node, click Agent, and from the Select Agent drop-down list select the FSR agent on which you want to run the connector actions. If there is only one FSR agent installed, then that FSR agent will be selected automatically.

Note

The Select Agent drop-down lists only those FSR agents whose Status is "Remote Node Connected."

If you are configuring the connector for the first time or if you want to add a new configuration, then click Add new configuration from the Select Configuration drop-down list and then add the name of the configuration and specify the configuration parameters. 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. For more information on configuring connectors, see the Introduction to Connectors chapter in the "Connectors" Guide.

Running remote actions

Once you have completed configuring the connectors, you can run remote actions on the FSR agent by using playbooks, or by running connector actions directly on records.

In case you are running remote actions using playbooks, you can add the connector as a step and then choose whether to execute that step on the current FortiSOAR node or remotely on the FSR agent node by clicking the Self or Agent buttons besides Target. By default, Self is selected, which means that the action will run on the current FortiSOAR node, then you must select the configuration using which you want to run the action since the FortiSOAR node can have multiple configurations, from the Configuration drop-down list.

From version 6.4.3 onwards, Listener-based connector configuration on the FSR agent is also supported. Listener-based connectors listen for live events on a server, and then these events are notified to FortiSOAR by triggering a playbook. For example, the Exchange connector, which has enabled its listener-based configuration starts a live listener for the specified email account. Therefore, if any new emails are received in the configured account or folder, the connector fetches that emails and triggers playbooks, such as the ingestion playbook, which is specified in the configuration.

Important: For Listener-based connectors to work and to trigger playbooks such as triggering the data ingestion playbook, the FSR agent appliance must have "Execute" permissions on 'Playbooks'.

From version 6.4.3 onwards, file-based operations are supported on the FSR agent, enabling you to perform connector actions that require file resources from FortiSOAR. For example, the "Get Unread Emails" action of the Exchange connector, has an option where you can choose to upload an attachment received in an email to FortiSOAR. You can perform the following operations:

  • Upload a file to FortiSOAR
  • Download a file from FortiSOAR.
  • Support of any generic API request for GET, PUT, POST, and DELETE methods
    Note: To perform the operations, roles having appropriate permissions to the required modules must be assigned to the agent. For example, to download an attachment, the agent would require a minimum of 'Read' permission on the "Attachment" module.

However, note that any file that is downloaded on the agent using the download file action of the Utilities connector will not be available to any of the next steps in the playbook. For example, if you create a playbook add then add the Utilities connector operation "File: Download File From URL" step for a FSR Agent configuration, add the download URL, and save the step. Next, you add the "File: Create Attachment From File" step in which provide the file reference from "Download" step and save and run the playbook. The playbook will fail with an error such as "Connector step is failing with error 'Invalid input :: Given filename/filepath /tmp/f68ab00fb7da4dfd9db4bb95abb1471e doesn't exists'". This is expected behavior since when a file download operation is performed on a FSR agent, the operation cleans the file when the response is returned to the base FortiSOAR node. Therefore, if any following step expects the downloaded file to be present at the agent will cause that step to fail.

You can click Agent and then from the Choose Agent drop-down list, you can select the FSR agent on which you want to run the action and you must also select the configuration using which you want to run the action since FSR agents can have multiple configurations. If you want the FSR agent configuration to be resolved dynamically, you can click {} in the Configuration field and then specify the connector configuration by either typing the connector configuration name or ID or specifying a Jinja variable that contains the connector configuration name or ID.

Playbook Designer - Adding execution options for the Connector step

In case of a multi-tenant configuration, on the master node, if you click Agent, then you can also select the Pick From Record's Ownership option in the Choose Agent drop-down list, which would then read the record of the tenant and accordingly select the FSR agent to be run the action.

If you have only one configuration for the connector or have specified a default configuration, then that configuration automatically gets selected.

Note

The Configuration drop-down lists only those FSR agents whose Status is "Remote Node Connected."

Next, you can select the action that you want to run, for example "Get IP Reputation", and provide the necessary input parameters for this action and save this step. Then you can continue to build the playbook as per your requirements.

Once you have developed the playbook that you want to execute using a remote FSR agent, and when you execute the same, you will observe in the 'Executed Playbook Log', that the playbook goes into the "Awaiting" state when it reaches the Connector step. This happens because this step is being executed on the remote FSR agent and then the playbook is consuming the result received back from the remote FSR agent for further processing.

Similarly, you can run direct connector actions on FSR agent records. To run direct connector actions on records, open the detail view of a record, for example, the detail view of an alert record and click the Actions button. The Actions list will display the active connectors. Search for actions that you want to perform using the Search Action box. For example, if you want to search for a reputation of an IP address, then you can type IP in the Search Action box, and the connectors that have any action related to an IP address will be displayed:

Searching for actions

As shown in the above image, VirusTotal, IBM XForce, URL Scan.io, etc connectors have "IP" in their actions. Click the down arrow to view the actions associated with IP for each connector. For example, if you click VirusTotal, you will see the "Get IP Reputation" action, which for example we want to perform on the FSR agent. Select the Get IP Reputation action, which displays the VirusTotal dialog. From version 6.4.1 onwards, you are required to specify whether you want to run the action on the current FortiSOAR node or remotely on the FSR agent node by clicking the Self or Agent buttons besides Target. By default, Self is selected, which means that the action will run on the current FortiSOAR node, then you must select the configuration using which you want to run the action since the FortiSOAR node can have multiple configurations. If you click Agent, then you can select the FSR agent on which you want to run the action and you must also select the configuration using which you want to run the action since FSR agents can have multiple configurations.

Specifying the execution mode for the action - Agent Mode

For our example, select Agent, then in the Input tab either enter an IP address or use the value of a record field. From the Relationships to Include list, you can also select the relationships such as Comments, Graphs, etc that you want to include in the output, and then click Execute Action. The action will then be executed on the remote FSR agent, and you will be able to see the output of the action in the Output tab.

Note: RBAC is applicable for FSR Agents, i.e., if you do not have appropriate permissions for FSRAgents, then FSR agents will not be visible for running connector action on records.

Output tab containing results of the action executed on the remote agent

Once you run the connector action, and if you have save the action output, then the action log is displayed in the collaboration panel as shown in the following image:

Executed action output in collaboration panel

From version 6.4.3 onwards, if you run the connector action on the FSR agent, then collaboration panel also displays the name of the FSR agent after the connector name. For example, "VirusTotal on <agent name> | At 08/07/2020 12:15 PM"

For more information on Running connector actions on a record, see the Working with Modules - Alerts & Incidents chapter in the "User Guide."

Upgrading a FSR Agent

You can upgrade a FSR agent from FortiSOAR version 6.4.1 onwards.

Tooltip

If you have upgraded your base FortiSOAR node, then updating your FSR agent to the version of your base FortiSOAR node is highly recommended to ensure compatibility with the base product version and to benefit from the latest enhancements. Also, note that you cannot upgrade your FSR agent node to the latest FortiSOAR version until you have upgraded your base FortiSOAR node.

Before you upgrade an agent ensure the following:

You can upgrade an agent using the following two methods:

  • Automatic Upgrade - Minimum applicable FSR Agent and FortiSOAR Node version for automatic upgrade is 6.4.3.
  • Manual Upgrade - Minimum applicable FSR Agent version for manual upgrade is 6.4.1.

Performing an Automatic Upgrade

You can perform an automatic upgrade for a FSR Agent that is on version 6.4.3 (or later).

To perform an automatic upgrade, do the following:

  1. Log on to your base FortiSOAR node as an administrator and click the Settings icon to open the System page.
  2. In the Agent Configurations section, click Agents in the left menu.
  3. On the Agents page, in the Agent Actions column, click the Update link:
    Agents Page - Update link
    Clicking the Update link opens the Agent Upgrade dialog.
  4. The Agent Upgrade dialog contains the current version information of your FSR Agent and the version it to which it will be upgraded, as well as other information such as prerequisites to the upgrade and expected downtime:
    Agents Upgrade Dialog
    Click Start Automatic Upgrade to display a confirmation dialog, and once you click Confirm, the FSR Agent begins to get automatically upgraded. You can see messages related to the upgrade on the same screen and once the FSR Agent is successfully upgraded to the same version as your base FortiSOAR node, you will no longer see the Update link in the Agent Actions column.

Performing a Manual Upgrade

If automatic upgrade of your FSR Agent fails due to any reason, then you can try to manually upgrade your FSR Agent using the following steps:

  1. Log on to your base FortiSOAR node as an administrator and click the Settings icon to open the System page.
  2. In the Agent Configurations section, click Agents in the left menu.
  3. On the Agents page, in the Agent Actions column, click the Update link. Clicking the Update link opens the Agent Upgrade dialog.
  4. On the Agent Upgrade dialog, click Perform Manual Upgrade, which in turn displays a message to download and deploy the installer:
    Agents Upgrade Dialog - Manual Upgrade
  5. Click Download Agent Installer to download the upgrade file named as <agent-name>-install.bin to your VM.
  6. Copy and paste the <agent-name>-install.bin to your FSR agent's VM (FSR Agent Node).
  7. SSH to the FSR agent's VM as a root user and run the following command:
    # sh install.bin or # ./install.bin
    Now, your FSR agent is upgraded to the same version as your base FortiSOAR node, and the Update link is no longer displayed in the Agent Actions column.

Troubleshooting

Files to be used for troubleshooting

Use the "connectors.log" to troubleshoot FortiSOAR connectors. This log is located at: /var/log/cyops/cyops-integrations/connectors.log.

Use the "config.ini" file to update the connector settings, such as changing the logging level of connectors. This file is located at: /opt/cyops-integrations/integrations/configs/config.ini. Once you complete updating the "config.ini" file, you must restart the cyops-integrations-agent service.

Use the "agent_config.yml" file on the FSR agent instance for details such as the FortiSOAR node to which the FSR agent requires to be connected, the secure message exchange to be used, etc. This file is located at: /opt/cyops-integrations/integrations/configs/agent_config.yml.

Deactivated FSR agent does not come back to the connected state even after activating the FSR agent

Activating a deactivated FSR agent does not change its connection state from "Remote Node Unreachable" to "Remote Node Connected" if the live connection mechanism does not correctly reflect the status.

Resolution

Restart the cyops-integrations-agent service on the FSR agent.

FSR Agents configuration page displays a "Agent <Agent UUID> does not exist" error when you click the Export Config link

This issue occurs if you have removed the default admin team, i.e., "SOC Team" and have not assigned the new admin team to the agent and playbook appliance.

Resolution

Recommended not to remove the default "SOC Team". However, if you have removed the SOC Team, then you must create a new admin team and assign that team to the agent and playbook appliance. To assign the new admin team to the agent and playbook appliance, click Settings > Appliances to open the Appliances page, and then click the Agent row to edit the agent appliance page. On the Edit Appliance page, in the Team and Role section, in the Teams table, select the new admin team to assign the same to the agent appliance. Perform the same steps for the playbook appliance.