Fortinet black logo

Deployment Guide

Deploying FortiSOAR

Copy Link
Copy Doc ID 0448600f-1d0e-11ec-8c53-00505692583a:158469
Download PDF

Deploying FortiSOAR

This chapter covers the process of deploying FortiSOAR, and the initial configuration required for FortiSOAR. You can perform the initial configuration for FortiSOAR using the FortiSOAR Configuration Wizard.

The following image displays the high-level tasks for deploying FortiSOAR:

High-level process for deploying FortiSOAR

You can also install FortiSOAR 7.0.2 using the FortiSOAR installer (.bin file). For more information, see Installing FortiSOAR 7.0.2 using the FortiSOAR installer.

You can also set up a local offline repository and deploying FortiSOAR using the offline repository. For more information, see the Setting up a local offline repository and deploying using the offline repository chapter.

Planning

Recommended Resource Requirements

Note

The maximum hard drive or physical volume size for FortiSOAR must be limited to 2 TB.

Virtual Machine (VM)

Minimum Specifications
  • 8 available vCPUs
  • 20 GB available RAM
  • 500 GB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC
Recommended Specifications
  • 8 available vCPUs
  • 32 GB available RAM
  • 1 TB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC
Note

In case of multi-tenant configurations, contact FortiSOAR Support for sizing requirements.

Supported Hypervisors

  • AWS AMI
  • VMware ESXi versions 5.5, 6.0, and 6.5
  • Redhat KVM

VM Inbound Networking

Enable the following ports for the VM within your VM network:

  • 22 Management (ssh)
  • 443 User Interface (https)

VM Outbound Networking

For FortiSOAR to correctly interact with your network, you must provide access between the FortiSOAR VM and the third-party products and services configured within your network.

To accomplish this, enable the following ports for SSH, SMTP, and HTTPs access:

  • 22 Management (ssh)
  • 25 Email SMTP relay server. This port can be different based on your environment.
  • 443 User Interface (https)
Note

Depending on the type of connectors used in Playbooks, you might require to open other ports or services.

Credentials

Credentials to access SSH management and the FortiSOAR User Interface are:

Username: csadmin

Password: changeme

From FortiSOAR 6.0.0 onwards, the UI password of the 'csadmin' user for AWS is set to the "instance_id" of your instance.
To know the instance ID of your FortiSOAR AWS instance, you can SSH and run the cloud-init query instance_id command.

Tooltip

From version 7.0.2 onwards, first FortiSOAR SSH login, password change is mandated for the 'csadmin' users, thereby enhancing the security of your csadmin account and preventing unauthorized parties from accessing the FortiSOAR administration account.

Requirements

It is highly recommended that Internet access is provided for a FortiSOAR upgrade, license deployment, and also for installing new out-of-the-box connectors.

Add the following URLs in the allowlist of your Firewall or Proxy servers:

For upgrading FortiSOAR, installing connectors, and accessing the widget library: https://update.cybersponse.com

For Connector Dependencies: https://pypi.python.org

For synchronization of FortiSOAR license details: https://globalupdate.fortinet.net

Port Requirements

The following ports require to be locally open for various services, i.e., all these ports do not require to be open on the firewall for external access, they are used only inter-service communication within the appliance:

Service Port Number
elasticsearch (Elasticsearch service uses this port for REST communication).
Port needs to be opened in case of high availability (HA) environments.
9200
elasticsearch (Elasticsearch service uses this port for communication between nodes) 9300
rabbitmqserver 5672
cyops routing agent through nginx postman 7575
cyops workflow (celery) through nginx /sealab 8888
postgresql
Port needs to be opened in case of HA environments.
5432
cyops auth server through nginx 8443
cyops integration (uwsgi) through nginx 9595
cyops-tomcat (hosts cyops-gateway, cyops-notifier) 8080
MQ TCP traffic
Port needs to be opened in case of HA environments.
5671
cyops-api (crud-hub) [php-fpm is used to host] 443
rabbitmq service 25672, 4389

If you need to access ssh or start a terminal session from outside your network to troubleshoot or manage services or databases, then port "22/tcp open ssh" should be opened on the firewall for external access. Port 443/tcp open https must always be opened on the firewall for external access.

Importing the FortiSOAR Virtual Appliance

Use a vSphere Client or a viclient to import the Virtual Appliance into the ESX/ESXi server. See the VMware documentation for steps on how to import a Virtual Appliance.

Note

After you import the FortiSOAR Virtual Appliance and the FortiSOAR system boots up, the IP address of the system is displayed on the command prompt. You can share this IP address with users who require to configure FortiSOAR using the FortiSOAR Configuration Wizard.

Downloading the FortiSOAR Virtual Appliance from the Support Portal

You can download the required FortiSOAR Virtual Appliance image from the support portal, which contains images for AWS, KVM-Supported QCOW2 and VMware. You will need these images to be downloaded before you can begin deploying FortiSOAR using vSphere or vCenter, or KVM. In case of AWS, you can directly lunch an instance using the images present on the AWS Marketplace images.

To download the FortiSOAR Virtual Appliance do the following:

  1. Log onto support.fortinet.com.
  2. Click Support > Firmware Download.
    Download the firmware for FSR virtual appliance
  3. On the Fortinet Firmware Images And Software Releases page from the Select Product drop-down list select FortiSOAR.
    Fortinet Firmware Images And Software Releases page
    The page displays various released versions of FortiSOAR , and contains two tabs: Release Notes and Downloads.
    Fortinet Firmware Images And Software Releases page: Release Notes and Downloads tabs
    To download the Release Notes for a particular version, click the version and build number link, which opens the FortiSOAR Document Library, from where you can download the release notes for that particular version.
  4. To download a firmware image do the following:
    1. Click the Download tab
    2. Navigate through the directory structure to open the page containing the required images. For example, to download a firmware image for version 7.0.0, click v7.0.0 > 7.0 > 7.0.0 and locate the firmware image you require.
      Download FSR Firmware using HTTPS link
    3. Download the firmware image by clicking the HTTPS link.
      An HTTPS connection is used to download the firmware image.
    4. Click the Checksum link for the image that you downloaded.
      The image file name and checksum code are displayed in the Get Checksum Code dialog box.
    5. Confirm that the checksum of the downloaded image file matches the checksum provided on the download site.

Deploying the FortiSOAR Virtual Appliance

Download the required FortiSOAR Virtual Appliance image from the Support Portal, which contains images for AWS, KVM-Supported QCOW2 and VMware. You will need these images to be downloaded before you can begin deploying FortiSOAR using vSphere or vCenter, or KVM. In case of AWS, you can directly lunch an instance using the images present on the AWS Marketplace images. For information on how to download images from the support portal, see the Downloading the FortiSOAR Virtual Appliance from the Support Portal section. Also, ensure that your VM is configured as per the specifications outlined in the Planning section.

Deploying the FortiSOAR Virtual Appliance using vSphere or vCenter

Download the VMware enterprise and secure message exchange images as outlined in the Downloading the FortiSOAR Virtual Appliance from the Support Portal section. Then once you have ensured that you have met all the specifications, deploy the FortiSOAR Virtual Appliance using vSphere or vCenter. See the VMware documentation for steps on how to deploy a Virtual Appliance.

Deploying the FortiSOAR Virtual Appliance using AWS

Once you have ensured that you have met all the specifications, perform the following steps to deploy the FortiSOAR Virtual Appliance on Amazon Web Services (AWS):

  1. Log into your AWS account and from the Amazon EC2 console dashboard, choose Launch Instance, to launch the FortiSOAR instance.
  2. On the Choose an Amazon Machine Image (AMI) page, enter fortinet-fortisoar in the search bar to find the latest version of the FortiSOAR Enterprise and SME (secure message exchange) AMIs in the AWS Marketplace. Choose the AMI and start configuring the instance. Following is a reference screenshot:

    AWS Marketplace - FortiSOAR AMIs

After you complete deploying your FortiSOAR and you connect the first time to your FortiSOAR VM, the EULA agreement page is displayed. You must accept the EULA to continue with your FortiSOAR configuration. If you do not accept the EULA, then the OS will halt, and you have to restart your FortiSOAR VM (power off-power on) and reconnect to the FortiSOAR VM and accept EULA to continue with your FortiSOAR configuration.

Deploying FortiSOAR using KVM

Once you have ensured that you have met all the specifications, perform the following steps to deploy the FortiSOAR QCOW2 on KVM:

  1. Download the KVM-Supported QCOW2 images as outlined in the Downloading the FortiSOAR Virtual Appliance from the Support Portal section.
  2. Copy the FortiSOAR QCOW2 image to the VM Image Datastore.
  3. Open the Virtual Machine Manager application for KVM VM deployment.
     Virtual Machine Manager application
  4. Click File > New Virtual Machine.
    Creating a new VM
  5. On the New VM dialog, select the Import existing disk image option and click Forward.
    New VM creation - Choosing to install the OS
  6. Click Browse and select the FortiSOAR image from the Image Datastore, select the OS type as Linux and Version as CentOS 7, and click Forward.
    New VM creation - Entering the storage path
    This displays the Storage Volume screen, where you can choose the storage volume, or click Cancel to keep as default:
    New VM creation - Choosing the storage volume
  7. Enter 32768 (i.e. 32768 MB=32 GB) in the Memory (RAM) field and 8 in the CPUs field and click Forward.
    New VM creation - Specifying Memory and CPU values
  8. Enter the name that you want to specify for the new virtual machine in the Name field, select the correct network adapter for this new virtual machine from the Network Selection field, and click Finish to complete the deployment.
    Note: The network adapter type would change depending upon your KVM environment. As an example, in the following image the "Bridge adapter.." is selected. You must select the proper network adapter as per your environment requirements.
    New VM creation - Specifying Name and Network Adapter
  9. Post VM deployment, the VM boots up and brings up the login console as shown in the following image:
    New VM - Login Console

CLI Deployment

If you want to deploy the FortiSOAR QCOW2 image (of version 6.4.1 for example) on KVM using the CLI, then use the following command:
virt-install --memory 32768 --vcpus 8 --import --os-type=linux --os-variant centos7.0 --name <virtual machine name> --disk </path/to/qcow2/image/.qcow2> --network <network type=kvm network name>

Following is an example using the above CLI command:
virt-install --memory 32768 --vcpus 8 --import --os-type=linux --os-variant centos7.0 --name FortiSOAR-Enterprise-6.4.1 --disk /var/lib/libvirt/fortisoar/fortisoar-kvm-enterprise-6.4.1-2133.qcow2 --network bridge=virbr0

Post deployment, perform the initial configuration steps using the FortiSOAR Configuration Wizard.

Installing FortiSOAR 7.0.2 using the FortiSOAR installer

This section describes the steps that you require to follow to install FortiSOAR 7.0.2 on a plain CentOS system that has minimal skew selected while installing CentOS.

Prerequisites

Before you begin this procedure, ensure that you can access update.cybersponse.com. In case you have configured proxies, then ensure that you have added your proxy settings in the following files:

  • /etc/environment
  • /etc/yum.conf
  • /etc/pip.conf

