Additional configuration settings for FortiSOAR™

You can optionally perform the following additional configurations for FortiSOAR™ based on your requirements.

If you want to externalize your FortiSOAR™ databases, which are PostgreSQL and ElasticSearch, see the "Administration Guide." The Externalization of your FortiSOAR™ PostgreSQL database chapter covers the steps for externalizing your PostgreSQL databases, and the ElasticSearch Configuration chapter covers the steps for externalizing your ElasticSearch database.

If you face any issues while deploying or upgrading FortiSOAR™, see the Troubleshooting FortiSOAR™ chapter. If you face deployment or upgrade failures due to insufficient space, or if you face issues while using FortiSOAR™ that might be caused due to insufficient space, like you are unable to log into FortiSOAR™ or FortiSOAR™ services stop working, then see the Issues occurring in FortiSOAR due to insufficient space section in the Troubleshooting FortiSOAR™ chapter.

Changing the hostname

The FortiSOAR Configuration Wizard is available only on the first ssh login. If at a later stage, you require to change the hostname of your FortiSOAR™ VM, then you can use the FortiSOAR™ Admin CLI (csadm). For more information on csadm, see the FortiSOAR™ Admin CLI chapter in the "Administration Guide."

To change the hostname, ensure that the hostname is resolvable and then do the following:

  1. SSH to your FortiSOAR™ VM and login as a root user.
  2. To change your hostname, type the following command:
    # csadm hostname --set [<hostname>]
    This command changes your current hostname to the new hostname that you have specified, sets up the message broker, regenerates certificates but does not replace nginx certificate, and restarts FortiSOAR™ services.

Important: It is recommended that you set the hostname of your FortiSOAR™ VM, at the time of deployment only and not after the FortiSOAR™ instance is in active use. If any errors occur when you are running the hostname change command, see the Troubleshooting FortiSOAR™ topic.

Replacing FortiSOAR™ self-signed certificates with your own signed certificates

Use this procedure to replace the FortiSOAR™ self-signed certificates with your certificates:
Note: Your certificate file must be in the .crt format. For example, if your certificate is in another format such as, a DER certificate from a Windows CA, then you need to create the .crt certificate from a .cer certificate, using the following command:
# openssl x509 -inform DER -in ssl_certificate.cer -out ssl_certificate.crt

To replace the FortiSOAR™ self-signed certificates with your certificates use the FortiSOAR™ Admin CLI (csadm). For more information on csadm, see the FortiSOAR™ Admin CLI chapter in the "Administration Guide."

  1. SSH to your FortiSOAR™ VM and login as a root user.
  2. To deploy your certificate, type the following command:
    # csadm certs --deploy
    You must then specify the following at the prompt:
    The complete path of the private key file of your ssl certificate.
    The complete path to the crt file of your ssl certificate.

Starting and stopping FortiSOAR™ Services

You will need to stop and start the FortiSOAR™ Services in the following cases:

  • Update/Upgrade your SSL certificates

  • Post-update, if playbooks are not working as expected

  • Post-reboot, if the FortiSOAR™ Platform is not working as expected

To stop and start all the FortiSOAR™ services, use the FortiSOAR™ Admin CLI (csadm). For more information on csadm, see the FortiSOAR™ Admin CLI chapter in the "Administration Guide." You can run the csadm command on any FortiSOAR™ machine using any terminal. Any user who has root or sudo permissions can run the csadm command.

To view the status of all FortiSOAR™ services, type: # csadm services --status

To restart FortiSOAR™ services, type: # csadm services --restart

To start FortiSOAR™ services, type: # csadm services --start

To stop FortiSOAR™ services, type: # csadm services --stop

Changing the FortiSOAR™ default database passwords

After you complete the FortiSOAR™ deployment procedure, you can change the default database passwords using the FortiSOAR™ Admin CLI (csadm) as a root user:
# csadm db --change-passwd

The script will prompt you for the new passwords for the Postgres DB, and you must appropriately enter the password that you want to set for the Postgres DB.

After running this script and changing the passwords, this script makes FortiSOAR™ use the new passwords and stores the passwords in an encrypted format. For more information on csadm, see the FortiSOAR™ Admin CLI chapter in the "Administration Guide."

