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, and restarts FortiSOAR services.

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 chapter.

Note: After the hostname has been reset, when users execute playbooks with an external manual input link, it is observed that the link that is generated in the email contains the original FQDN (hostname) rather than the one that has been updated. Therefore, users who are required to provide the input, have to manually update the FQDN (hostname) in the manual input link present in the email.

Regenerating self-signed certificates

The default self-signed certificates shipped with FortiSOAR are valid for one year from the inception of your FortiSOAR instance. It is recommended to regenerate these certificates before the end of one year by running the following command as a root user (using 'sudo su' and using the csadmin password) using a SSH session:
csadm certs --generate `hostname`

Once this command is run successfully, you require to restart all services using the following command:
csadm services --restart

Updating the SSL certificates

Use the following procedure to update Nginx certificates within the FortiSOAR Virtual Appliance when the FortiSOAR certificates expire. You can also use the following procedures to replace FortiSOAR self-signed certificates with your own signed certificates.

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

If your certificate is in another format such as, a CER certificate from 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

There are two methods that you can use to update your SSL certificates:

• Using the FortiSOAR Admin CLI (csadm). For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."
• Manually: You can use this method in case you face some issues with csadm.

Method 1: Using csadm

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.

Method 2: Manually

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.

Adding self-signed CA certificates in CentOS as trusted certificates

You might want to add self-signed CA certificates in OS as a trusted certificate in cases where you are using an offline repository with a self-signed certificate or you have agents that use self-signed certificates to communicate with your FortiSOAR instance.

A CA certificate is self-signed, so it is not trusted by default in any OS. Due to this tools like OpenSSL clients, curl, wget, etc raise issues. Sometimes, you can use tool flags to bypass certificate checks, for example, using -k in curl to bypass the certificate check

To solve this issue in CentOS, you can add the self-signed CA cert in the OS as a trusted certificate, by exporting the self-signed CA certificate (including all intermediate CA certs), then importing them into the Centos CA store using the process defined in https://access.redhat.com/solutions/6339061. The process is detailed as follows:

Exporting the CA certificate using a browser

1. Open the offline repo URL in your browser.
2. Click on the Padlock sign, and then click on Connection is secure.
   
3. Clicking on Connection is secure opens the Security section as shown in the following image:
   
   Click Certificate is Valid in the Security section.
4. Clicking on Certificate is Valid opens the Certificate Detail dialog as shown in the following image:
   
   Click the Certification Path tab.
5. The Certification Path tab lists the complete CA chain as shown in the following image:
   
   Select one of the CA certificates and click View Certificate.
6. On the Certificate Detail dialog, click the Details tab and click OK.
   
   
7. Click the Copy to File button to open the 'Certificate Export Wizard' that you can use to copy the certificate file.
   
   
8. On the Welcome screen of the 'Certificate Export Wizard', click Next.
   
   
9. On the Export File Format screen, select Base-64 encoded as the file format to export, and click Next.
   
   
10. On the File to Export screen, click Browse to specify the location to export the CA certificate as a file and click Next.
    
    
11. On the Completing the Certificate Export Wizard screen, click Finish, to complete exporting the CA certificate.
    
    Use the same procedure to export all your CA certs in the certificate chain.

Adding the self-signed CA cert in the OS

You require to copy the CA certificate files that were exported to the destination CentOS system(s).

1. Create a certificate file abc.crt using for example your organization's name, abc, in the following location:
   /etc/pki/ca-trust/source/anchors/ abc.crt
2. Copy the contents from CA certificate files that were exported to abc.crt.
3. Execute the following command:
   update-ca-trust enable ; update-ca-trust extract
   

Verifying that the self-signed CA certificates are added as trusted certificates in CentOS

Run the following commands to verify if the self-signed CA certificates are added as trusted CA in CentOS:

• curl –v https://<offline-repo-server>
• wget https://<offline-repo-server>/7.0.0/upgrade-cyops-7.0.0.sh

If both the above commands should work without any certificate warnings or errors it means that the self-signed CA certificates are added as trusted CA in CentOS.

Setting up monitoring for your FortiSOAR system

It is recommended that you set up the following as part of your initial deployment and configuration process to monitor various important parts of your FortiSOAR system such as disk space, audit logs, execution logs, etc.

Setting up system monitoring