Following is an example of adding proxy settings to the above-mentioned files:

  • /etc/environment
    product_yum_server=update.cybersponse.com
    http_proxy='http://username:password@10.1.1.0:8080'
    no_proxy='127.0.0.1','localhost'
    https_proxy='http://username:password@10.1.1.0:8080'
  • /etc/yum.conf
    proxy=http://10.1.1.0:8080
    proxy_username=username
    proxy_password=password
  • Create the /etc/pip.conf file as follows:
    [global]
    extra-index-url=
    https://update.cybersponse.com/prod/connectors/deps/simple/
    proxy='http://username:password@10.1.1.0:8080'

Procedure

The following procedure describes the steps that you require to run for installing FortiSOAR 7.0.2 Enterprise Edition and Secure Message Exchange:

  1. Provision a CentOS 7 (minimal) VM [recommended version 7.7.1908 (Core)], with the wget package.
  2. Ensure your VM has disk space of 500 GB. If you have a large volume of data being ingested daily, it is recommended to have a disk space of 1 TB. It is recommended to have a thin provisioned disk.
    You can add three more disks to your Virtual Machine (VM) and create separate Logical Volume Management (LVM) partitioning for PostgreSQL, Elasticsearch and FortiSOAR RPM data. For more information about multiple disk support, see the Multidisk Support article present in the Fortinet Knowledge Base.
    Note: The database disk requires most volume is required for the database disk. So if you are provisioning the volume with multiple disks, the size of the data disk is the most important and should be sufficiently large.
    Refer to the table that is present at the end of this procedure for the minimum and recommended disk sizes.
  3. To ensure that your ssh session does not timeout execute the screen command.
    For more information on how to handle session timeouts, see the Handle session timeouts while running the FortiSOAR upgrade article present in the Fortinet Knowledge Base.
  4. To download the installer for FortiSOAR 7.0.2:
    # wget https://update.cybersponse.com/7.0.2/install-fortisoar-7.0.2.bin
  5. To install FortiSOAR 7.0.2 run the following command as a root user:
    # sh install-fortisoar-7.0.2.bin
    OR
    chmod +x install-fortisoar-7.0.2.bin
    ./install-fortisoar-7.0.2.bin
    The installer will display the following installation options:
    Enterprise
    OR
    Secure Message Exchange
    Choose Enterprise in this case and complete the installation.
    Note: If you are installing FortiSOAR in a closed or air-gapped environment, you will see a message such as "The system does not have connectivity to https://globalupdate.fortinet.net. Connectivity....", ignore these warning messages and proceed with the installation as there is no requirement to check the check connectivity to globalupdate.fortinet.com in case of an air-gapped environment. For information on licensing in the case of closed environments, see the FortiSOAR licensing using FortiManager topic in the Licensing FortiSOAR chapter.
  6. Once the installation is complete, exit the terminal session and log back in using the following credentials:
    Username: csadmin
    Password: changeme
  7. Once you have logged into FortiSOAR, you will be asked to accept the EULA. You must accept the EULA before you can proceed to the FortiSOAR Configuration Wizard.
  8. Retrieve your FortiSOAR Device UUID, which is created automatically by the FortiSOAR installation. This Device UUID is used to identify each unique FortiSOAR environment. A root user can directly run the following command to retrieve the Device UUID:
    csadm license --get-device-uuid
    Use this Device UUID to get your FortiSOAR license using the process detailed in the Licensing FortiSOAR chapter.
  9. Before you deploy your FortiSOAR license, ensure that you can connect to https://globalupdate.fortinet.net, else the license deployment will fail. Connectivity to this address is required for fetching the license entitlements and product functioning post-upgrade.
    You can deploy your FortiSOAR license using the FortiSOAR UI or using the FortiSOAR Admin CLI. For more information on deploying the FortiSOAR license, see the Licensing FortiSOAR chapter.
  10. Once your system is licensed, you can log on to the FortiSOAR UI using the default credentials:
    Username: csadmin
    Password: changeme

Following is a table that contains the minimum and recommended disk sizes:

Mount Point Recommended Size Minimum Size
/ 6 GB -
/boot 1.5 GB -

/tmp

2 GB

1 GB

/opt

9.5 GB

-

/var

4 GB

-

/var/lib/pgsql

500 GB

20 GB

/var/lib/elasticsearch

150 GB

-

/var/lib/rabbitmq

11.5 GB

-

/var/log

5 GB

2 GB

/var/log/audit

1 GB

/var/log/cyops/coredump

49 GB

-

/home

10 GB

-

Installing the secure message exchange

A secure message exchange establishes a secure channel that is used to relay information to the agents or tenant nodes. To create a dedicated secure channel, you are required to add the reference of the installed and configured secure message exchange, when you add agent or tenant nodes to your environment. A default "self" secure message exchange configuration is available and can be enabled. However, for a production setup, we recommend that you configure a separate secure message exchange. For more information, see the Enabling the secure message exchange and Adding a secure message exchange sections.

Steps for installing the secure message exchange are as follows:

  1. Provision a CentOS 7 (minimal) VM [recommended version 7.7.1908 (Core)], with the wget package.
  2. Ensure your VM has disk space of minimum 50 GB, recommended is 100 GB. It is recommended to have a thin provisioned disk.
  3. To ensure that your ssh session does not timeout execute the screen command.
    For more information on how to handle session timeouts, see the Handle session timeouts while running the FortiSOAR upgrade article present in the Fortinet Knowledge Base.
  4. To download the installer for FortiSOAR 7.0.2 secure message exchange:
    wget https://update.cybersponse.com/7.0.2/install-fortisoar-7.0.2.bin
  5. To install FortiSOAR 7.0.2 secure message exchange run the following command as a root user:
    # sh install-fortisoar-7.0.2.bin
    OR
    chmod +x install-fortisoar-7.0.2.bin
    ./install-fortisoar-7.0.2.bin
    The installer will display the following installation options:
    Enterprise
    OR
    Secure Message Exchange
    Choose Secure Message Exchange in this case and complete the installation.

Once you have installed the secure message exchange, a FortiSOAR Secure Message Exchange Configuration Wizard similar to the FortiSOAR Configuration Wizard is automatically run on the first ssh login by the csadmin user and it performs the initial configuration steps that are required for the Secure Message Exchange. In the FortiSOAR Secure Message Exchange Configuration Wizard you require to provide certain inputs such as the hostname of the Secure Message Exchange VM, port numbers to be used for the API and TCP connections to the Secure Message Exchange, etc., which are required to complete the initial configuration steps for the Secure Message Exchange.

Installing FortiSOAR on RHEL using the FortiSOAR installer

This section describes the steps that you require to follow to install FortiSOAR on a Red Hat Enterprise Linux (RHEL) system.

  1. Register your RHEL instance:
    subscription-manager register --username <username> --password <password>--auto-attach --force
  2. Enable the optional repositories:
    subscription-manager repos --enable=rhel-7-server-optional-rpms
  3. Install the required packages:
    yum install policycoreutils-python gcc java-11-openjdk yum-utils -y && yum install wget screen vim -y
  4. Follow the steps outlined in the Installing FortiSOAR7.0.2 using the FortiSOAR installer topic to install FortiSOAR on your RHEL instance.

FortiSOAR Configuration Wizard

Interactive VM configuration

A configuration wizard runs automatically on the first ssh login by the csadmin user and performs the initial configuration steps that are required for FortiSOAR. The wizard guides you through the configuration process with appropriate instructions so that you can efficiently perform the initial configuration required for FortiSOAR. To begin running the configuration wizard, you must accept the Fortinet End User License Agreement.

The wizard performs the following configuration steps:

  1. Change hostname: (Optional) You can change the hostname for your FortiSOAR VM. Ensure that the hostname that you provide is resolvable. If the hostname gets resolved by a DNS server, ensure that you provide only the node name and not the complete FQDN. The wizard checks if the hostname is valid or not; and throws an error in case of an invalid hostname. FortiSOAR optionally also asks for additional DNS servers.
    In an environment where DHCP is not enabled, i.e., in case of a static IP environment, the configuration wizard fails since it cannot get the network. Therefore, from version 6.4.1 onwards, the configuration wizard detects whether the FortiSOAR VM has an IP; if the wizard cannot detect an IP, a Static IP page is displayed where you can add the Static IP, Gateway, Netmask, DNS1 and DNS2, ensuring that the configuration wizard completes without failure. This also provides users with the flexibility of changing their environment from DHCP to Static without worrying that the configuration wizard will fail since it cannot get the network.
    If the configuration wizard detects an IP, i.e. in case of a DHCP enabled system, the DNS servers input page is displayed.
    Also, if you change the hostname, the configuration wizard automatically updates the HOSTNAME variable in /etc/profile.
  2. Configure Proxy: (Optional) You can configure an https/http proxy server to serve all https/http requests from FortiSOAR. To configure an https or http proxy, you must specify the username and password, and the hostname and the port number of the HTTPS or HTTP proxy server. For example to configure an HTTPS proxy, enter the proxy details in the following format: https://user:password@[ip/fqdn]:port. You can also configure a comma-separated list of hostnames that do not require to be routed through a proxy server. For example, [ip1/fqdn1], [ip2/fqdn2]
  3. Update network configuration: This is an automatic process.
  4. Set up intra-service authentication: This is an automatic process to generate new appliance keys unique to your instance for communication to the FortiSOAR services.
  5. Generate certificates: This is an automatic process; you do not require to provide any inputs.
  6. Generate Device UUID: This is an automatic process; you do not require to provide any inputs. The wizard also saves the Device UUID in the /home/csadmin/device_uuid file.
    This Device UUID is required for when you are generating your license for FortiSOAR. For more information, see the Licensing FortiSOAR chapter.
    Important: You get logged out after the FortiSOAR VM is configured, so that the changes can take effect. Therefore, you require to ssh again to the FortiSOAR VM.
  7. Reset database passwords: This is an automatic process to reset database password to a new password unique to your instance.
  8. Restart services: This is an automatic process to reset all FortiSOAR services.
  9. Configure default HA cluster: This is an automatic process that creates the default single-node HA cluster. This FortiSOAR server is created as a primary-active node.
  10. Install python libraries: This is an automatic process to install some python libraries required by FortiSOAR.

After the FortiSOAR Configuration Wizard is run, it displays the following:

  • Device UUID
  • Path where the Device UUID is saved
  • Path of the Configuration Wizard log
Note

If your FortiSOAR Configuration Wizard displays errors when it is being run, then you can troubleshoot the FortiSOAR Configuration Wizard errors by checking its logs, which are located at /var/log/cyops/install/config_vm_<timestamp>. For example, /var/log/cyops/install/config-vm-09_Nov_2018_05h_37m_36s.log.

Tooltip

If you want to replace the Self-Signed Certificates with your own signed certificates, see the Updating the SSL certificates topic.

Non-interactive VM configuration

The FortiSOAR Configuration Wizard also has a non-interactive mode that automatically performs the initial configuration steps (as mentioned in the Interactive VM Configuration section) that are required for FortiSOAR, without any inputs from the user. The configuration in this case is done by using the default inputs from the configuration file that is shipped along with the FortiSOAR appliance. Non-interactive VM configuration is useful when users are expecting a ready-to-use appliance.

The default configuration files are:

  • For the Enterprise edition: /opt/cyops/configs/scripts/config-vm-enterprise-default.conf
    and

  • For the Secure Message Exchange: /opt/cyops/configs/scripts/config-vm-sme-default.conf

You can customize the non-interactive VM configuration by providing additional custom configuration files. Values provided in the custom configuration files overrides the ones mentioned in the default configuration file.