Setting up a proxy server to service all requests from FortiSOAR™

Use the Environment Variables tab on the System Configuration page to configure proxy settings for FortiSOAR™ and to define any other environment variables.

Important: When you configure proxies using the FortiSOAR™ UI, the Environment Variables tab, the proxies get applied at the application level but not at the OS level. To configure proxies at the OS level, you need to make that entry in the /etc/environment file.

Whenever you change the proxy server settings or the environment variables you must restart the celeryd and uswgi services for the changes to take effect. Use the # systemctl restart celeryd and # systemctl restart uwsgi commands to restart the celeryd and uswgi services.

System Configuration Menu - Proxy Configuration tab

Note

External web pages that you open (for example, from a link included in the description field of an alert) or view (for example, using the iFrame Widget) in FortiSOAR™ goes through the configured proxy server if you have configured the proxy in the web browser's settings. If the proxy is not configured in the web browser's settings, then the external web pages are opened directly without using the configured proxy server.

Configuring Proxy Settings and environment variables

Use the following procedure to add proxy details and environment variables for FortiSOAR™:

  1. Log on to FortiSOAR™ as an administrator.
  2. Click Setting to open the System Configuration page (Application Configuration tab).
  3. Click the Environment Variables tab.
  4. To set up an HTTP proxy to serve all HTTP requests from FortiSOAR™, enter the following details in the Proxy Settings section on the Environment Variables page:
    1. In the Proxy URL field, enter the HTTP proxy server IP and in the Port field, optionally enter the HTTP proxy server port.
      Note: If you do not specify HTTP or HTTPS in the Proxy URL field, then by default HTTPS is set.
    2. In the Username field, enter the username used to access the HTTP proxy server (if not applicable leave this field blank).
    3. Click Set Password to enter the password used to access the HTTP proxy server (if not applicable leave this field blank).
    4. Verify that the Enabled check box is selected to apply the proxy settings that you have specified. If you clear the Enabled check box, then the proxy settings that you have specified are saved but not applied.
      By default, the Enabled check box is selected.
  5. To set up an HTTPS proxy server to serve all https requests from FortiSOAR™, enter the following details in the HTTPS section on the Environment Variables page:
    1. If you want to use the same proxy server that you have set up for HTTP requests for HTTPS requests as well, then select the Use Same As Above checkbox. Or set up the HTTPS proxy server as follows:
    2. In the Proxy URL field, enter the https proxy server IP and in the Port field, optionally enter the HTTPS proxy server port.
    3. In the Username field, enter the username used to access the HTTPS proxy server (if not applicable leave this field blank).
    4. Click Set Password to enter the password used to access the HTTPS proxy server (if not applicable leave this field blank).
    5. Verify that the Enabled check box is selected to apply the proxy settings that you have specified. If you clear the Enabled check box, then the proxy settings that you have specified is saved but not applied.
      By default, the Enabled check box is selected.
  6. (Optional) In the No Proxy List text box, enter a comma-separated list of addresses that do not require to be routed through a proxy server.
    For example, enter http://example.com in the No Proxy List text box.
    localhost and 127.0.0.1 are added by default to the no proxy list by the system.
  7. (Optional) In the Other Environment Variables section, you can add environmental variables and setup proxies for other protocols, such as FTP (other than HTTP or HTTPS) in a key-value pair. Click the +Add New link and the Key and Value text boxes will be displayed. Enter the protocol for which you want to set up the proxy in the Key text box and its value in the Value box.
    For example, enter FTP in the Key field and 1.1.1.1 in the Value field.
  8. Click Save to save your proxy server settings or the environment variables you have added.
    Important: Whenever you change the proxy server settings or the environment variables you must restart the celeryd and uswgi services for the changes to take effect. Use the # systemctl restart celeryd and # systemctl restart uwsgi commands to restart the celeryd and uswgi services.

Setting up a proxy for the yum command for FortiSOAR™

If your organization has a policy that all external traffic must pass through a proxy, then you must configure a proxy for the yum command. The yum command is used to install connectors, therefore, if you do not configure this proxy, FortiSOAR™ connectors will not get installed.