From version 6.4.3 onwards, you should set up system monitoring for FortiSOAR, both in case of a single node system and High Availability (HA) clusters on the System Configuration page. To know more about the setting up thresholds and enabling notifications to effectively monitor various FortiSOAR system resources such as CPU, Disk Space and Memory utilization, and the statuses of various FortiSOAR services, see the System Configuration chapter in the "Administration Guide."

For versions prior to 6.4.3, you should set up thresholds, schedules, and notifications for the System Monitoring playbook that is included by default with FortiSOAR to effectively monitor various FortiSOAR system resources. To know more about configuring thresholds, schedules, and notifications, see the System Monitoring: Setting up thresholds, schedules, and notifications article present in the Fortinet Knowledge Base.

Setting up purging for audit and playbook logs

FortiSOAR persists each workflow step inputs, outputs and error details for providing granular details of each action run, which is very useful for subsequent analysis and debugging. However, the Playbook Execution History data is significantly large and generates large volumes of data, which might not be useful after some point of time. Therefore, it is recommended that the retention period for the playbook logs should not be more than a few weeks and it is very important that you schedule purging for these logs at regular intervals.

FortiSOAR also audits every login, logout, record create, update, delete of records and other important activity on the system. These logs also might be useful for only a few years.

One must, therefore, configure a purge schedule for both the playbook and audit logs as per the organization's retention policy. This would help keeping the database and disk usage for these logs constant over time.

You can schedule purging, on a global level, for both audit logs and executed playbook logs. Scheduling purging of audit and executed playbook logs ensures that the logs are periodically cleared. For the procedure for enabling and scheduling purging, see the System Configuration chapter in the "Administration Guide."

For additional information about monitoring your FortiSOAR system, see the Monitoring FortiSOAR chapter in the "Administration Guide."

Configuring High Availability or Disaster Recovery options

You can configure FortiSOAR with either an externalized PostgreSQL database or an internal PostgreSQL database. For both cases you can configure Active-Active or Active-Passive high availability clusters. For more information, see the High Availability support in FortiSOAR chapter in the "Administration Guide."

FortiSOAR provides backup scripts that are scheduled to run at pre-defined intervals and take full database backup on a shared or backed up drive. For more information on backing up and restoring FortiSOAR, see the Backing up and Restoring FortiSOAR chapter in the "Administration Guide."

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

Your FortiSOAR instance would need access to the following endpoints on the public internet:

• For upgrading FortiSOAR, installing connectors, and accessing the widget library: https://repo.fortisoar.fortinet.com/
• For installing python dependencies for connectors: https://pypi.python.org
  Note: There is a parallel python repository also on repo.fortisoar.fortinet.com that can be used with some configuration if your organization does not approve pypi.
• For synchronization of FortiSOAR license details: https://globalupdate.fortinet.net
• For accessing any SaaS or API endpoint that you have configured, for example VirusTotal, and to which you require to be connected.

You must ensure that these endpoints are open from the organizations proxy. You can configure your proxy for the first time when you run the FortiSOAR Configuration Wizard. If you subsequently require to change the proxy, then you can use the csadm cli commands or use the UI as specified in the following procedure.

You can use the # csadm network set-https-proxy command to set the proxy for both your system and the web services. For more information on csadm, see the FortiSOAR Admin CLI chapter in the "Administration Guide."

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

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 forFortiSOAR:

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 fromFortiSOAR, 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.

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 back up the encryption keys (.Defuse.key) from the /opt/cyops/config/cyops-api file. The .Defuse.key is a dot file, therefore you need to use ls -la /opt/cyops/configs/cyops-api/ to list/view the file and store the data encryption keys securely in a Password Manager or Vault.

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 Support.

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.

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

<VirtualHost *:80>                                                                                                                                                                   
 #ServerName
 SSLProxyEngine on                                                                                                                                                                   
 SSLProxyCheckPeerCN on
 SSLProxyCheckPeerName on
 
 /** Section required for enabling Websockets **/
 RewriteEngine On
 RewriteCond %{HTTP:Upgrade} =websocket [NC]
 RewriteRule /(.*)           wss://<FortiSOAR-URL>/$1 [P,L]
 /** End Section **/

 ProxyPass / https://<FortiSOAR-URL>/
 ProxyPassReverse / https://<FortiSOAR-URL>/

 RequestHeader set Host "<FortiSOAR-URL>"
 RequestHeader set Origin "https://<FortiSOAR-URL>"
</VirtualHost>