A configuration file has the following format:

key=value

Following is a list of supported key names with their sample values:

  • hostname=sample_hostname

  • dns=sample_dns_name

  • proxy_https=https://userid:password@www.sample-https.com:9999

  • proxy_http=http://userid:password@www.sample-http.com:9999

  • proxy_noproxy=127.0.0.1,sample-no-proxy

  • static_ip=192.168.51.181

  • gateway=192.168.51.1

  • netmask=255.255.255.0

  • dns1=192.168.60.100

  • dns2=8.8.8.8

  • message_queue_user_id=admin

  • message_queue_password=changeme

  • message_queue_api_port=15671

  • message_queue_tcp_port=5671

Guidelines to creating custom configuration files:

  • Empty keys are ignored. For example: hostname=.

  • The userid and password parameters are optional in the proxy_httpand proxy_https keys. The format of the URL is: proxy_https=https://www.sample-https.com:9999
    Also note that proxy_http, proxy_https, and proxy_noproxy are applicable to only the 'Enterprise' edition

  • The static_ip, gateway, netmask, dns1, and dns2 keys are considered only in case of a 'non-dhcp environment'.
    The static_ip, gateway, netmask, and dns1 keys are mandatory. The dns2 key is optional.

  • The message_queue_user_id, message_queue_password, message_queue_api_port, and message_queue_tcp_port keys are applicable to only the 'Secure Message Exchange' edition

  • Keys that are not applicable to a particular edition are ignored. For example, if you add the proxy_http to the 'Secure Message Exchange' edition, the proxy_http will be ignored.

Once your system is appropriately deployed, it is recommended that you install the Content Pack (FSR-IR-CONTENT-PACK). The Content Pack enables users to experience the power of FortiSOAR incident response, both automated and manual, without having to configure FortiSOAR to ingest any data. With out-of-box (OOB) demo records and their corresponding playbooks that demonstrate various use cases along with best practices to combat various types of incidents. From version 7.0.0 onwards, you can install the content before deploying your FortiSOAR license. For more information on the Content Pack, see the Incident Response Content Pack article present in FUSE (Fortinet User Community).

Pointing the ntpd service to a valid ntp server

If the time on the FortiSOAR server is not correct, you might see issues such as ingestion workflows not pulling the latest data from an external source. It is highly recommended to keep the time in sync with an NTP server. Therefore, if you require to change the system time on your FortiSOAR instance, then perform this step immediately after running the FortiSOAR Configuration Wizard.

The ntpd service runs on your FortiSOAR instance, and it requires to be pointed to a valid ntp server. If the /etc/ntp.conf file contains entries to ntp server(s) that are not valid; then you might face Invalid System Time issues where you might not be able to log on to your FortiSOAR instance. Edit the /etc/ntp.conf file to add details of a valid ntp server(s). For a list of common NTP servers, go to https://www.ntppool.org/en/.

In case your FortiSOAR VM does not have access to the internet, then you must edit the /etc/ntp.conf to add details of a valid ntp server within your datacenter.

Editing the VM configuration

It is not necessary to perform the following steps, but they can quickly assist you to get access to the FortiSOAR VM:

  1. Setting a static IP
  2. Determining your DHCP IP Address

Setting a static IP

  1. On the ESX console for your FortiSOAR VM, login to the VM as the csadmin user.
  2. Type sudo –i in the terminal and press Enter to become a root user.
  3. Once you are logged in to the terminal, type nmtui and press Enter.
    Entering nmtui on the terminal
  4. On the first screen, select the Edit a connection option and press Enter.
    Edit a connection option
  5. On the second screen, select the connection listed under Ethernet, which is Wired connection 1 and select <Edit...>.
    Select the Ethernet connection
  6. Use the arrow keys to select <Show> that appears to the right of the IPv4 Configuration option and press Enter.
  7. Enter the required information for your network. You must enter all the information, such as IP Address, Gateway, DNS servers address, on this screen:
    IPv4 Configuration
  8. (Optional) If you want to configure IPv6, repeat steps 5 and 6 and then enter the required information, such as IPv6 Address, for your network.
  9. Ensure that you have selected the Automatically connect and Available to all users options.
    Automatically connect and Available to all users options
  10. Select <OK> and press Enter.
  11. Select <Back> and press Enter.
  12. Select <OK> and press Enter.
  13. Restart the network service using the systemctl restart network command.

Once the network service restarts, you can use the assigned static IP.

Determining your DHCP IP address

  1. On the ESX console for your FortiSOAR VM, login to the FortiSOAR VM as the root user.
  2. Type ifconfig | more in the terminal and press Enter.
    Your IP address is listed in the eth** section, next to inet, as displayed in the following image:
    DHCP IP address'
Note

Once you have completed configuring the hostname and IP address ensure that the default inbound ports mentioned in the 'VM Inbound Networking' section are open and accessible.

Now you must follow the licensing process required for FortiSOAR and then you can use this IP address to log on to the FortiSOAR UI and begin the configuring the system. See the Licensing FortiSOAR chapter for more information.

Deploying FSR Agents

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 FSRAgent 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 FSRagent 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.

Note

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

From version 7.0.2 onwards, you can use client certificate based authentication to create connections between the FSR agent and secure message exchange. Prior to the 7.0.2 release, basic authentication using username and password was used to create connections between FSR agent and secure message exchange. Going forward, you can configure the following types of authentications to connect FSRagent and secure message exchange:

  • Basic Authentication: Uses username and password to create connections between FSR agent and secure message exchange.
  • Basic Authentication with Peer Verification: Uses username and password to create connections between FSR agent and secure message exchange, and also performs 'Certificate Verification'. This process will verify that the clients which are attempting to connect can be trusted by presenting a certificate that is signed by a CA and trusted by the server; thereby ensuring that only trusted clients can connect to the secure message exchange.
  • Client Certificate Authentication: Presents a certificate to the server which is signed by a trusted CA. It is recommended that you create the certificate with the common name as the name of your agent or tenant. This provides enhanced security as this gives the facility to connect only to trusted clients.

To enable client certificate authentication, you can specify the authentication type as 'Certificate Auth' while adding a FSR agent.

To enforce client certificate verification, you must provide a pair of exchange event listener client certificates and exchange event listener client key when you are adding a secure message exchange. Client verification ensures that whenever any client wants to connect to secure message exchange that client must present the client certificate to the secure message exchange for verification. You must also provide the pair of exchange event listener client certificates and exchange event listener client key, if you have enabled mutual TLS (mTLS). Use the csadm mq mtls command to enable or disable mTLS. For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."

Architecture

Architecture of Segmented Network Support

Recommended Resource Requirements for Virtual Machines (VM)

Recommended specifications for Secure Message Exchange

  • 8 available vCPUs
  • 16 GB available RAM
  • 100 GB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC

Recommended specifications for FSR agents

  • 4 GB available RAM
  • CentOS Linux release 7.9.2009 (kernel-3.10.0-1160.6.1.el7.x86_64) or Red Hat Enterprise Linux (RHEL) Server release 7.9 (Maipo) (Kernel - 13.10.0-1160.el7)

Prerequisites for installing a FSR agent

  • Ensure that the VM on which you want to install the FSR agent matches the recommended specifications, see Recommended specifications for FSR agents.
  • Ensure that update.cybersponse.com is reachable or resolvable from the VM on which you want to install the FSR agent.
  • Ensure that the secure message exchange that you have specified when you have added the FSR agent is reachable or resolvable from the VM.
  • Ensure that the following packages are installed on the instance where you are going to install the FSR agent:
    • Python36-devel: The FSR agent runtime needs "python36-devel". During FSR agent installation, the installer looks for an existing installation, and in the case, it is not installed, tries to install it using yum install. If this package is not found, the FSR agent installation will fail.
    • GCC: Some connectors have a dependency on GCC. Therefore, the FSR agent installer looks for an existing installation, and tries to install it using yum install. If this package is not found, the FSR agent installation will display a "warning" and will not fail the installation. You can install GCC later on a FSR agent using the yum install gcc command, if you want to use a connector that is dependent on GCC.
      You can either keep these packages pre-installed on the FSR agent's system, or along with the default repos ensure that the following repos are enabled, so that they get installed during agent binary installation:
      For CentOS: CentOS-Base.repo
      For RHEL: rhel-7-server-optional-rpm and rhel-server-rhscl-7-rpms for RHEL
      Note: If the connector has dependency on any other package or application to work then that package or application will require to be separately installed on the FSR agent. For example, the nmap connector requires the nmap application to be installed, therefore you would require to install this application separately on the agent.

Process of setting up a FSR agent

  1. Add a secure message exchange.
    A Secure Message server is used for communication with FSR Agents or dedicated tenant nodes. You can add both externally deployed secure message exchange or the Default (Embedded) secure message exchange.
    If you want to use the local i.e., Default (Embedded) secure message exchange to connect to external FSR agents and run remote actions on various segments of your network or in case of a dedicated tenant, then you must enable the secure message exchange as described in the Enabling the secure message exchange section. In case of an external secure message exchange, then add the secure message exchange as described in the Adding a Secure Message Exchange section.
  2. Add FSR agents to your FortiSOAR instance. See the Adding a FSR agent section.
  3. Install FSR agents. See the Installing a FSR agent section.

Minimal permissions required

To configure and install FSR agents:

  • Create, Read, and Update permissions on Agents.
  • Read permissions on Application and Secure Message Exchange.
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.

Enabling the secure message exchange

A secure message exchange establishes a secure channel using which you can relay information to your FSR agent or tenant nodes. A Default (Embedded) secure message exchange configuration is available on every FortiSOAR node that can be enabled as explained in this section.

To use the Default (Embedded) secure message exchange to connect to external FSR agents, you must enable the secure message exchange using the csadm secure-message-enchange enable command. For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."

Note

For a production setup, it is recommended that you add and configure an external secure message exchange for handling scale and high availability.

Adding a Secure Message Exchange

Install a secure message exchange and then adding the reference of this secure message exchange in the tenant or FSR agent node(s) creates a dedicated secure channel of communication. You can have more than one secure message exchange in the configuration. You can distribute tenants across secure message exchanges based on the geographical locations, scale, or compliance policies of the respective customers.