Edit the /etc/yum.conf file and specify the proxy settings:

proxy=http://proxysever.yourdomain.com:<TCP Port Number>
proxy_username=<proxy server username to use for the proxy URL>
proxy_password=<proxy server password to use for the proxy URL>

proxy is the Proxy server URL (domain name or IP address) that yum should use, and it must include the TCP port number. In the above example, proxysever.yourdomain.com is the URL of the proxy server. Do not forget to add the actual port number of the proxy server in place of the <TCP Port Number>.

If your proxy does not have any authentication, then you do not require to specify proxy_username or proxy_password.

Backing up the data encryption keys

Encryption keys are used to encrypt data in FortiSOAR™. When you install FortiSOAR™ for the first-time default encryption keys are added, which are unique per instance therefore, you do not need to change the encryption keys.

Important: It is highly recommended that you copy the encryption keys from the /opt/cyops/config/cyops-api/application.conf file and store them securely in a Password Manager or Vault.

Warning

Once you encrypt your production data in FortiSOAR™ using the encryption keys, you should not change those keys again, since if your encryption keys are changed, this might result in the loss of previously encrypted production data. If you do require to change the encryption keys, then contact FortiSOAR™ CS.

Updating the SSL certificates

When the FortiSOAR™ certificates expire, then you must update Nginx certificates, within the FortiSOAR™ Virtual Appliance as follows:

Note: Your SSL certificate file must be in the .crt format. FortiSOAR™ does not support certificate formats such as cer, p7b, etc.

  1. SSH to your FortiSOAR™ VM and login as a root user.
  2. Copy your certificates to /etc/nginx/ssl/.
    Note: When you deploy a custom certificate, you must ensure that the SAN name in the certificate should match the hostname (with or without a wildcard). If it is an IP address, it should be of type IPAddress in SAN name field.
  3. Edit the cyops-api.conf file that is located in the /etc/nginx/conf.d directory to update the ssl_certificate and ssl_certificate_key as follows:
    ssl_certificate /etc/nginx/ssl/yourCert.crt;
    ssl_certificate_key /etc/nginx/ssl/yourCert.key;
    For selinux permissions, run the following command:
    # restorecon -v -R /etc/nginx/ssl
  4. Edit the /etc/cyops/config.yml file to update crudhub_host to the DNS name specified in SSL Certificate.
  5. Restart the nginx service using the following commands:
    # systemctl restart nginx
  6. Clear your browser cache and re-login to FortiSOAR™ after updating the SSL Certificate.

Configuring a reverse proxy (Apache proxy server)

If you have set up a reverse proxy, an Apache proxy server, in your environment, then configure this reverse proxy server so that the live sync functionality works, as follows:

Important: This procedure applies only to an Apache proxy server. You can enable any other reverse proxy using a similar pattern to support the web socket functionality.

  1. Update the proxy configuration file on your proxy server as follows:

    <VirtualHost *:80>                                                                                                                                                                   
     #ServerName
     SSLProxyEngine on                                                                                                                                                                   
     SSLProxyCheckPeerCN on
     SSLProxyCheckPeerName on
    
     RewriteEngine On
     RewriteCond %{HTTP:Upgrade} =websocket [NC]
     RewriteRule /(.*)           wss://<CyOps-URL>/$1 [P,L]
    
     ProxyPass / https://<CyOps-URL>/
     ProxyPassReverse / https://<CyOps-URL>/
    
     RequestHeader set Host "<CyOps-URL>"
     RequestHeader set Origin "https://<CyOps-URL>"
    </VirtualHost>
    

  2. On the FortiSOAR™ server perform the following steps:

    1. Update the crud_hub host with the <fortisoar-URL> in the /etc/cyops/config.yml file as shown in the following example:
      update crudhub_host to https://<fortisoar-url>
      Example: crudhub_host: https://demo.fortinet.com
      Important: The <fortisoar-URL> must match with the SSL certificate Alternate DNS name.
    2. Restart all the FortiSOAR™ services by using csadm and running the following command as a root user:
      # csadm services --restart
      After all the FortiSOAR™ services have been successfully restarted, you should be able to load all the modules using the reverse proxy server.