To add a secure message exchange, do the following:

  1. Log on to FortiSOAR as an administrator.
    Note: Administrator role must have Create, Update, and Delete permissions on Secure Message Exchange.
  2. Click the Settings (Setting icon) icon to open the System page.
  3. On the System page, you will see the Agent Configurations section. Click the Secure Message Exchange item in the left menu, to configure the secure message exchange.
    Secure Message Exchanges Page
  4. Click Add Secure Message Exchange on the Secure Message Exchanges page.
    Important: To add a secure message exchange and configure tenants, you must have a role that has a minimum of Create and Read permissions on the Secure Message Exchange and Tenants modules. To update the details of the secure message exchange you additionally require Update permissions on the Secure Message Exchange and Tenants modules.
    To edit the configuration of an existing secure message exchange, click the secure message exchange row whose configuration you want to update. This displays the Edit Secure Message Exchange dialog. Update the configuration parameters, as required, in the dialog and click Update.
  5. In the Add New Secure Message Exchange dialog, configure the following parameters:
    1. In the Name field, enter the name of the secure message exchange that you have configured to act as a secure channel of data replication between the FortiSOAR node and tenant or FSR agent nodes.
    2. In the Address field, enter the FQHN (Fully Qualified Host Name) of the secure message exchange.
      Important: Ensure that the FQHN matches the Certificate Name (CN) or the Subject Alternative Name (SAN) provided in the SSL certificate used to configure the secure message exchange.
    3. In the API Port field, enter the RabbitMQ Management port number that you had specified while configuring the secure message exchange, and ensure that the FortiSOAR node has outbound connectivity to the secure message exchange at this port.
      By default, it is set as 15671.
    4. In the TCP Port field, enter the TCP port number that you had specified while configuring the secure message exchange, and ensure that the FortiSOAR node has outbound connectivity to the secure message exchange at this port.
      By default, it is set as 5671.
    5. In the User Name field, enter the username you will use to login to your secure message exchange as an administrator.
      By default, it is set as admin.
    6. In the Password field, enter the password you will use to login to your secure message exchange as an administrator.
    7. In the CA Certificate field, copy-paste the certificate text of the Certificate Authority (CA) that has signed the secure message exchange certificate in the pem format. You can also upload the certificate file. If it is a chain, then the complete chain must be provided.
      By default, the CA certificate for the FortiSOAR self-signed certificate is present at the following location: /opt/cyops/configs/rabbitmq/ssl/cyopsca/cacert.pem.
      Important: If in the future, your secure message exchange certificate expires, and you need to deploy a new certificate, then the new certificate must be copied back to the master node as well as the tenant's router entry.
    8. (Optional) If you have enabled the mTLS, i.e., you require that clients that want to connect to secure message exchange must present the client certificate to the secure message exchange for verification, then you must also provide a pair of exchange event listener client certificates and exchange event listener client key, as follows:
      1. In the Exchange Event Listener Client Cert field, copy-paste the client certificate text or you can also upload the client certificate file.
      2. In the Exchange Event Listener Client Key field, copy-paste the client key text or you can also upload the client key file.
    9. To save the configuration for the secure message exchange on the FortiSOAR node, click Create.
Note

After you have updated your secure message exchange configuration, the updated configurations might take some time to get reflected.

Adding a FSR agent

To add a FSR agent, 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. To add FSR agents, in the Agent Configurations section, click Agents in the left menu and click Add.
    To edit the configuration of an existing FSR agent, click the FSR agent whose configuration you want to update, which opens the FSR agent record in the detail view. Update the configuration parameters as required.
    If you no longer require an existing FSR agent, you can deactivate or deboard an FSR agent. To deactivate an agent, clear the Enabled checkbox in the FSR agent record.
    Deboarding a FSR agent is an irreversible operation which also deletes all data related to that FSR agent from the FortiSOAR node. For more information, see Deboarding FSR Agents.
  3. On the Agent page, click Add to open the Add New Agent dialog and configure the following parameters for the FSR agent:
    1. In the Name field, enter the name of the FSR agent.
    2. From the Secure Message Exchange drop-down list, choose the secure message exchange that you have configured as the secure channel using which you can relay information to your FSR agent.
    3. (Optional) In the Description field, enter the description of the FSR agent.
    4. If you have selected Certificate Auth from the Auth Type drop-down list, then in the Client Certificate field, copy-paste the client certificate text of the Certificate Authority (CA) that has signed the secure message exchange certificate in the pem format. You can also upload the client certificate file.
      If you want to enforce client certificate verification with Basic Auth then also you must provide client certificate in this field, so that the secure message exchange will verify the certificate before allowing connection to any client.
      Note: If you are using CA signed certificates, you must add these certificates to the truststore. For more information, see the FortiSOAR Admin CLI chapter in the "Administration Guide."
    5. Similarly, in the Client Key field, copy-paste the client key text or you can also upload the client key file.
    6. From the Auth Type drop-down list, select the type of authentication you want to enforce for agents or clients to connect to the secure message exchange.
    7. From the Owners drop-down list, select the teams that you want to add as owners of the FSR agent and click Link Team.
      If you do not select any team, then the teams that the user who adds the FSR agent belongs to will be associated as owners of the agent. Teams help in governing RBAC for the FSR agent. While running connector actions using FSR agents, users will only see FSR agents that are associated with their teams.
    8. To complete adding the FSR agent, click Create.

Once you have completed adding the FSR agent, you will see the status for the FSR agent. Following is the list of statuses that can be displayed:

  • Configuration In Progress: Process of configuring the FSR agent has begun.
  • Awaiting Remote Node Connection: Connection between the FortiSOAR node and secure message exchange is established and awaiting the connection to the FSR agent.
  • Remote Note Connected: FSR Agent has been connected to the FortiSOAR node using secure message exchange.
  • Configuration Failed: FSR Agent failed to be added on the secure message exchange.
  • Message Exchange Unreachable: Secure message exchange is unreachable.
  • Remote Node Unreachable: FSR Agent is unreachable from the FortiSOAR node.

If the connection between the FortiSOAR node and secure message exchange is established, then the Status column displays "Awaiting Remote Node Connection" along a Download Installer link. Now, you are required to download the FSR agent installer and install the FSR agent as described in the following section.

Added the agent - Download installer link

In the Agent Actions column, you will see either the Export Config link or the Download Installer link. The Download Installer link represents a "FSR Agent" and you can use this link to install the agent at a specified endpoint. The Export Config link represents a "FSR Node", i.e., in this case the agent represents a dedicated tenant and you can use this link to export the configuration of the dedicated tenant.

If the Status column displays statuses like "Message Exchange Unreachable" or "Remote Node Unreachable", the Agent Actions column will also display a Retry link that allows you to again perform the operation.

From FortiSOAR version 6.4.4 onwards, you might also see a Warning symbol in the Agents Action column as shown in the following image:

Agents Action column - Warning symbol

The Warning symbol indicates that the master cannot remotely execute or manage connector actions on the FSR agent. Prior to version 6.4.4., the FortiSOAR UI did not provide any indication of remote connector management, and if remote connector management was disabled at the FSR agent, then the master was not notified. Due to this if the master triggers any remote request, then that would get ignored by the FSR agent since the remote operation had been disallowed. Therefore, in version 6.4.4, the Warning icon is introduced to indicate when remote connector management is disabled.

To enable or disable remote connector management on the FSR agent, you must have a minimum of Upgrade permission on the Agent module, and to disallow the master from remotely executing connector actions on an FSR agent, ensure that the FSR agent's version must be 6.4.4 and later.

Then, ssh to the FSR agent's VM and edit the /opt/cyops-integrations/integrations/configs/config.ini file and set the value of the ENABLE_REMOTE_CONNECTOR_OPERATION parameter:

  • To enable remote connector management, set the ENABLE_REMOTE_CONNECTOR_OPERATION parameter to true.
  • To disable remote connector management, set the ENABLE_REMOTE_CONNECTOR_OPERATION parameter to false.

Once you have completed editing the config.ini file and setting the value of the ENABLE_REMOTE_CONNECTOR_OPERATION parameter, restart the cyops-integrations-agent service. Restarting the cyops-integrations-agent service notifies these changes to the master node.

From version 7.0.2 onwards, the agent grid will also contain an Auth Type column which displays whether the agent will use Basic Auth or Certificate Auth to connect to the secure message exchange. It also contains a Certificate Expiry column, which displays when the client certificate will expire in case of Certificate Authentication or Basic Authentication with Peer Verification. In the case of Basic Auth, if you provide certificates while adding agents, then the certificate expiry will be displayed; however, if you do not provide any certificates while adding agents, then a blank will be displayed in the Certificate Expiry column shown in the following image:

Agent Grid - Authenticatoion Details

Note

If you have enabled mTLS on secure message exchange, and you have added the secure message exchange client certificate and key after the FSR agent is added or if you have updated the secure message exchange client certificate and key after they have expired, then you require to first disable and again enable the agent to re-trigger the event listener and update agent status correctly.

Installing a FSR agent

Before you install a FSR agent, ensure that you meet all the prerequisites to installing an FSR agent. For more information, see Prerequisites for installing a FSR agent.

To install a FSR agent, do the following:

  1. Click the Download installer link on the Agents page.
  2. On the Prepare and Download Agent Installer dialog, from the Include Specified Connectors to install on Agent drop-down list, choose which connectors you want to include while installing the FSR agent. You can choose from the following options: Do not install connectors by default, Custom, All connectors installed on Master, or Include pre-existing connectors on agent.
    FSR Agents use connectors to remotely run actions on a remote network. If you select Do not install connectors by default, then connectors are not installed on the FSR agent, except for the "Utilities" connector that is installed, by default, on the FSR agent.
    If you select Custom, then from the Select Connectors drop-down list you have to select the connectors that you want to install on the FSR agent. Note that only connectors that are installed on FortiSOAR (master) node can be installed on the agent. If you select All connectors installed on Master, then all the connectors that are installed on FortiSOAR are installed on the FSR agent.
    If you had an FSR agent system on which you had configured some connectors, which you required to re-provision, if for example, there were some issues with the FSR agent's system, then you can download the FSR agent installer again, and select the Include pre-existing connectors on agent option. Selecting the Include pre-existing connectors on agent bundles up the connectors and their configurations of those connectors that were previously installed and configured on the FSR agent.
  3. Click Download Installer.

Once you click Download Installer, the installer file named as <agent-name>-install.bin is downloaded on your VM. Copy-paste this installer to the FSR agent VM and install the FSR agent.

The installer installs the following for the FSR agent:

  • PostgreSQL database.
  • cyops-integrations-agent

After the installation is complete, you should check the status of the cyops-integrations-agent service. Also, note that the password for PostgreSQL is the ID of the FSR Agent.

Once you have completed installing the FSR agent, you can begin to run connector actions on FSR agents, install and configure custom connectors, and perform other administrative functions. For information on all these functions, upgrading the FSR agent, see the Segmented Network Support chapter in the "Administration Guide."

Deboarding FSR Agents

To deboard existing FSR agents, you require to have Read and Delete permissions on the Agents module. Deboarding agents not only deletes the FSR agent, but also removes the list of connectors installed and all the configurations of the connectors that have been installed on the specific FSR agent from the FortiSOAR node. Once you delete a FSR agent, you cannot retrieve any information related to that FSR agent, therefore you must be careful while performing this operation.

To deboard a FSR agent, log on to FortiSOAR as an administrator and click the Settings icon to open the System page. Click Agents in the left menu and on the Agents page, click Delete. FortiSOAR will display a warning dialog, click Confirm on the warning dialog to deboard the FSR agent.

Moving a FSR agent to a new secure message exchange

If you have added a new secure message in your environment, and you want to move your FSR agent to the new secure message exchange, do the following on the FortiSOAR system:

  1. Add the new secure message on your FortiSOAR system. For more information, see the Adding a Secure Message Exchange section.
  2. Log on to your FortiSOAR node, master node in case of a distributed multi-tenant configuration, as an administrator and click the Settings icon to open the System page.
  3. In the Agent Configurations section, click Agents in the left menu.
  4. Click to open the FSR agent record that you want to move to the new secure message exchange.
  5. In the FSR agent record, from the Secure Message Exchange drop-down list, select the secure message exchange on which you want to move the FSR agent.
  6. Restart the cyops-postman, uwsgi, and cyops-integrations-agent services on the master node, using the following command:
    systemctl restart cyops-postman uwsgi cyops-integrations-agent
    After you have completed updating the router information and restarting the services, you must download the FSR agent installer again and reinstall the FSR agent on the FSR agent VM.

Deploying FortiSOAR

This chapter covers the process of deploying FortiSOAR, and the initial configuration required for FortiSOAR. You can perform the initial configuration for FortiSOAR using the FortiSOAR Configuration Wizard.

The following image displays the high-level tasks for deploying FortiSOAR:

High-level process for deploying FortiSOAR

You can also install FortiSOAR 7.0.2 using the FortiSOAR installer (.bin file). For more information, see Installing FortiSOAR 7.0.2 using the FortiSOAR installer.

You can also set up a local offline repository and deploying FortiSOAR using the offline repository. For more information, see the Setting up a local offline repository and deploying using the offline repository chapter.

Planning

Recommended Resource Requirements

Note

The maximum hard drive or physical volume size for FortiSOAR must be limited to 2 TB.

Virtual Machine (VM)

Minimum Specifications
  • 8 available vCPUs
  • 20 GB available RAM
  • 500 GB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC
Recommended Specifications
  • 8 available vCPUs
  • 32 GB available RAM
  • 1 TB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC
Note

In case of multi-tenant configurations, contact FortiSOAR Support for sizing requirements.

Supported Hypervisors

  • AWS AMI
  • VMware ESXi versions 5.5, 6.0, and 6.5
  • Redhat KVM

VM Inbound Networking

Enable the following ports for the VM within your VM network:

  • 22 Management (ssh)
  • 443 User Interface (https)

VM Outbound Networking

For FortiSOAR to correctly interact with your network, you must provide access between the FortiSOAR VM and the third-party products and services configured within your network.

To accomplish this, enable the following ports for SSH, SMTP, and HTTPs access:

  • 22 Management (ssh)
  • 25 Email SMTP relay server. This port can be different based on your environment.
  • 443 User Interface (https)
Note

Depending on the type of connectors used in Playbooks, you might require to open other ports or services.

Credentials

Credentials to access SSH management and the FortiSOAR User Interface are:

Username: csadmin

Password: changeme

From FortiSOAR 6.0.0 onwards, the UI password of the 'csadmin' user for AWS is set to the "instance_id" of your instance.
To know the instance ID of your FortiSOAR AWS instance, you can SSH and run the cloud-init query instance_id command.

Tooltip

From version 7.0.2 onwards, first FortiSOAR SSH login, password change is mandated for the 'csadmin' users, thereby enhancing the security of your csadmin account and preventing unauthorized parties from accessing the FortiSOAR administration account.

Requirements

It is highly recommended that Internet access is provided for a FortiSOAR upgrade, license deployment, and also for installing new out-of-the-box connectors.

Add the following URLs in the allowlist of your Firewall or Proxy servers:

For upgrading FortiSOAR, installing connectors, and accessing the widget library: https://update.cybersponse.com

For Connector Dependencies: https://pypi.python.org

For synchronization of FortiSOAR license details: https://globalupdate.fortinet.net

Port Requirements

The following ports require to be locally open for various services, i.e., all these ports do not require to be open on the firewall for external access, they are used only inter-service communication within the appliance:

Service Port Number
elasticsearch (Elasticsearch service uses this port for REST communication).
Port needs to be opened in case of high availability (HA) environments.
9200
elasticsearch (Elasticsearch service uses this port for communication between nodes) 9300
rabbitmqserver 5672
cyops routing agent through nginx postman 7575
cyops workflow (celery) through nginx /sealab 8888
postgresql
Port needs to be opened in case of HA environments.
5432
cyops auth server through nginx 8443
cyops integration (uwsgi) through nginx 9595
cyops-tomcat (hosts cyops-gateway, cyops-notifier) 8080
MQ TCP traffic
Port needs to be opened in case of HA environments.
5671
cyops-api (crud-hub) [php-fpm is used to host] 443
rabbitmq service 25672, 4389

If you need to access ssh or start a terminal session from outside your network to troubleshoot or manage services or databases, then port "22/tcp open ssh" should be opened on the firewall for external access. Port 443/tcp open https must always be opened on the firewall for external access.

Importing the FortiSOAR Virtual Appliance

Use a vSphere Client or a viclient to import the Virtual Appliance into the ESX/ESXi server. See the VMware documentation for steps on how to import a Virtual Appliance.

Note

After you import the FortiSOAR Virtual Appliance and the FortiSOAR system boots up, the IP address of the system is displayed on the command prompt. You can share this IP address with users who require to configure FortiSOAR using the FortiSOAR Configuration Wizard.

Downloading the FortiSOAR Virtual Appliance from the Support Portal

You can download the required FortiSOAR Virtual Appliance image from the support portal, which contains images for AWS, KVM-Supported QCOW2 and VMware. You will need these images to be downloaded before you can begin deploying FortiSOAR using vSphere or vCenter, or KVM. In case of AWS, you can directly lunch an instance using the images present on the AWS Marketplace images.

To download the FortiSOAR Virtual Appliance do the following:

  1. Log onto support.fortinet.com.
  2. Click Support > Firmware Download.
    Download the firmware for FSR virtual appliance
  3. On the Fortinet Firmware Images And Software Releases page from the Select Product drop-down list select FortiSOAR.
    Fortinet Firmware Images And Software Releases page
    The page displays various released versions of FortiSOAR , and contains two tabs: Release Notes and Downloads.
    Fortinet Firmware Images And Software Releases page: Release Notes and Downloads tabs
    To download the Release Notes for a particular version, click the version and build number link, which opens the FortiSOAR Document Library, from where you can download the release notes for that particular version.
  4. To download a firmware image do the following:
    1. Click the Download tab
    2. Navigate through the directory structure to open the page containing the required images. For example, to download a firmware image for version 7.0.0, click v7.0.0 > 7.0 > 7.0.0 and locate the firmware image you require.
      Download FSR Firmware using HTTPS link
    3. Download the firmware image by clicking the HTTPS link.
      An HTTPS connection is used to download the firmware image.
    4. Click the Checksum link for the image that you downloaded.
      The image file name and checksum code are displayed in the Get Checksum Code dialog box.
    5. Confirm that the checksum of the downloaded image file matches the checksum provided on the download site.

Deploying the FortiSOAR Virtual Appliance

Download the required FortiSOAR Virtual Appliance image from the Support Portal, which contains images for AWS, KVM-Supported QCOW2 and VMware. You will need these images to be downloaded before you can begin deploying FortiSOAR using vSphere or vCenter, or KVM. In case of AWS, you can directly lunch an instance using the images present on the AWS Marketplace images. For information on how to download images from the support portal, see the Downloading the FortiSOAR Virtual Appliance from the Support Portal section. Also, ensure that your VM is configured as per the specifications outlined in the Planning section.

Deploying the FortiSOAR Virtual Appliance using vSphere or vCenter

Download the VMware enterprise and secure message exchange images as outlined in the Downloading the FortiSOAR Virtual Appliance from the Support Portal section. Then once you have ensured that you have met all the specifications, deploy the FortiSOAR Virtual Appliance using vSphere or vCenter. See the VMware documentation for steps on how to deploy a Virtual Appliance.

Deploying the FortiSOAR Virtual Appliance using AWS

Once you have ensured that you have met all the specifications, perform the following steps to deploy the FortiSOAR Virtual Appliance on Amazon Web Services (AWS):

  1. Log into your AWS account and from the Amazon EC2 console dashboard, choose Launch Instance, to launch the FortiSOAR instance.
  2. On the Choose an Amazon Machine Image (AMI) page, enter fortinet-fortisoar in the search bar to find the latest version of the FortiSOAR Enterprise and SME (secure message exchange) AMIs in the AWS Marketplace. Choose the AMI and start configuring the instance. Following is a reference screenshot:

    AWS Marketplace - FortiSOAR AMIs

After you complete deploying your FortiSOAR and you connect the first time to your FortiSOAR VM, the EULA agreement page is displayed. You must accept the EULA to continue with your FortiSOAR configuration. If you do not accept the EULA, then the OS will halt, and you have to restart your FortiSOAR VM (power off-power on) and reconnect to the FortiSOAR VM and accept EULA to continue with your FortiSOAR configuration.

Deploying FortiSOAR using KVM

Once you have ensured that you have met all the specifications, perform the following steps to deploy the FortiSOAR QCOW2 on KVM:

  1. Download the KVM-Supported QCOW2 images as outlined in the Downloading the FortiSOAR Virtual Appliance from the Support Portal section.
  2. Copy the FortiSOAR QCOW2 image to the VM Image Datastore.
  3. Open the Virtual Machine Manager application for KVM VM deployment.
     Virtual Machine Manager application
  4. Click File > New Virtual Machine.
    Creating a new VM
  5. On the New VM dialog, select the Import existing disk image option and click Forward.
    New VM creation - Choosing to install the OS
  6. Click Browse and select the FortiSOAR image from the Image Datastore, select the OS type as Linux and Version as CentOS 7, and click Forward.
    New VM creation - Entering the storage path
    This displays the Storage Volume screen, where you can choose the storage volume, or click Cancel to keep as default:
    New VM creation - Choosing the storage volume
  7. Enter 32768 (i.e. 32768 MB=32 GB) in the Memory (RAM) field and 8 in the CPUs field and click Forward.
    New VM creation - Specifying Memory and CPU values
  8. Enter the name that you want to specify for the new virtual machine in the Name field, select the correct network adapter for this new virtual machine from the Network Selection field, and click Finish to complete the deployment.
    Note: The network adapter type would change depending upon your KVM environment. As an example, in the following image the "Bridge adapter.." is selected. You must select the proper network adapter as per your environment requirements.
    New VM creation - Specifying Name and Network Adapter
  9. Post VM deployment, the VM boots up and brings up the login console as shown in the following image:
    New VM - Login Console

CLI Deployment

If you want to deploy the FortiSOAR QCOW2 image (of version 6.4.1 for example) on KVM using the CLI, then use the following command:
virt-install --memory 32768 --vcpus 8 --import --os-type=linux --os-variant centos7.0 --name <virtual machine name> --disk </path/to/qcow2/image/.qcow2> --network <network type=kvm network name>

Following is an example using the above CLI command:
virt-install --memory 32768 --vcpus 8 --import --os-type=linux --os-variant centos7.0 --name FortiSOAR-Enterprise-6.4.1 --disk /var/lib/libvirt/fortisoar/fortisoar-kvm-enterprise-6.4.1-2133.qcow2 --network bridge=virbr0

Post deployment, perform the initial configuration steps using the FortiSOAR Configuration Wizard.

Installing FortiSOAR 7.0.2 using the FortiSOAR installer

This section describes the steps that you require to follow to install FortiSOAR 7.0.2 on a plain CentOS system that has minimal skew selected while installing CentOS.

Prerequisites

Before you begin this procedure, ensure that you can access update.cybersponse.com. In case you have configured proxies, then ensure that you have added your proxy settings in the following files:

  • /etc/environment
  • /etc/yum.conf
  • /etc/pip.conf

Following is an example of adding proxy settings to the above-mentioned files:

  • /etc/environment
    product_yum_server=update.cybersponse.com
    http_proxy='http://username:password@10.1.1.0:8080'
    no_proxy='127.0.0.1','localhost'
    https_proxy='http://username:password@10.1.1.0:8080'
  • /etc/yum.conf
    proxy=http://10.1.1.0:8080
    proxy_username=username
    proxy_password=password
  • Create the /etc/pip.conf file as follows:
    [global]
    extra-index-url=
    https://update.cybersponse.com/prod/connectors/deps/simple/
    proxy='http://username:password@10.1.1.0:8080'

Procedure

The following procedure describes the steps that you require to run for installing FortiSOAR 7.0.2 Enterprise Edition and Secure Message Exchange:

  1. Provision a CentOS 7 (minimal) VM [recommended version 7.7.1908 (Core)], with the wget package.
  2. Ensure your VM has disk space of 500 GB. If you have a large volume of data being ingested daily, it is recommended to have a disk space of 1 TB. It is recommended to have a thin provisioned disk.
    You can add three more disks to your Virtual Machine (VM) and create separate Logical Volume Management (LVM) partitioning for PostgreSQL, Elasticsearch and FortiSOAR RPM data. For more information about multiple disk support, see the Multidisk Support article present in the Fortinet Knowledge Base.
    Note: The database disk requires most volume is required for the database disk. So if you are provisioning the volume with multiple disks, the size of the data disk is the most important and should be sufficiently large.
    Refer to the table that is present at the end of this procedure for the minimum and recommended disk sizes.
  3. To ensure that your ssh session does not timeout execute the screen command.
    For more information on how to handle session timeouts, see the Handle session timeouts while running the FortiSOAR upgrade article present in the Fortinet Knowledge Base.
  4. To download the installer for FortiSOAR 7.0.2:
    # wget https://update.cybersponse.com/7.0.2/install-fortisoar-7.0.2.bin
  5. To install FortiSOAR 7.0.2 run the following command as a root user:
    # sh install-fortisoar-7.0.2.bin
    OR
    chmod +x install-fortisoar-7.0.2.bin
    ./install-fortisoar-7.0.2.bin
    The installer will display the following installation options:
    Enterprise
    OR
    Secure Message Exchange
    Choose Enterprise in this case and complete the installation.
    Note: If you are installing FortiSOAR in a closed or air-gapped environment, you will see a message such as "The system does not have connectivity to https://globalupdate.fortinet.net. Connectivity....", ignore these warning messages and proceed with the installation as there is no requirement to check the check connectivity to globalupdate.fortinet.com in case of an air-gapped environment. For information on licensing in the case of closed environments, see the FortiSOAR licensing using FortiManager topic in the Licensing FortiSOAR chapter.
  6. Once the installation is complete, exit the terminal session and log back in using the following credentials:
    Username: csadmin
    Password: changeme
  7. Once you have logged into FortiSOAR, you will be asked to accept the EULA. You must accept the EULA before you can proceed to the FortiSOAR Configuration Wizard.
  8. Retrieve your FortiSOAR Device UUID, which is created automatically by the FortiSOAR installation. This Device UUID is used to identify each unique FortiSOAR environment. A root user can directly run the following command to retrieve the Device UUID:
    csadm license --get-device-uuid
    Use this Device UUID to get your FortiSOAR license using the process detailed in the Licensing FortiSOAR chapter.
  9. Before you deploy your FortiSOAR license, ensure that you can connect to https://globalupdate.fortinet.net, else the license deployment will fail. Connectivity to this address is required for fetching the license entitlements and product functioning post-upgrade.
    You can deploy your FortiSOAR license using the FortiSOAR UI or using the FortiSOAR Admin CLI. For more information on deploying the FortiSOAR license, see the Licensing FortiSOAR chapter.
  10. Once your system is licensed, you can log on to the FortiSOAR UI using the default credentials:
    Username: csadmin
    Password: changeme

Following is a table that contains the minimum and recommended disk sizes:

Mount Point Recommended Size Minimum Size
/ 6 GB -
/boot 1.5 GB -

/tmp

2 GB

1 GB

/opt

9.5 GB

-

/var

4 GB

-

/var/lib/pgsql

500 GB

20 GB

/var/lib/elasticsearch

150 GB

-

/var/lib/rabbitmq

11.5 GB

-

/var/log

5 GB

2 GB

/var/log/audit

1 GB

/var/log/cyops/coredump

49 GB

-

/home

10 GB

-

Installing the secure message exchange

A secure message exchange establishes a secure channel that is used to relay information to the agents or tenant nodes. To create a dedicated secure channel, you are required to add the reference of the installed and configured secure message exchange, when you add agent or tenant nodes to your environment. A default "self" secure message exchange configuration is available and can be enabled. However, for a production setup, we recommend that you configure a separate secure message exchange. For more information, see the Enabling the secure message exchange and Adding a secure message exchange sections.

Steps for installing the secure message exchange are as follows:

  1. Provision a CentOS 7 (minimal) VM [recommended version 7.7.1908 (Core)], with the wget package.
  2. Ensure your VM has disk space of minimum 50 GB, recommended is 100 GB. It is recommended to have a thin provisioned disk.
  3. To ensure that your ssh session does not timeout execute the screen command.
    For more information on how to handle session timeouts, see the Handle session timeouts while running the FortiSOAR upgrade article present in the Fortinet Knowledge Base.
  4. To download the installer for FortiSOAR 7.0.2 secure message exchange:
    wget https://update.cybersponse.com/7.0.2/install-fortisoar-7.0.2.bin
  5. To install FortiSOAR 7.0.2 secure message exchange run the following command as a root user:
    # sh install-fortisoar-7.0.2.bin
    OR
    chmod +x install-fortisoar-7.0.2.bin
    ./install-fortisoar-7.0.2.bin
    The installer will display the following installation options:
    Enterprise
    OR
    Secure Message Exchange
    Choose Secure Message Exchange in this case and complete the installation.

Once you have installed the secure message exchange, a FortiSOAR Secure Message Exchange Configuration Wizard similar to the FortiSOAR Configuration Wizard is automatically run on the first ssh login by the csadmin user and it performs the initial configuration steps that are required for the Secure Message Exchange. In the FortiSOAR Secure Message Exchange Configuration Wizard you require to provide certain inputs such as the hostname of the Secure Message Exchange VM, port numbers to be used for the API and TCP connections to the Secure Message Exchange, etc., which are required to complete the initial configuration steps for the Secure Message Exchange.

Installing FortiSOAR on RHEL using the FortiSOAR installer

This section describes the steps that you require to follow to install FortiSOAR on a Red Hat Enterprise Linux (RHEL) system.

  1. Register your RHEL instance:
    subscription-manager register --username <username> --password <password>--auto-attach --force
  2. Enable the optional repositories:
    subscription-manager repos --enable=rhel-7-server-optional-rpms
  3. Install the required packages:
    yum install policycoreutils-python gcc java-11-openjdk yum-utils -y && yum install wget screen vim -y
  4. Follow the steps outlined in the Installing FortiSOAR7.0.2 using the FortiSOAR installer topic to install FortiSOAR on your RHEL instance.

FortiSOAR Configuration Wizard

Interactive VM configuration

A configuration wizard runs automatically on the first ssh login by the csadmin user and performs the initial configuration steps that are required for FortiSOAR. The wizard guides you through the configuration process with appropriate instructions so that you can efficiently perform the initial configuration required for FortiSOAR. To begin running the configuration wizard, you must accept the Fortinet End User License Agreement.

The wizard performs the following configuration steps:

  1. Change hostname: (Optional) You can change the hostname for your FortiSOAR VM. Ensure that the hostname that you provide is resolvable. If the hostname gets resolved by a DNS server, ensure that you provide only the node name and not the complete FQDN. The wizard checks if the hostname is valid or not; and throws an error in case of an invalid hostname. FortiSOAR optionally also asks for additional DNS servers.
    In an environment where DHCP is not enabled, i.e., in case of a static IP environment, the configuration wizard fails since it cannot get the network. Therefore, from version 6.4.1 onwards, the configuration wizard detects whether the FortiSOAR VM has an IP; if the wizard cannot detect an IP, a Static IP page is displayed where you can add the Static IP, Gateway, Netmask, DNS1 and DNS2, ensuring that the configuration wizard completes without failure. This also provides users with the flexibility of changing their environment from DHCP to Static without worrying that the configuration wizard will fail since it cannot get the network.
    If the configuration wizard detects an IP, i.e. in case of a DHCP enabled system, the DNS servers input page is displayed.
    Also, if you change the hostname, the configuration wizard automatically updates the HOSTNAME variable in /etc/profile.
  2. Configure Proxy: (Optional) You can configure an https/http proxy server to serve all https/http requests from FortiSOAR. To configure an https or http proxy, you must specify the username and password, and the hostname and the port number of the HTTPS or HTTP proxy server. For example to configure an HTTPS proxy, enter the proxy details in the following format: https://user:password@[ip/fqdn]:port. You can also configure a comma-separated list of hostnames that do not require to be routed through a proxy server. For example, [ip1/fqdn1], [ip2/fqdn2]
  3. Update network configuration: This is an automatic process.
  4. Set up intra-service authentication: This is an automatic process to generate new appliance keys unique to your instance for communication to the FortiSOAR services.
  5. Generate certificates: This is an automatic process; you do not require to provide any inputs.
  6. Generate Device UUID: This is an automatic process; you do not require to provide any inputs. The wizard also saves the Device UUID in the /home/csadmin/device_uuid file.
    This Device UUID is required for when you are generating your license for FortiSOAR. For more information, see the Licensing FortiSOAR chapter.
    Important: You get logged out after the FortiSOAR VM is configured, so that the changes can take effect. Therefore, you require to ssh again to the FortiSOAR VM.
  7. Reset database passwords: This is an automatic process to reset database password to a new password unique to your instance.
  8. Restart services: This is an automatic process to reset all FortiSOAR services.
  9. Configure default HA cluster: This is an automatic process that creates the default single-node HA cluster. This FortiSOAR server is created as a primary-active node.
  10. Install python libraries: This is an automatic process to install some python libraries required by FortiSOAR.

After the FortiSOAR Configuration Wizard is run, it displays the following:

  • Device UUID
  • Path where the Device UUID is saved
  • Path of the Configuration Wizard log
Note

If your FortiSOAR Configuration Wizard displays errors when it is being run, then you can troubleshoot the FortiSOAR Configuration Wizard errors by checking its logs, which are located at /var/log/cyops/install/config_vm_<timestamp>. For example, /var/log/cyops/install/config-vm-09_Nov_2018_05h_37m_36s.log.

Tooltip

If you want to replace the Self-Signed Certificates with your own signed certificates, see the Updating the SSL certificates topic.

Non-interactive VM configuration

The FortiSOAR Configuration Wizard also has a non-interactive mode that automatically performs the initial configuration steps (as mentioned in the Interactive VM Configuration section) that are required for FortiSOAR, without any inputs from the user. The configuration in this case is done by using the default inputs from the configuration file that is shipped along with the FortiSOAR appliance. Non-interactive VM configuration is useful when users are expecting a ready-to-use appliance.

The default configuration files are:

  • For the Enterprise edition: /opt/cyops/configs/scripts/config-vm-enterprise-default.conf
    and

  • For the Secure Message Exchange: /opt/cyops/configs/scripts/config-vm-sme-default.conf

You can customize the non-interactive VM configuration by providing additional custom configuration files. Values provided in the custom configuration files overrides the ones mentioned in the default configuration file.

A configuration file has the following format:

key=value

Following is a list of supported key names with their sample values:

  • hostname=sample_hostname

  • dns=sample_dns_name

  • proxy_https=https://userid:password@www.sample-https.com:9999

  • proxy_http=http://userid:password@www.sample-http.com:9999

  • proxy_noproxy=127.0.0.1,sample-no-proxy

  • static_ip=192.168.51.181

  • gateway=192.168.51.1

  • netmask=255.255.255.0

  • dns1=192.168.60.100

  • dns2=8.8.8.8

  • message_queue_user_id=admin

  • message_queue_password=changeme

  • message_queue_api_port=15671

  • message_queue_tcp_port=5671

Guidelines to creating custom configuration files:

  • Empty keys are ignored. For example: hostname=.

  • The userid and password parameters are optional in the proxy_httpand proxy_https keys. The format of the URL is: proxy_https=https://www.sample-https.com:9999
    Also note that proxy_http, proxy_https, and proxy_noproxy are applicable to only the 'Enterprise' edition

  • The static_ip, gateway, netmask, dns1, and dns2 keys are considered only in case of a 'non-dhcp environment'.
    The static_ip, gateway, netmask, and dns1 keys are mandatory. The dns2 key is optional.

  • The message_queue_user_id, message_queue_password, message_queue_api_port, and message_queue_tcp_port keys are applicable to only the 'Secure Message Exchange' edition

  • Keys that are not applicable to a particular edition are ignored. For example, if you add the proxy_http to the 'Secure Message Exchange' edition, the proxy_http will be ignored.

Once your system is appropriately deployed, it is recommended that you install the Content Pack (FSR-IR-CONTENT-PACK). The Content Pack enables users to experience the power of FortiSOAR incident response, both automated and manual, without having to configure FortiSOAR to ingest any data. With out-of-box (OOB) demo records and their corresponding playbooks that demonstrate various use cases along with best practices to combat various types of incidents. From version 7.0.0 onwards, you can install the content before deploying your FortiSOAR license. For more information on the Content Pack, see the Incident Response Content Pack article present in FUSE (Fortinet User Community).

Pointing the ntpd service to a valid ntp server

If the time on the FortiSOAR server is not correct, you might see issues such as ingestion workflows not pulling the latest data from an external source. It is highly recommended to keep the time in sync with an NTP server. Therefore, if you require to change the system time on your FortiSOAR instance, then perform this step immediately after running the FortiSOAR Configuration Wizard.

The ntpd service runs on your FortiSOAR instance, and it requires to be pointed to a valid ntp server. If the /etc/ntp.conf file contains entries to ntp server(s) that are not valid; then you might face Invalid System Time issues where you might not be able to log on to your FortiSOAR instance. Edit the /etc/ntp.conf file to add details of a valid ntp server(s). For a list of common NTP servers, go to https://www.ntppool.org/en/.

In case your FortiSOAR VM does not have access to the internet, then you must edit the /etc/ntp.conf to add details of a valid ntp server within your datacenter.

Editing the VM configuration

It is not necessary to perform the following steps, but they can quickly assist you to get access to the FortiSOAR VM:

  1. Setting a static IP
  2. Determining your DHCP IP Address

Setting a static IP

  1. On the ESX console for your FortiSOAR VM, login to the VM as the csadmin user.
  2. Type sudo –i in the terminal and press Enter to become a root user.
  3. Once you are logged in to the terminal, type nmtui and press Enter.
    Entering nmtui on the terminal
  4. On the first screen, select the Edit a connection option and press Enter.
    Edit a connection option
  5. On the second screen, select the connection listed under Ethernet, which is Wired connection 1 and select <Edit...>.
    Select the Ethernet connection
  6. Use the arrow keys to select <Show> that appears to the right of the IPv4 Configuration option and press Enter.
  7. Enter the required information for your network. You must enter all the information, such as IP Address, Gateway, DNS servers address, on this screen:
    IPv4 Configuration
  8. (Optional) If you want to configure IPv6, repeat steps 5 and 6 and then enter the required information, such as IPv6 Address, for your network.
  9. Ensure that you have selected the Automatically connect and Available to all users options.
    Automatically connect and Available to all users options
  10. Select <OK> and press Enter.
  11. Select <Back> and press Enter.
  12. Select <OK> and press Enter.
  13. Restart the network service using the systemctl restart network command.

Once the network service restarts, you can use the assigned static IP.

Determining your DHCP IP address

  1. On the ESX console for your FortiSOAR VM, login to the FortiSOAR VM as the root user.
  2. Type ifconfig | more in the terminal and press Enter.
    Your IP address is listed in the eth** section, next to inet, as displayed in the following image:
    DHCP IP address'
Note

Once you have completed configuring the hostname and IP address ensure that the default inbound ports mentioned in the 'VM Inbound Networking' section are open and accessible.

Now you must follow the licensing process required for FortiSOAR and then you can use this IP address to log on to the FortiSOAR UI and begin the configuring the system. See the Licensing FortiSOAR chapter for more information.

Deploying FSR Agents

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 FSRAgent 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 FSRagent 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.

Note

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

From version 7.0.2 onwards, you can use client certificate based authentication to create connections between the FSR agent and secure message exchange. Prior to the 7.0.2 release, basic authentication using username and password was used to create connections between FSR agent and secure message exchange. Going forward, you can configure the following types of authentications to connect FSRagent and secure message exchange:

  • Basic Authentication: Uses username and password to create connections between FSR agent and secure message exchange.
  • Basic Authentication with Peer Verification: Uses username and password to create connections between FSR agent and secure message exchange, and also performs 'Certificate Verification'. This process will verify that the clients which are attempting to connect can be trusted by presenting a certificate that is signed by a CA and trusted by the server; thereby ensuring that only trusted clients can connect to the secure message exchange.
  • Client Certificate Authentication: Presents a certificate to the server which is signed by a trusted CA. It is recommended that you create the certificate with the common name as the name of your agent or tenant. This provides enhanced security as this gives the facility to connect only to trusted clients.

To enable client certificate authentication, you can specify the authentication type as 'Certificate Auth' while adding a FSR agent.

To enforce client certificate verification, you must provide a pair of exchange event listener client certificates and exchange event listener client key when you are adding a secure message exchange. Client verification ensures that whenever any client wants to connect to secure message exchange that client must present the client certificate to the secure message exchange for verification. You must also provide the pair of exchange event listener client certificates and exchange event listener client key, if you have enabled mutual TLS (mTLS). Use the csadm mq mtls command to enable or disable mTLS. For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."

Architecture

Architecture of Segmented Network Support

Recommended Resource Requirements for Virtual Machines (VM)

Recommended specifications for Secure Message Exchange

  • 8 available vCPUs
  • 16 GB available RAM
  • 100 GB available disk space: Recommended to have high-performance storage, preferably SSDs.
  • 1 vNIC

Recommended specifications for FSR agents

  • 4 GB available RAM
  • CentOS Linux release 7.9.2009 (kernel-3.10.0-1160.6.1.el7.x86_64) or Red Hat Enterprise Linux (RHEL) Server release 7.9 (Maipo) (Kernel - 13.10.0-1160.el7)

Prerequisites for installing a FSR agent

  • Ensure that the VM on which you want to install the FSR agent matches the recommended specifications, see Recommended specifications for FSR agents.
  • Ensure that update.cybersponse.com is reachable or resolvable from the VM on which you want to install the FSR agent.
  • Ensure that the secure message exchange that you have specified when you have added the FSR agent is reachable or resolvable from the VM.
  • Ensure that the following packages are installed on the instance where you are going to install the FSR agent:
    • Python36-devel: The FSR agent runtime needs "python36-devel". During FSR agent installation, the installer looks for an existing installation, and in the case, it is not installed, tries to install it using yum install. If this package is not found, the FSR agent installation will fail.
    • GCC: Some connectors have a dependency on GCC. Therefore, the FSR agent installer looks for an existing installation, and tries to install it using yum install. If this package is not found, the FSR agent installation will display a "warning" and will not fail the installation. You can install GCC later on a FSR agent using the yum install gcc command, if you want to use a connector that is dependent on GCC.
      You can either keep these packages pre-installed on the FSR agent's system, or along with the default repos ensure that the following repos are enabled, so that they get installed during agent binary installation:
      For CentOS: CentOS-Base.repo
      For RHEL: rhel-7-server-optional-rpm and rhel-server-rhscl-7-rpms for RHEL
      Note: If the connector has dependency on any other package or application to work then that package or application will require to be separately installed on the FSR agent. For example, the nmap connector requires the nmap application to be installed, therefore you would require to install this application separately on the agent.

Process of setting up a FSR agent

  1. Add a secure message exchange.
    A Secure Message server is used for communication with FSR Agents or dedicated tenant nodes. You can add both externally deployed secure message exchange or the Default (Embedded) secure message exchange.
    If you want to use the local i.e., Default (Embedded) secure message exchange to connect to external FSR agents and run remote actions on various segments of your network or in case of a dedicated tenant, then you must enable the secure message exchange as described in the Enabling the secure message exchange section. In case of an external secure message exchange, then add the secure message exchange as described in the Adding a Secure Message Exchange section.
  2. Add FSR agents to your FortiSOAR instance. See the Adding a FSR agent section.
  3. Install FSR agents. See the Installing a FSR agent section.

Minimal permissions required

To configure and install FSR agents:

  • Create, Read, and Update permissions on Agents.
  • Read permissions on Application and Secure Message Exchange.
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.

Enabling the secure message exchange

A secure message exchange establishes a secure channel using which you can relay information to your FSR agent or tenant nodes. A Default (Embedded) secure message exchange configuration is available on every FortiSOAR node that can be enabled as explained in this section.

To use the Default (Embedded) secure message exchange to connect to external FSR agents, you must enable the secure message exchange using the csadm secure-message-enchange enable command. For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."

Note

For a production setup, it is recommended that you add and configure an external secure message exchange for handling scale and high availability.

Adding a Secure Message Exchange

Install a secure message exchange and then adding the reference of this secure message exchange in the tenant or FSR agent node(s) creates a dedicated secure channel of communication. You can have more than one secure message exchange in the configuration. You can distribute tenants across secure message exchanges based on the geographical locations, scale, or compliance policies of the respective customers.

To add a secure message exchange, do the following:

  1. Log on to FortiSOAR as an administrator.
    Note: Administrator role must have Create, Update, and Delete permissions on Secure Message Exchange.
  2. Click the Settings (Setting icon) icon to open the System page.
  3. On the System page, you will see the Agent Configurations section. Click the Secure Message Exchange item in the left menu, to configure the secure message exchange.
    Secure Message Exchanges Page
  4. Click Add Secure Message Exchange on the Secure Message Exchanges page.
    Important: To add a secure message exchange and configure tenants, you must have a role that has a minimum of Create and Read permissions on the Secure Message Exchange and Tenants modules. To update the details of the secure message exchange you additionally require Update permissions on the Secure Message Exchange and Tenants modules.
    To edit the configuration of an existing secure message exchange, click the secure message exchange row whose configuration you want to update. This displays the Edit Secure Message Exchange dialog. Update the configuration parameters, as required, in the dialog and click Update.
  5. In the Add New Secure Message Exchange dialog, configure the following parameters:
    1. In the Name field, enter the name of the secure message exchange that you have configured to act as a secure channel of data replication between the FortiSOAR node and tenant or FSR agent nodes.
    2. In the Address field, enter the FQHN (Fully Qualified Host Name) of the secure message exchange.
      Important: Ensure that the FQHN matches the Certificate Name (CN) or the Subject Alternative Name (SAN) provided in the SSL certificate used to configure the secure message exchange.
    3. In the API Port field, enter the RabbitMQ Management port number that you had specified while configuring the secure message exchange, and ensure that the FortiSOAR node has outbound connectivity to the secure message exchange at this port.
      By default, it is set as 15671.
    4. In the TCP Port field, enter the TCP port number that you had specified while configuring the secure message exchange, and ensure that the FortiSOAR node has outbound connectivity to the secure message exchange at this port.
      By default, it is set as 5671.
    5. In the User Name field, enter the username you will use to login to your secure message exchange as an administrator.
      By default, it is set as admin.
    6. In the Password field, enter the password you will use to login to your secure message exchange as an administrator.
    7. In the CA Certificate field, copy-paste the certificate text of the Certificate Authority (CA) that has signed the secure message exchange certificate in the pem format. You can also upload the certificate file. If it is a chain, then the complete chain must be provided.
      By default, the CA certificate for the FortiSOAR self-signed certificate is present at the following location: /opt/cyops/configs/rabbitmq/ssl/cyopsca/cacert.pem.
      Important: If in the future, your secure message exchange certificate expires, and you need to deploy a new certificate, then the new certificate must be copied back to the master node as well as the tenant's router entry.
    8. (Optional) If you have enabled the mTLS, i.e., you require that clients that want to connect to secure message exchange must present the client certificate to the secure message exchange for verification, then you must also provide a pair of exchange event listener client certificates and exchange event listener client key, as follows:
      1. In the Exchange Event Listener Client Cert field, copy-paste the client certificate text or you can also upload the client certificate file.
      2. In the Exchange Event Listener Client Key field, copy-paste the client key text or you can also upload the client key file.
    9. To save the configuration for the secure message exchange on the FortiSOAR node, click Create.
Note

After you have updated your secure message exchange configuration, the updated configurations might take some time to get reflected.

Adding a FSR agent

To add a FSR agent, 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. To add FSR agents, in the Agent Configurations section, click Agents in the left menu and click Add.
    To edit the configuration of an existing FSR agent, click the FSR agent whose configuration you want to update, which opens the FSR agent record in the detail view. Update the configuration parameters as required.
    If you no longer require an existing FSR agent, you can deactivate or deboard an FSR agent. To deactivate an agent, clear the Enabled checkbox in the FSR agent record.
    Deboarding a FSR agent is an irreversible operation which also deletes all data related to that FSR agent from the FortiSOAR node. For more information, see Deboarding FSR Agents.
  3. On the Agent page, click Add to open the Add New Agent dialog and configure the following parameters for the FSR agent:
    1. In the Name field, enter the name of the FSR agent.
    2. From the Secure Message Exchange drop-down list, choose the secure message exchange that you have configured as the secure channel using which you can relay information to your FSR agent.
    3. (Optional) In the Description field, enter the description of the FSR agent.
    4. If you have selected Certificate Auth from the Auth Type drop-down list, then in the Client Certificate field, copy-paste the client certificate text of the Certificate Authority (CA) that has signed the secure message exchange certificate in the pem format. You can also upload the client certificate file.
      If you want to enforce client certificate verification with Basic Auth then also you must provide client certificate in this field, so that the secure message exchange will verify the certificate before allowing connection to any client.
      Note: If you are using CA signed certificates, you must add these certificates to the truststore. For more information, see the FortiSOAR Admin CLI chapter in the "Administration Guide."
    5. Similarly, in the Client Key field, copy-paste the client key text or you can also upload the client key file.
    6. From the Auth Type drop-down list, select the type of authentication you want to enforce for agents or clients to connect to the secure message exchange.
    7. From the Owners drop-down list, select the teams that you want to add as owners of the FSR agent and click Link Team.
      If you do not select any team, then the teams that the user who adds the FSR agent belongs to will be associated as owners of the agent. Teams help in governing RBAC for the FSR agent. While running connector actions using FSR agents, users will only see FSR agents that are associated with their teams.
    8. To complete adding the FSR agent, click Create.

Once you have completed adding the FSR agent, you will see the status for the FSR agent. Following is the list of statuses that can be displayed:

  • Configuration In Progress: Process of configuring the FSR agent has begun.
  • Awaiting Remote Node Connection: Connection between the FortiSOAR node and secure message exchange is established and awaiting the connection to the FSR agent.
  • Remote Note Connected: FSR Agent has been connected to the FortiSOAR node using secure message exchange.
  • Configuration Failed: FSR Agent failed to be added on the secure message exchange.
  • Message Exchange Unreachable: Secure message exchange is unreachable.
  • Remote Node Unreachable: FSR Agent is unreachable from the FortiSOAR node.

If the connection between the FortiSOAR node and secure message exchange is established, then the Status column displays "Awaiting Remote Node Connection" along a Download Installer link. Now, you are required to download the FSR agent installer and install the FSR agent as described in the following section.

Added the agent - Download installer link

In the Agent Actions column, you will see either the Export Config link or the Download Installer link. The Download Installer link represents a "FSR Agent" and you can use this link to install the agent at a specified endpoint. The Export Config link represents a "FSR Node", i.e., in this case the agent represents a dedicated tenant and you can use this link to export the configuration of the dedicated tenant.

If the Status column displays statuses like "Message Exchange Unreachable" or "Remote Node Unreachable", the Agent Actions column will also display a Retry link that allows you to again perform the operation.

From FortiSOAR version 6.4.4 onwards, you might also see a Warning symbol in the Agents Action column as shown in the following image:

Agents Action column - Warning symbol

The Warning symbol indicates that the master cannot remotely execute or manage connector actions on the FSR agent. Prior to version 6.4.4., the FortiSOAR UI did not provide any indication of remote connector management, and if remote connector management was disabled at the FSR agent, then the master was not notified. Due to this if the master triggers any remote request, then that would get ignored by the FSR agent since the remote operation had been disallowed. Therefore, in version 6.4.4, the Warning icon is introduced to indicate when remote connector management is disabled.

To enable or disable remote connector management on the FSR agent, you must have a minimum of Upgrade permission on the Agent module, and to disallow the master from remotely executing connector actions on an FSR agent, ensure that the FSR agent's version must be 6.4.4 and later.

Then, ssh to the FSR agent's VM and edit the /opt/cyops-integrations/integrations/configs/config.ini file and set the value of the ENABLE_REMOTE_CONNECTOR_OPERATION parameter:

  • To enable remote connector management, set the ENABLE_REMOTE_CONNECTOR_OPERATION parameter to true.
  • To disable remote connector management, set the ENABLE_REMOTE_CONNECTOR_OPERATION parameter to false.

Once you have completed editing the config.ini file and setting the value of the ENABLE_REMOTE_CONNECTOR_OPERATION parameter, restart the cyops-integrations-agent service. Restarting the cyops-integrations-agent service notifies these changes to the master node.

From version 7.0.2 onwards, the agent grid will also contain an Auth Type column which displays whether the agent will use Basic Auth or Certificate Auth to connect to the secure message exchange. It also contains a Certificate Expiry column, which displays when the client certificate will expire in case of Certificate Authentication or Basic Authentication with Peer Verification. In the case of Basic Auth, if you provide certificates while adding agents, then the certificate expiry will be displayed; however, if you do not provide any certificates while adding agents, then a blank will be displayed in the Certificate Expiry column shown in the following image:

Agent Grid - Authenticatoion Details

Note

If you have enabled mTLS on secure message exchange, and you have added the secure message exchange client certificate and key after the FSR agent is added or if you have updated the secure message exchange client certificate and key after they have expired, then you require to first disable and again enable the agent to re-trigger the event listener and update agent status correctly.

Installing a FSR agent

Before you install a FSR agent, ensure that you meet all the prerequisites to installing an FSR agent. For more information, see Prerequisites for installing a FSR agent.

To install a FSR agent, do the following:

  1. Click the Download installer link on the Agents page.
  2. On the Prepare and Download Agent Installer dialog, from the Include Specified Connectors to install on Agent drop-down list, choose which connectors you want to include while installing the FSR agent. You can choose from the following options: Do not install connectors by default, Custom, All connectors installed on Master, or Include pre-existing connectors on agent.
    FSR Agents use connectors to remotely run actions on a remote network. If you select Do not install connectors by default, then connectors are not installed on the FSR agent, except for the "Utilities" connector that is installed, by default, on the FSR agent.
    If you select Custom, then from the Select Connectors drop-down list you have to select the connectors that you want to install on the FSR agent. Note that only connectors that are installed on FortiSOAR (master) node can be installed on the agent. If you select All connectors installed on Master, then all the connectors that are installed on FortiSOAR are installed on the FSR agent.
    If you had an FSR agent system on which you had configured some connectors, which you required to re-provision, if for example, there were some issues with the FSR agent's system, then you can download the FSR agent installer again, and select the Include pre-existing connectors on agent option. Selecting the Include pre-existing connectors on agent bundles up the connectors and their configurations of those connectors that were previously installed and configured on the FSR agent.
  3. Click Download Installer.

Once you click Download Installer, the installer file named as <agent-name>-install.bin is downloaded on your VM. Copy-paste this installer to the FSR agent VM and install the FSR agent.

The installer installs the following for the FSR agent:

  • PostgreSQL database.
  • cyops-integrations-agent

After the installation is complete, you should check the status of the cyops-integrations-agent service. Also, note that the password for PostgreSQL is the ID of the FSR Agent.

Once you have completed installing the FSR agent, you can begin to run connector actions on FSR agents, install and configure custom connectors, and perform other administrative functions. For information on all these functions, upgrading the FSR agent, see the Segmented Network Support chapter in the "Administration Guide."

Deboarding FSR Agents

To deboard existing FSR agents, you require to have Read and Delete permissions on the Agents module. Deboarding agents not only deletes the FSR agent, but also removes the list of connectors installed and all the configurations of the connectors that have been installed on the specific FSR agent from the FortiSOAR node. Once you delete a FSR agent, you cannot retrieve any information related to that FSR agent, therefore you must be careful while performing this operation.

To deboard a FSR agent, log on to FortiSOAR as an administrator and click the Settings icon to open the System page. Click Agents in the left menu and on the Agents page, click Delete. FortiSOAR will display a warning dialog, click Confirm on the warning dialog to deboard the FSR agent.

Moving a FSR agent to a new secure message exchange

If you have added a new secure message in your environment, and you want to move your FSR agent to the new secure message exchange, do the following on the FortiSOAR system:

  1. Add the new secure message on your FortiSOAR system. For more information, see the Adding a Secure Message Exchange section.
  2. Log on to your FortiSOAR node, master node in case of a distributed multi-tenant configuration, as an administrator and click the Settings icon to open the System page.
  3. In the Agent Configurations section, click Agents in the left menu.
  4. Click to open the FSR agent record that you want to move to the new secure message exchange.
  5. In the FSR agent record, from the Secure Message Exchange drop-down list, select the secure message exchange on which you want to move the FSR agent.
  6. Restart the cyops-postman, uwsgi, and cyops-integrations-agent services on the master node, using the following command:
    systemctl restart cyops-postman uwsgi cyops-integrations-agent
    After you have completed updating the router information and restarting the services, you must download the FSR agent installer again and reinstall the FSR agent on the FSR agent VM.