System Configuration

You can customize FortiSOAR and configure several default options used throughout the system, including the way FortiSOAR gets displayed to the users and the way notifications are sent to the users. To configure the system, you must be assigned CRUD permissions to the Application module. The Application module is assigned by default to the Application Administrator role. For information about roles, refer to the Default Roles section in the Security Management chapter.

Click the Settings () icon to open the System (System Configuration) page. Use the Application Configuration tab on the System Configuration page to edit several default options found throughout the system, especially in the user profile. These include the following:

• Default notifications for system and cluster health monitoring
• Default Comment Modification
• Default Playbook Execution Logging Levels
• Default Playbook Recovery options
• Default timezone for exporting reports
• Default theme
• Purging of audit logs and executed playbook logs and cleaning the database
• Purging of recycle bin records
• Default country code
• Default navigation bar style
• Manage user listings in People Lookup fields
• Enable MIME type validation for file uploads

For more information on user profile configuration, refer to the User Profiles section in the Security Management chapter.

You can modify all the default values on a per-user basis on any user's Profile page.

To enable sending system notifications, including requests for resetting passwords, and also for sending emails outside FortiSOAR you must configure the SMTP connector. For more information on FortiSOAR Built-in connectors, including the SMTP connector, see the "FortiSOAR Built-in connectors" article.

Click Settings > Audit Log to open the Audit Log page. Use the Audit Log page to view a chronological record of all actions across FortiSOAR. For more information, see Audit Log.

Click Settings > License Manager to open the License Manager page. Use the License Manager page to update your license and view the details of your FortiSOAR license. For more information, see License Manager.

Click Settings > Notifications to open the Notifications page. Use the Notifications page to configure rules for delivery of notifications and also configure notification channels. For more information, see Notifications.

Click Settings > Data Archival to open the Data Archival page. Use the Data Archival page to configure settings for data archival and to search for records in the data archives. For more information, see Data Archival.

Use the Environment Variables tab on the System Configuration page to add proxies to serve HTTP, HTTPS, or other protocol requests from FortiSOAR or define environment variables. For the procedure for configuring proxy settings and defining environment variables is included in the Configuring Proxy Settings and environment variables topic in the Additional configuration settings for FortiSOAR chapter of the "Deployment Guide."

Use the Branding tab on the System Configuration page to customize FortiSOAR branding based on your license type. For more information, see Branding.

Use the System Fixtures tab on the System Configuration page to view the links to various playbook collections and templates, which are included by default with FortiSOAR. For more information, see System Fixtures.

Application Configuration

On the Application Configuration page, you can configure settings that will apply across FortiSOAR. You can edit the settings and then click Save to apply the changes or click Revert to revert your changes.

Configuring System and Cluster Health Monitoring

You can set up system monitoring for FortiSOAR, both in case of a single node system and High Availability (HA) clusters. To receive email notifications of any FortiSOAR service failure, or of any monitored thresholds exceeding the set threshold, etc., click the Enable Notification checkbox in the System & Cluster Health Monitoring section.

Once you click the Enable Notification checkbox, from the Service drop-down list, select the service to be used for notifications. You can choose between SMTP or Exchange. In the Email field, specify the email address that will be notified in case of any service failures, threshold breaches, etc.

From version 7.0.0 onwards, the email that is sent for high CPU consumption will also contain information about the processes that are consuming the most memory.

In the Monitoring Interval (Minutes) field specify the interval in minutes at which you want to monitor the system and perform the health check of the HA cluster. By default, the system is monitored every 5 minutes.

In the System Health Thresholds section, you can set the thresholds, in percentages, for Memory Utilization (80% default), CPU Utilization (80% default), Disk Utilization (80% default), Swap Memory Utilization (50% default), Workflow Queue Threshold, i.e., the value of the celery queue size, and from release 7.2.0, WAL Files Size (GB), which by default it is set as 20 GB. The default value of the workflow queue is set at 100. If the thresholds set are reached or crossed for any of the monitored parameters, an email notification is sent to the specified email addresses.

If you have an HA environment, then in addition to the above settings, you can also monitor and get notified in case of heartbeat failures and high replication lags between nodes of your HA cluster. You can specify values for these parameter in the Cluster Health section:

In the Missed Heartbeat Count field, specify the count of missed heartbeats after which notifications of failure will be sent to the email addresses you have specified.

You cannot specify a value lesser than 3 in the Missed Heartbeat Count field.

In the Replication Lag field, specify the threshold, in percentage, for the replication lag between nodes. By default, this is set to 60%. This 60% is relative of the total max lag of 10 GB (wal_segment_count, 640 in postgresql.conf). If the replication lag threshold is reached or crossed, then an email notification is sent to the specified email addresses.

Some examples of how Monitoring Interval (Minutes) and Missed Heartbeat Count values help you in monitoring heartbeats between nodes in an HA cluster:

Case 1

If you have set the Monitoring Interval to 5 minutes and the Missed Heartbeat Count to 3, this means that when the heartbeat is missed (the cyops-ha service is down) for the last >=15 minutes (monitoring interval * missed heartbeat count), the heartbeat missed notification will be sent to the email address that you have specified in the Email field.

The cluster health check is performed based on the monitoring interval specified. For example, if you specify 3 minutes in the Monitoring Interval (Minutes) field, then the HA cluster health check will be run every 3 minutes.

Notifications get sent based on the multiplication of the values that you have set in the monitoring interval and missed heartbeat count. For example, if you have set monitoring interval to 3 and missed heartbeat count to 4, and if the heartbeat is missed for the last >=12 minutes, then heartbeat missed notifications will be sent to the email address that you have specified in the Email field.

Case 2

If you have no heartbeats missed for the last >=15 minutes, considering monitoring interval set to 5 minutes and missed heartbeat count set to 3; however, there is a service down or a service connectivity failure found in the health check, then a notification for service down or service connectivity failure will be sent to the email address that you have specified in the Email field.

For more information on HA, see the High Availability support in FortiSOAR chapter.

Configuring Comments

A user who has Security Update permissions can edit comments of any FortiSOAR user, and a user who has Security Delete permissions can delete comments of any FortiSOAR user. There is no time limit for the Security user to update or delete comments.

Users can edit and delete their own comments in the "Collaboration" window or in the Comments widget, if you (the administrator) has enabled the settings for comment modification and if the user has appropriate CRUD permissions on the Comments module.

To allow users to edit and delete their own comments, click the Settings icon, which opens the System Configuration page. On the Application Configuration tab, in the Comment Modification section, select the Allow Comment Modification checkbox.

You can also specify the time until when the user can edit or delete their comments in the Allow users to modify /delete their comments for a duration of field. For example, if you select 1 minute from this field, then users can edit and delete their comments until 1 minute after which they have added the comment. By default, the Allow users to modify/delete their comments for a duration of field is set to 5 minutes. Users cannot edit or delete their comments after the time specified in the Allow users to modify/delete their comments for a duration of field.

You can also specify the behavior of the comment "delete" action, i.e., when a user deletes a comment, you can choose to permanently delete the comment or flag the comment for deletion, i.e., Soft Delete. If you choose to keep the Soft Delete checkbox checked (default), then the comments will be soft deleted, i.e., on the UI you will see --Comment Deleted-- instead of the comment. In case you have cleared the Soft Delete checkbox, you will not see anything on the UI since the comment has been permanently deleted.

Purging of audit logs and executed playbook logs and reclaiming unused disk space

You can schedule purging, on a global level, for both audit logs and executed playbook logs. Click the Settings icon, which opens the System Configuration page. In the Purge Logs section, you can define the schedule for purging both Audit Logs and Executed Playbook Logs.

By default, audit logs are not purged and executed playbooks logs are purged.

The Purging activity deletes logs permanently, and you cannot revert this operation.

Purging logs deletes old records from the respective tables; however, it does not free up the PostgreSQL database space, which could cause space and performance issues in FortiSOAR. Therefore, from version 7.0.2 onward, FortiSOAR provides you with an option to reclaim unused disk space. This activity clears all the empty rows in tables and indexes, which helps in improving the performance by optimizing the space. By default, this cleanup activity is run "Weekly at 02:01 AM (UTC) on Sunday"; however, you have the ability to update the schedule of this cleanup activity as per your requirement.

Scheduling purging of audit logs

To purge Audit Logs, you must be assigned a role that has a minimum of Read permission on the Security module, Read permission on the Application module, and Delete permissions on the Audit Log module.

To enable purging of Audit logs, select the Enable Purging checkbox that appears in the Audit Logs section.

Once you select the Enable Purging checkbox, you require to define the schedule for purging of audit logs. To specify the time for which you want to retain the logs, you must select the appropriate option from the Keep logs Of drop-down list. You can choose from the following options: Last month, Last 3 months, Last 6 months, Last year, or Custom as shown in the following image:

If you choose Custom, then you must specify the number of days for which you want to retain the logs.

For purging purposes, 1 month is considered as 30 days and 1 year is considered as 365 days.

The purging schedule clears all logs that belong to a timeframe earlier than what you have specified.

For example, if you want to retain audit logs for a month, then select Last month from the Keep logs of drop-down list. Once you save this setting all audit logs that are older than 1 month (30 days) will be cleared, and this will be an ongoing process, as the audit log records will all be time-stamped and the ones older than 30 days will be purged.

By default, the purge schedule job, runs every midnight (UTC time) and clears all logs that have exceeded the time duration that you have specified. If you want to run the purging activity at a different time of the day or for a different duration, you can do so by editing the schedule of purging on the Schedules page (Automation > Schedules) once you enable purging of the logs.

Scheduling purging of executed playbook logs

To purge Executed Playbook Logs, you must be assigned a role that has a minimum of Read and Update permissions on the Security module, Read and Update permissions on the Application module, and Delete permissions on the Playbooks module.

Purging of executed playbook logs based on date or days criteria

Executed Playbook Logs are purged by default, and therefore the Enable Purging checkbox is already selected in the Executed Playbook Logs section. By default, any executed playbook logs that are older than 15 days are purged. You can change time for which you want to retain the playbook execution logs by selecting the appropriate option from the Keep logs Of drop-down list, as is the case with audit logs.

A system schedule, named "Purge Executed Playbook Logs" is also already created and active on the Schedules page. This schedule runs every midnight (UTC time) and clears all logs that have exceeded the time duration that is specified. If you want to run the purging activity at a different time of the day or for a different duration, you can do so by editing this schedule.

Purging of executed playbook logs based on criteria other than date or days

From version 7.0.0 onwards, you can purge executed playbook logs based on some complex query condition that involves multiple parameters and not just the date or days criteria. For example, clearing logs of ingestion playbooks that have completed their execution. Being able to clear logs based on these criteria is useful since ingestion playbooks are generally scheduled and they can occupy a major chunk of playbook history in the database. Therefore, this feature provides you with an option to build desired queries for purging executed playbook logs and scheduling the purging.

To add the custom criteria, based on the clearing ingestion playbook that have completed their execution example, do the following:

1. Click the +Add link in the "Additional Criteria" section.
2. In the Criteria Title field, enter the title of the criteria based on which you want to purge the executed playbook logs. For example, Purging Ingestion Playbook Logs.
3. Select the logical operator, All of the below are True (AND), or Any of the below is True (OR). For our example, we require the AND operator, since we want to purge all playbooks that contain the "ingestion" tag and whose status is finished, so select All of the below are True (AND).
4. Click the Add Condition link to add conditions for purging the executed playbook logs:
   From the Select a field drop-down, select Tags, from the Operator drop-down list select Contains and in the Add Tags field, enter ingestion. Click the Add Condition link again, and from the Select a field drop-down, select Status, from the Operator drop-down list select Equals, in the Status drop-down list select Finished.
   You can add additional conditions or criteria as per your requirements.
   
5. Schedule the purging of the executed playbooks logs based on the above-specified criteria by selecting the appropriate option from the Keep Logs Of drop-down list. You can choose from the following options: Last month, Last 3 months, Last 6 months, Last year, or Custom.
   For our example, we choose the Custom option and specify 1 for days, which means that keep the logs for the ingestion playbooks that have finished their execution for just 1 day in the database.
   
   
6. To save the criteria for purging executed playbook logs, click Save.

Points to be considered while setting multiple purging criteria

If you have added multiple purging criteria, then the purge functionality purges logs sequentially.
For example, if you have defined the following criteria

• Default: Keep logs of the last 2 days.
• If 'Playbook Execution Status = Failed', then keep logs for last 1 day.
• If Tags contain Ingest, then keep logs for last 1 day.

In such a scenario, logs are purged as follows:

1. Retains logs for the last 2 days only, and purges the remaining logs.
2. From the logs of the last 2 days, looks for logs that have 'Playbook Execution Status = Failed', and keeps such logs for the last 1 day only.
3. Looks for logs that have 'Tags' containing 'Ingest', and keeps such logs for the last 1 day only.

Scheduling storage space reclamation

To reclaim unused space, ensure that the Storage Space Reclamation option is selected (default). This activity clears all the empty rows in tables and indexes, which helps in improving the performance by optimizing the space.

You can schedule regular storage space reclamation to ensure that space gets regularly freed up in the PostgreSQL database as per your requirements.

It is recommended to run the cleanup schedule after logs have been purged and during times when the system usage is lower, as this process can slow your system's performance.

In the Storage Space Reclamation Settings section, you can select the frequency of running the storage space reclamation activity. You can choose between running this activity Weekly or Daily or to some custom frequency based on your requirements. By default, a system schedule named "Reclaim Disk Space (Playbook Logs)" is created in Automation > Schedules to periodically clear the playbook execution logs "Weekly at 02:01 AM on Sunday".
To change this schedule to a custom frequency, click the View link to display its Schedule Details and edit the schedule as per your requirement, and then click Save. For example, to run this activity "Weekly on Mondays at 12:01", change the schedule as follows:

You can view the % of disk space that is being used for playbook logs that is eligible for cleanup and which can be reclaimed, and you can also immediately initiate a cleanup of playbook logs by clicking the Initiate Cleanup Now link, which displays a confirmation dialog. Clicking Confirm on the dialog immediately starts the disk space reclamation activity.

Configuring the logging level for Playbook Execution Logs

From version 7.0.2 onwards, you can define the logging levels for your playbook execution logs, both globally as well as at the individual playbook level. On the System Configuration page, you can choose either INFO or DEBUG as the global playbook logging level.

INFO is set as the default global playbook logging level for fresh installations of FortiSOAR. If you are upgrading FortiSOAR, then the DEBUG mode is set as the default playbook logging level to ensure that there is no data loss.

• INFO: At the 'INFO' level, only the final playbook execution status and individual playbook step status information is available after playbooks have completed their execution. It is recommended that you keep the logging level at INFO for production instances and in scenarios where you want to use storage space efficiently.
  With the INFO logging level, you can select the Enable DEBUG level logging for failed playbooks checkbox, which enables 'DEBUG-level' logging for failed playbooks.
• DEBUG: At the 'DEBUG' level, detailed logging is enabled that includes additional execution information like step input, output, configurations and other details.
  

  Enabling DEBUG level logging can quickly fill up the storage space. It is recommended to use it only while designing or debugging playbooks, or use this option wisely only for certain playbooks where this data might be useful

Selecting the Allow individual playbook log level logging settings to override global settings checkbox honors the logging level that has been set at the individual playbook level. If you clear this checkbox, or do not change the logging level at the individual playbook level (default is INFO), then the global playbook logging level gets applicable. This is useful if you want to temporarily switch logging for the entire environment.

You can set the logging level of individual playbooks, even if you clear the Allow individual playbook log level logging settings to override global settings checkbox; however, at the time of playbook execution the global playbook logging level gets applied.

Configuring Playbook Recovery

Use the autosave feature in playbooks to recover playbook drafts in cases where you accidentally close your browser or face any issues while working on a playbook.

In the Playbook Recovery section, you can define the following:

• If you do not want FortiSOAR to save playbook drafts, clear the Enable Playbook Recovery option. By default, this option is checked.
• In the Save Drafts Every field, enter the time, in seconds, after which FortiSOAR will save playbook drafts. By default, FortiSOAR saves playbook drafts 15 seconds after the last change.
  The minimum time that you can set for saving playbook drafts is 5 seconds after the last change.
  

Scheduling purging of recycle bin records

You can schedule the purging of recycle bin records to periodically clear the soft-deleted records from the recycle bin. For more information, see the Recycle Bin chapter.

To purge Recycle Bin records, you must be assigned a role that has a minimum of Read and Update permissions on the 'Application' module.

Click the Settings icon, which opens the System Configuration page. To enable purging recycle bin records, in the Purge Recycle Bin section, select Enable Purging.

Once you select the Enable Purging checkbox, you require to define the schedule for purging of recycle bin records. To specify the time for which you want to retain the recycle bin records, you must select the appropriate option from the Keep records upto drop-down list. You can choose from the following options: Last month, Last 3 months, Last 6 months, Last year, or Custom as shown in the following image:

If you choose Custom, then you must specify the number of days for which you want to retain the recycle bin records.
For example, if you want to retain the recycle bin records for a month, then select Last month from the Keep records upto drop-down list. Once you save this setting all recycle bin records that are older than 1 month (30 days) will be cleared, and this will be an ongoing process, as the records will all be time-stamped and the ones older than 30 days will be purged.

Configuring the default timezone for exporting reports

You can define a timezone that will be used by default for exporting reports. This timezone will be applied by default to all reports that you export from the Reports page. To apply the default timezone, click the Enable Timezone Selection option in the Report Export section. Then from the Timezone drop-down list, search for and select the timezone in which you want to export the report. For example, if you want to search for the timezone of Los Angeles, you can type los in the search box below the Timezone field to find the correct timezone, as shown in the following image:

Managing user listings in People Lookup fields

From version 7.0.1 onwards, you can choose to display only active users in 'people lookup' fields, such as assignedTo, across FortiSOAR. To manage user listings in people look up fields, ensure that the Restrict People Lookups To Active Users checkbox in the People Lookup Filter section is selected. If the Restrict People Lookups To Active Users checkbox is cleared then both active and inactive users will be displayed in people lookup fields.

Enabling MIME type validations for file uploads

In release 7.2.0, you can specify the MIME types that will be disallowed from being uploaded in Attachments, Comments, or any other modules that have fields of type 'File'. Using this option, administrators can restrict potentially malicious files of types such as .exe, .bat, etc. to be uploaded into FortiSOAR, which users can later download. FortiSOAR has not added this restriction as defaults since there could be business use cases such as where users as part of automation read the file being sent to them in emails, and then upload the same to FortiSOAR to be used in the future for different operations like sandboxing, etc. Therefore, administrators can enable MIMI type validations for file uploads as per their organization’s policies by adding MIME types in the Restricted File MIME Types section:

In addition to restricting MIME types, you can also block specific HTML tags and attributes from being added to HTML content in Rich Text fields. For more information, see Blocking specific HTML tags and attributes.

Configuring Themes

You can configure the FortiSOAR theme that will apply to all the users in the system.

Non-admin users can change the theme by editing their user profile. Changes made by a non-admin user to the theme are applicable only to those users who have not changed their default user profile settings.

There are currently three theme options, Dark, Light, and Space, with Space being the default. On the Application Configuration page, select the theme that you want to apply across FortiSOAR. Click Preview Theme to view how the theme would look and click Save to apply the theme.

To revert the theme to the default, click Revert Theme.

Configuring Default Country Code

You can configure country code format for contact numbers that will apply to all users in the system. In the Phone Number section, select the Default Country and thereby the default country code that you want to apply across FortiSOAR and click Save to apply the code.

Configuring Navigation Preferences

You can configure the behavior of the left navigation bar across FortiSOAR. You can choose whether you want the left navigation bar to collapse to just display icons of the modules or expand to display both icons and titles of modules. In the Navigation Preferences section, click Collapse Navigation to collapse the left navigation bar and click Save to apply the behavior of the left navigation bar across the system.

Log Forwarding

Many organizations use an external log management server to manage logs and maintain all logs at a single place, making analysis efficient. From version 6.4.3 onwards, FortiSOAR application logs and audit logs can be forwarded to your central log management server that supports a Rsyslog client, using both the FortiSOAR UI and the csadm CLI. You can also select the category of the logs you want to forward to the external log management server. For information about configuring syslog forwarding using the CLI, see the FortiSOAR Admin CLI chapter.

If you have a FortiSOAR HA setup, then note that Syslog settings are not replicated to the passive node. If you want to forward logs from the passive node, you must enable it manually using the csadm log forward command.

You could also send FortiSOAR logs to a SIEM, since all SIEMs support syslog ingestion, and which would help you achieve the following

• Ease High Availability (HA) troubleshooting since now you can use consolidated logs instead of having to go individual nodes to debug HA issues.
• Ability to forward FortiSOAR logs to your SIEM, if you have a policy of setting up log forwarding to SIEM for all your production devices.
  Once the logs are in the a SIEM, you can further configure rules for raising alerts for specific failure, making system monitoring more effective.

Click Settings > System Configuration and then click the Log Forwarding tab to open the Log Forwarding page. Use the Log Forwarding page to setup, modify, and enable or disable your syslog forwarding of FortiSOAR logs to your central syslog server. To enable syslog forwarding, click the Enable Log Forwarding check box.

Once you select the Enable Log Forwarding, you require to fill in the details of the syslog server to which you want to forward the FortiSOAR logs, the type of logs to forward, etc.

You can configure only a single syslog server.

1. In the Configuration Name field, add the name of the configuration in which you want to store the log forwarding configuration details.
   Note: The name that you specify must not have any special characters, underscores, or spaces.
2. In the Syslog Server Details section, enter the following details:
   1. In the Server field enter the DNS name or IP address of the syslog server to which you want to forward the FortiSOAR logs.
   2. From the Protocol drop-down list, select the protocol that you want to use to communicate with the syslog server. You can choose between UDP, TCP, or RELP.
   3. In the Port field enter the port number that you want to use to communicate with the syslog server.
   4. (Optional) To securely communicate with the syslog server, click Enable TLS.
      Once you click Enable TLS, in the Certificate field, you must enter your CA certificate.
      If you have a client certificate for your FortiSOAR client, then in the Client Certificate and Client Key fields, you must enter the client certificate and the client key.
3. In the Choose Log Types To Forward section, choose the types of FortiSOAR logs you want to forward to the syslog server.
   Application Logs include OS logs, and this checkbox is selected by default. To also forward FortiSOAR audit logs, click the Audit Logs checkbox. Once you select audit logs, you can define the following:
   1. From the Specify Audit Log Detail Level drop-down list, select the amount of data, Basic or Detailed that you want to forward to the syslog server. Basic (default and recommended) sends high-level details of the event per audit log, whereas Detailed sends detailed information about the event per audit log.
   2. In the Configure Audit Log Forward Rules section, define the rules to forward audit logs:
      From the Record Type drop-down list, select the record types such as, Alerts, Incidents, etc. whose audit logs you want to forward to the syslog server.
      From the User drop-down list, select the users such as, CS Admin etc., whose audit logs you want to forward to the syslog server.
      From the Operation drop-down list, select the operations such as Create, UpdateConfig, Delete, etc., whose audit logs you want to forward to the syslog server.
      From the Playbooks drop-down list, select the operations such as Generate Incident Summary Report, Playbook Execution History Cleanup, etc., whose audit logs you want to forward to the syslog server.
      To add more rules, click the Define More Rules link.
      Important: If you do not define rules, then all the audit logs will be forwarded.
4. Once you have completed configuring syslog forwarding, click Save.
   FortiSOAR performs validations such as, whether the syslog server is reachable on the specified port etc. before adding the syslog server.
   Once the syslog server is added, you can update or remove the configuration as per your requirements.

Persisting the FortiSOAR logs

If your external log management server goes down, then the FortiSOAR logs generated during that time period will not be sent by FortiSOAR to your syslog server. If you want to persist the logs for the time frame when external log management server is down and send those logs when server comes back online, you need to do the following:

In the /etc/rsyslog.d/00-rsyslog-fortisoar-settings.conf file, add the following contents after the #### add the server details after this #### line:

#### add the server details after this ####
$ActionQueueType LinkedList 
$WorkDirectory /home/csadmin/.offline-rsyslogs/
# 
# for the workdir mentioned above, make sure you run 
# chown -R -t syslogd_var_lib_t /home/csadmin/.offline-rsyslogs/ 
# 
$ActionQueueMaxDiskSpace 1gb # 1gb space limit (You can change this value) 
$ActionQueueFileName fortisoar-offline-rsyslog 
$ActionResumeRetryCount -1 
$ActionQueueSaveOnShutdown on 

Next, run the following commands:
mkdir -p /home/csadmin/.offline-rsyslogs/
chcon -R -t syslogd_var_lib_t /home/csadmin/.offline-rsyslogs/
systemctl restart rsyslog

Environment Variables

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

The procedure of how to configure proxy settings and define environment variables is included in the Configuring Proxy Settings and environment variables section in the Additional configuration settings for FortiSOAR chapter of the "Deployment Guide".

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.

Branding

You can customize branding of FortiSOAR as per your requirement. From version 6.4.0 onwards, branding is not bound based on licensing, i.e., all customers can customize FortiSOAR branding as per their requirements.

To customize your branding in FortiSOAR, you must have a role which has a minimum of Application Update permission and then can do any or all of the following branding changes:

• Changing Logos: You can update the FortiSOAR logo to reflect your logo in the FortiSOAR UI. However, note that the maximum size for a logo is 1 MB.
  Update your logo in the Logo Settings section:
  Brand Logo (Small) - Dark Theme and Brand Logo (Large) - Dark Theme: Click the FortiSOAR logos and browse to the logos that you want to display in FortiSOAR Dark or Steel theme in two sizes: Small (90px X 72px) and Large (210px X 24px).
  Brand Logo (Small) - Light Theme and Brand Logo (Large) - Light Theme: Click the FortiSOAR logos and browse to the logos that you want to display in FortiSOAR Light theme in two sizes: Small (90px X 72px) and Large (210px X 24px).
  Note: You can hover on the information icon to view where these logos will appear in FortiSOAR.
• Changing the Favicon: To change the favicon that is displayed in FortiSOAR, click the FortiSOAR favicon and browse to the icon that you want to display as a favicon.
  Note: You can hover on the information icon to view where this favicon will appear in FortiSOAR.
  
• Editing the Product Name: To change the name of the product displayed in the FortiSOAR UI, in the Product Name field, enter the name of the product that you want to display in the UI.
• Editing the Company Name: To change the name of the company displayed in the FortiSOAR UI, in the Company Name field, enter the name of the company that you want to display in the UI.
• Editing the Login Tagline: To change the customized messages or taglines that appears to all users on their login screen, you can deselect the default tagline(s) by clicking the red cross that appears beside the tag line. The tagline that you deselect will not appear on the login page.
  
  You can then add your own tag line in the Login Page Tag Lines section as follows:
  In the Heading Text field: Enter the heading for your tagline.
  In the Sub Heading Text field: Enter the sub-heading for your tagline.
  In the Button Label and Button Hyperlink fields: If you want to add a button on your login page, which on clicking by the user, navigates the user to another web page, then enter the label of the button and the URL of the other web page in the Button Label and Button Hyperlink fields respectively.
  Once you complete adding your tag line, click Add.

To save your branding updates, click Save, to reset the branding to its default, click Reset to Default.

System Fixtures

The FortiSOAR UI includes links in the System Configuration page to the various playbook collections and templates, which are included by default when you install your FortiSOAR instance. Click the System Fixtures tab on the System Configuration page to view the links to the system playbook collections and templates. Administrators can click these links to easily access all the system fixtures to understand their workings and make changes in them if required. In the previous versions, administrators required to know the complete URL for these fixtures to access them and make required changes.

You can see these fixtures when you install FortiSOAR and the SOAR Framework solution pack. As you install other solution packs, you might see system fixtures added by those respective solution packs.

The following fixtures are included:

Playbooks:

• Approval/Manual Task Playbooks collection: Includes a collection of system-level playbooks that are used to automate approvals and manual tasks, such as triggering the resume playbook when the input is received for manual tasks.
  
• Schedule Management Playbooks collection: Includes a collection of system-level playbooks that are used for the scheduler module and used for various scheduler actions such as scheduling playbook execution history cleanup, audit log cleanup, etc.
• Report Management Playbooks collection: Includes a collection of system-level playbooks that are used to manage generation of FortiSOAR Reports, such as exporting reports, generating reports, generating reports based on a schedule, etc.

Playbooks that contain a reference to the approvalHost global variable fail with the 'approvalHost variable undefined' error, since the approvalHost global variable is removed from release 7.2.0 onwards. To resolve this error, replace the approvalHost global variable in the playbook with the Server_fqhn global variable.

For more information on system-level playbooks, see the Introduction to Playbooks chapter in the "Playbooks Guide."

Email Templates

• Password Reset Token: Includes an email template that is sent to FortiSOAR users' who forget their password and click on the Forgot Password link, so that they can reset their password. This email contains a link that the user can use to create their new password.
• Send Email To New User: Includes an email template that is sent to a new FortiSOAR users' and it contains a link that the new user can use to create their own new password.
• Send Email For Password Change: Includes an email template that is sent when a user requests for a change in their FortiSOAR password.
• Send Email For Reset Password By Admin: Includes an email template that is sent to FortiSOAR users' whose password has been reset by an administrator.

To modify the content of the email templates, click the email template whose content you want to change, for example, click Password Reset Token to open the email template. Click the Edit Record button to edit the contents of the template. You can also click the Edit Template icon to edit the structure of the email or click Actions to perform actions on the record.

To change the content of the email, click the Edit icon, or click the Edit Record to open the email template in a "form" format in which you can change the contents of the email as per your requirement, and then click Save to save your changes.

In case you have deleted the email templates, and you require to update or modify the default email templates, then you require to edit the mailtemplate.yml file located at /opt/cyops/configs/cyops-api/.

Audit Log

You can view the historical record of activities across FortiSOAR using the Audit Log, the User-Specific Audit Logs, and the graphical representation of the Audit Log in the detail view of a record.

Audit Log Permissions

• To view your own audit logs, you must have a role with a minimum of Read permission on the Audit Log Activities module. To view audit logs of all users, you must have a role with a minimum of Read permission on the Security and Audit Log Activities modules.
• To filter audit logs based on users you must have a role with a minimum of Read permission on the People, Appliances, and Audit Log Activities modules.
• To delete your own audit logs, you must have a role with a minimum of Delete permission on the Audit Log Activities module. To delete audit logs of all users, you must have a role with a minimum of Delete permission on the Security and Audit Log Activities modules.
  Note: The Delete permission on the Audit Log Activities module will be removed for both csadmin and playbook appliances roles, and also this will not be enabled (checked) by default for the Full App Permissions role. Therefore, if you want any user or role to have the right to delete audit logs, you must explicitly assign the Delete permission on the Audit Log Activities module to that particular user or role.

If you cannot access the Audit Log, you must ask your administrator for access. FortiSOAR displays an error, as shown in the following image, if you do not have access to Audit Logs:

You can view historical record of activities across FortiSOAR using the following options:

• Audit Log: Audit Log displays a chronological list of all the actions across all the modules of FortiSOAR. Click Settings > Audit Log to open the Audit Log page.
• User-Specific Audit Logs: User-Specific Audit Logs displays a chronological list of all the actions across all the modules of FortiSOAR for a particular user.
• Viewing Audit Log in the detailed view of a record: You can view a graphical presentation, or grid view, of all the actions performed on that particular record. The audit log is displayed in a graphical format using the Timeline widget.

Audit Logs include data such as, recording the name of the user who had deleted the record, linking and delinking events, picklist events, and model metadata events (including changes made in model metadata during the staging phrase). Free text search, additional filtering criteria, the ability to quickly add auditing for a new service and lazy loading has also been implemented in audit logs.

Audit logs also contain operations related to playbooks such as trigger, update, terminate, resume, create and delete playbook versions, etc. From version 6.4.1 onwards, the operations such as Snapshot Created and Snapshot Deleted operations are renamed to Version Created and Version Deleted since snapshots have been renamed to versions. However, for older audit logs in cases of an upgrade, you will see the old audit log entries with the older names such as Snapshot Created or Snapshot Deleted.

The data included in the audit log also contains the following types of entries:

• Users' login success or failures and logout events. The login event includes all three supported login types, which are DB Login, LDAP Login, and SSO Login.
• Users' login with an invalid username.
• Locked users's attempts to log on to FortiSOAR.
• Locking of users' account in the event of multiple failed login attempts.
• Inactive users's attempts to log on to FortiSOAR.
• Forced log out events by an administrator using the UI
• Forced log out events by an administrator using the CLI
• Change in user's access type, i.e., Named to Concurrent, or vice-versa, by an administrator
• Triggering of the workflow Execution history cleanup job
• Success or failure entry every time the storage space reclamation job is run along with the information about the date and time of the job run and table name on which the job is run.
  Success entry when the storage reclamation job is successfully completed: "Workflow Execution history cleanup job Completed".
  Failure entry on failure of the storage reclamation job: "Workflow Execution history cleanup job Failed". This occurs mainly due to insufficient space.
• Soft deletion of records.
• Restoring of records from Recycle Bin.
• Success or failure entry every time the data archival service is run.
• Setting of the archival option for a module.
• Change in configuration of rules
  

If you have a field, in a module, whose Singular Description attribute value contains a . or $ then the Audit Logs replace the . or $ with an _. For example, if you have a field SourceID whose singular description you have specified as Source.ID, then in this field will appear as Source_ID in Audit Logs.

You can purge Audit Logs using the Purge Logs button on the top-right of the Audit Log page. You will see the Purge Logs button only if you have Delete permissions on the Audit Log Activities module.

You can also use the Audit Log Purge API to purge audit logs on an automated as well as an on-demand basis. For more information, see the API Methods chapter in the "API Guide."

Viewing Audit Log

Use the Audit Log to view a chronological list of all the actions across all the modules of FortiSOAR. To view the Audit Log page, you must have access to the Audit Log Activities module. Click Settings > Audit Log to open the Audit Log page. The audit log also displays users' login success or failures and logout events. The login event includes all three supported login types, which are DB Login, LDAP Login, and SSO Login.

You can filter the audit logs to display the audit logs for a particular record type by selecting the record type (module) from the Record Type drop-down list. You can also filter audit logs on users, operations, and data range, apart from modules.

To filter audit logs on for a particular user, select the user from the Select User drop-down list.

To filter audit logs on for a particular operation, select the operation from the Select Operation drop-down list. You can choose from the operations such as, Comment, Create, Delete, Link, Login Failed, Snapshot Created, Trigger, Unlink, Update, etc.

You can also filter audit logs for a particular date range by selecting the From Date and To Date using the calendar icon.

You can also search for audit logs using free text search. Click the Search icon and enter a search criterion in the Search Logs field to search the audit logs.

The Audit Log displays the following historical information for each record:

• Title: Title of the record on which the action was performed.
  Note: In case of Approval playbooks the playbook audit log displays the Approval Description field, which represents the name of the approval record, in the Title field. In this case, the Title field will be displayed in the format Approval [Approval Description] Operation Performed. For example, Approval [Approval Test] Created.
• Record Type: Type (module) of the record on which the action was performed such as Alerts, Incidents, Configs, Indicators, etc.
• Operation: Operation that was performed.
• User: User who performed the operation such as the name of the user who performed the operation, or if the operation was performed by the system, playbooks, agents.
  Note: From version 7.0.2 onwards, operations performed by FortiSOAR such as the creation of schema for various modules (Alerts, Events, etc.) are added as a global audit log user filter named 'SYSTEM', and is applicable for audits generated from version 7.0.2 onwards. Audits done by the SYSTEM user prior to version 7.0.2 will not be visible when filtered by the SYSTEM user.
  
• Source: Source IP address where the operation that was performed.
• Transaction date: Date and time that the record was updated in the format DD/MM/YYYY HH:MM.

To view the details of an audit log entry, click the expand icon (>) in the audit entry row. Details in the audit log entry are present in the JSON format, and include the old data and updated (new) data for a record, in case of an update operation, and all attributes and their details, such as ID and type, for a record, in case of a create operation. You can copy the data using the Copy to Clipboard button.

You can perform the following operations on the Audit Log page, by clicking the More Options icon () to the right of the table header:

• Export All Columns As CSV: Use this option to export all the columns of the audit log to a .csv file.
• Export Visible Columns As CSV: Use this option to export visible columns of the audit log to a .csv file.
  Note: You can hide columns by deselecting a column from the list of columns present within the More Options menu. The hidden columns appear with a red cross.
  
• Export Visible Columns As PDF: Use this option to export visible columns of the audit log to a .pdf file.
• Reset Columns To Default: Use this option to reset the audit log fields to the default fields specified for the audit log.

You can view logs specific to a particular module, by clicking Settings > Modules (in the Application Editor section) and from the Select a module to edit or create new module drop-down list, select the module whose audit log you want to view, and then click the Audit Logs button.

You view the same details and perform the same actions as mentioned earlier on the Audit Logs Dialog. You can filter the audit logs for modules on users, operations, and date range. For example, you can filter logs which have an Create operation performed on a particular record type (module), as shown in the following image:

Similarly, you can also view logs specific to a particular picklist, go to Settings > Picklists (in the Application Editor section). From the Select a picklist or edit or create a new picklist drop-down list select the picklist whose audit log you want to view and click the Audit Logs button. You view the same details and perform the same actions as mentioned earlier on the Audit Logs Dialog. You can filter the audit logs for picklists on users, operations, and date range.

Audit logs also include the auditing of the following actions so that you can get comprehensive records of all activities across FortiSOAR :

• Schedule actions - Create, update and delete, start, and stop
• Rules actions - Create, update, delete, activate, and deactivate
• Dashboard/Report actions - Create, update, and delete
• Navigation actions - All
• License Update actions - All
• SVT Update actions - All
• Role - Modification (Create and Delete already gets audited)
• Team - Modification (including team hierarchy updates), User Link/Unlink (Create and Delete already gets audited)

From version 7.0.0 onwards, the following fields have been added to audit and system logs to provide more information about your FortiSOAR system and to help FortiAnalyzer (FAZ) integration:

• vd(enterprise|master|tenant) - The value of this field is "enterprise" for an enterprise setup, "master" for the master node in a multi-tenant setup, and "tenant" for the tenant node in a multi-tenant setup.
• level(emerg|alert|crit|err|warning|notice|info|debug) - The severity level of the event.
  Note that the following audit operations will be considered as 'warning' severity operations: Delete, Unlink, Terminate, Version Deleted, Uninstall, DeleteConfig, Deactivate and Replication Failed. All other audit operations are considered as 'info' severity.
  
• devid - FortiSOAR's SNO, i.e., the same serial number from the license file.
• datetime - Event timestamp in the 'epoch' format. This is applicable only for audit logs.
• type(AuditLog|System Log) - The Log type.
  Sample Audit log: 2021-02-19T06:17:24.958779+00:00 fsrprimary fortisoar-audit-log: CEF:0|Fortinet Inc|FortiSOAR|7.0.0|Alert Deleted|Alert Deleted|1|devid="FSRVMPTM20000061" vd="enterprise" level="warning" type="Audit Log" msg="Alert [1] Deleted " src="192.168.56.1" suid="3451141c-bac6-467c-8d72-85e0fab569ce" suser="CS Admin" end=1613634028029 playbookName="" playbookId="" eventTimeStr="18 Feb 2021 07:40:28.029"

Viewing User-Specific Audit Logs

Use the User-Specific Audit Logs to view the chronological list of all the actions across all the modules of FortiSOAR for a particular user. Users can view their own audit logs by clicking the User Profile icon and selecting the Edit Profile option and clicking the Audit Logs panel. Administrators who have a minimum of Read access on the Audit Log Activities module along with access to the People module, which allows them to access a user's profile, can view User Specific Audit Logs. The user-specific audit log also displays user's login success or failures and logout events. The login event includes all three supported login types, which are DB Login, LDAP Login, and SSO Login.

Use the same filtering and searching techniques mentioned in the Viewing Audit Log section. You can filter the user-specific audit logs on record types (modules) and date range.

The user-specific audit logs display the same information as the audit log, and you can also perform the same actions here as you can perform in case of audit logs. For more information, see the Viewing Audit Log section.

Viewing Audit Log in the detailed view of a record

Use the Audit Log tab, which is present in the detail view of a record, to view the graphical presentation of all the actions performed on that particular record. The Audit Log tab uses the Timeline widget to display the graphical representation of the details of the record. You cannot edit the Timeline widget. For more information about widgets, see the Using Template Widgets topic in the "User Guide."

You can toggle the view in the Audit Log tab to view the details in both the grid view and the timeline (graphical) view. Use the same filtering and searching techniques mentioned in the Viewing Audit Log section. You can filter the user-specific audit logs on record types and date range.

Click a record within a module to open the detail view of a record and then click the Audit Log tab to view the graphical representation, or grid view of the details of the record, as shown in the following image:

A timeline item mentions the action performed on the record, such as Created, Updated, Commented, Attached, or Linked, the name of the person who has made the update, and the date and time that the update was made.

In the timeline, you might see some records created by Playbook. This signifies that the record was created by a workflow entity, such as a Playbook or a Rule.

When you update any detail in a record, then you can click the refresh button in the timeline to view the updates in timeline immediately. To view the complete details of the updates made at a particular timeline item, click the arrow (>) present to the right of the item. The following image displays the details shown for a specific timeline item:

You can toggle between the expanded and collapsed view of the audit log tab, using the Full-screen Mode icon. To move to a full screen view of the audit log, click the Full-screen Mode icon, which opens the audit log in the full screen as shown in the following image:

To exit the full screen, press ESC.

You can toggle between the timeline view and grid view in the Audit Log tab. The grid view in the detailed view of a record appears as shown in the following image:

The grid view also displays the same information as the audit log, and you can also perform the same operations here as you can perform in case of audit logs. For more information, see the Viewing Audit Log section.

Purging Audit Logs

You can purge Audit Logs using the Purge Logs button on the top-right of the Audit Log page. Purging audit logs allows you to permanently delete old audit logs that you do not require and frees up space on your FortiSOAR instance. You can also schedule purging, on a global level, for both audit logs and executed playbook logs. For information on scheduling Audit Logs and Executed Playbook Logs, see Scheduling purging of audit logs and executed playbook logs.

To purge Audit Logs, you must be assigned a role that has a minimum of Read permission on the Security module and Delete permissions on the Audit Log Activies module.

To purge Audit Logs, click the Purge Logs button on the Audit Log page, which displays the Purge Audit Logs dialog:

In the Purge all logs before, field, select the time frame (using the calendar widget) before which you want to clear all the audit logs. For example, if you want to clear all audit logs before January 1st, 2019, 12:00 AM, then select this date and time using the calendar widget.

By default, logs of all events are purged. However, you can control the event types that will be chosen for purging. For example, if you do not want to purge events of type "Login Failure" and "Trigger", then you must clear the Login Failure and Trigger checkboxes, as shown in the following image:

To purge the logs, click the Purge Logs button, which displays a warning as shown in the following image:

Click the I Have Read the warning - Purge Logs to continue the purging process.

License Manager

FortiSOAR enforces licensing using the License Manager. The License Manager restricts the usage of FortiSOAR by specifying the following:

• The maximum number of active named users in FortiSOAR at any point in time.
• The type and edition of the license.
• The expiry date of the license.

For details of the FortiSOAR licensing process, including deploying your FortiSOAR license for the first time, see the Licensing FortiSOAR chapter in the "Deployment Guide."

Click Settings > License Manager to open the License Manager page as shown in the following image:

You can use the License Manager page to view your license details and to update your license. FortiSOAR displays a message about the expiration of your license 15 days prior to the date your license is going to expire. If you license type is Evaluation or Perpetual, then you must update your license within 15 days, if you want to keep using FortiSOAR. To update your license, click Update License and either drag-and-drop your updated license or click and browse to the location where your license file is located, then select the file and click Open. If your license type is Subscription, you must renew your subscription.

For more information on licensing and for details about the various parameters on the License Manager page, see the Licensing FortiSOAR chapter in the "Deployment Guide."

Notifications

FortiSOAR is built on the premise of humans being in the loop for effective orchestrated investigation; therefore, ensuring timely action-centric (or informational) notifications are generated becomes vital in achieving this goal. To achieve this goal, in release 7.2.0, FortiSOAR introduces a common framework for diverse notifications, such as email notifications, UI notifications from various services (like alerts/incidents/tasks assignments), Comments @mentions, workflow failures, etc. This common notification framework makes it possible for users to have complete control of the setup and consumption of notifications, i.e., how and when they want to consume notifications, and what notifications they want to consume.

From release 7.2.0 onwards, there is a single 'Notifications' page using which you can enable, disable, or edit the notifications settings and add, edit or deactivate notification channels.

To view the 'Notifications' page, you must be assigned Read permission on the Notifications Rules module and Update permission on the Application module. Similarly, to perform actions such as configuring delivery rules, or notification channels, you must be assigned appropriate CRUD permissions on the Notifications Rules module.

To view the Notifications page, click Settings > Notifications.

On the Notifications page, you will see the Delivery Rules, Notification Channels, and Notification Logs tabs:

• The Delivery Rules page contains default rules that are included by default in FortiSOAR and which have already been created for some common use cases, such as notifications to be generated when an approval request is created - 'Pending Approval Notification', or when comments that have @mentions are updated or added, or for playbook failures, etc. It also specifies the channel used for sending the notifications.
  Note: To edit an existing rule, you can click the row of the rule to open the edit <named of the rule> page, make the required changes, and then click Update.
  For example, if you want manual input notifications to be sent using the email channel in addition to the default In App notifications, click the Notify On Pending Manual Input rule to display the Edit Notify On Pending Manual Input dialog, then in the Select Channel page, from the Notification Channels drop-down list, select Email Notification and click Add Channel:
  
  Note: Ensure that you have added appropriate notification details to the Email channel before you add the Email channel for pending manual inputs. For details on how to set up a notification channel, see the Setting up Notifications Channels topic.
• The Notification Channels page lists the channels that can be used to send notifications. The default channels are In-App Notifications and Email Notifications.
• The Notification Logs page contains a list of notification failures with their respective error messages using which you can debug the notification failure. Once you have fixed the issues in the notification, you can select that particular log entry and click Retry Notification.

If you have upgraded to release 7.2.0 or later from a release prior to 7.2.0, then users will receive two emails for a single notification. This is because the upgraded FortiSOAR system would have both the new notification rules and the system playbooks that triggered notifications prior to 7.2.0. To resolve this issue, the earlier system playbooks that used to send the notifications emails must be deactivated and the notification rules must be customized to suit your requirements. Details for the same are included in the Post-Upgrade Tasks chapter in the "Upgrade Guide."

Adding Delivery Rules

You can add your own custom delivery rules based on which notifications will be created and delivered as follows:

1. Click Settings > Notifications > Delivery Rules.
2. On the Delivery Rules page, click Add Delivery Rule, to open the 'Create New Delivery Rule' wizard.
3. On the Rule Details screen, you can define the rules for generating the notifications:
   1. To create the rule in the 'Active' state, leave the Active toggle button as YES.
   2. In the Name field, add a name that describes the purpose of the rule. For example, if you want to generate a notification if the reputation of an indicator is updated to malicious, then add the name as Indicator > Notify Indicator Reputation Updated to Malicious
   3. Add the rule for generating notifications:
      When an Indicator is updated
      Then add the additional conditions for generating the notification. In our example, we want to generate a notification only if the reputation of the indicator is updated to 'Malicious' is added. Therefore, in the Condition section, choose the logical operator AND or OR and then add the condition as:
      Reputation Equals Malicious
      
      You can add additional conditions as per your requirement.
   4. Once you have completed adding the details for the rule, click Continue.
4. On the Select Channel screen using which users can consume the notifications.
   Note: You can choose only those channels that have been created. In-App Notifications and Email Notification are channels that are set up by default. For more information, see the Setting up Notifications Channels topic.
   1. From the Notification Channels drop-down list, select the channel using which you want to deliver the notifications. If you want to deliver notifications using the Notifications icon present on the top-right corner in FortiSOAR, select In-App Notifications and click Add Column. You can further configure the settings for this notification:
      1. To enable or disable this notification, you can toggle the Enabled button.
      2. In the Content field, add the content that you want to display as part of the notification. For example:
         A malicious indicator, {{vars.input.record.value}}, has been created!
      3. In the Ownership section, you can choose to assign this notification to a specific user or to make it public. In this example, we have chosen to make it public.
         
         Similarly, you can choose to deliver notifications from other notification channels, such as Email Notification.
   2. Once you have completed setting up the notification channels, click Continue.
5. On the Review Rule Details screen, review the details of the rule for generating the specific notification:
   
   Once you are satisfied, click the Create button.

You will observe that whenever a malicious indicator is added, a notification will be generated, that can be viewed by clicking the Notifications icon:

Setting up Notification Channels

Notification channels define the mechanism using which notifications are delivered to users. By default, the 'In-App Notifications' and 'Email Notification' (using the SMTP integration) channels are set up. Users cannot delete these default notification channels and they also cannot edit the In-App Notification channel.

You can set up other channels to deliver notifications using desktop applications, slack, mobile applications, etc. You could also edit the existing 'Email Notification' channel to use Exchange or any other email server to send email notifications.

To deliver notifications to users using notification channels, you first have to ensure that you have configured the integration (connector) that will be used for the channel. For example, to use Exchange as the 'Email Notification' channel (SMTP is pre-configured), ensure that you have configured the Exchange connector and its 'Health Check' displays 'Available'. 'In-App Notifications' do not require any configuration.

To set up a new channel for delivering notifications, for example, a Slack channel, do the following:

1. Ensure that you have installed and configured the Slack connector and its 'Health Check' displays 'Available'. Also, ensure that you have set up a channel in Slack for receiving the notifications.
   For information on connectors, see the Introduction to connectors chapter in the 'Connectors Guide.'
2. Click Settings > Notifications> Notification Channels.
3. On the Notification Channels page, click Add, to open the 'Create New Notification Channel' wizard.
4. In the 'Create New Notification Channel' wizard, click Let's Build a Channel.
   
5. On the Channel Details screen, specify the details of the notification channel:
   1. To create the notification channel in the 'Active' state, leave the Active toggle button as YES.
   2. In the Name field, add the name of the channel, for example, Slack Notifications.
   3. In the Channel Description field, add a brief description of the channel, for example, Channel for sending notifications using Slack.
      
      
   4. Once you have completed adding the details for the channel, click Continue.
6. On the Integrations screen, configure the connector using which you want to send notifications to the users:
   1. From the Choose Suitable Connector drop-down list, select Slack.
   2. In the Choose Configuration and Action section, configure the following:
      1. From the Choose Connector Configuration drop-down list, select the connector configuration that you want to use to send notifications and ensure that the 'Health Check' displays Available. For our example, select Default.
      2. From the Choose Action drop-down list, select the action that you want to perform using the Slack connector. For our example, select Send Message. The Send Message action will send the notifications to the specific channel that you have set up on your Slack Cloud.
   3. In the Default Value for Action Inputs section, enter the ID of the channel (or user) that you have created for receiving notifications from FortiSOAR, and the default message that you want to include for notifications.
      
   4. Once you have completed setting up the integration, click Continue.
7. On the Test Run screen, you can test your integration by providing sample inputs and clicking Trigger Test Notification.
   Clicking Trigger Test Notification sends a live notification to the Slack channel that you have configured for receiving notifications.
   To move to the next screen, click Continue.
8. On the Review Channel Details screen, review the details of the notification channel:
   Once you are satisfied, click the Save button.

If you disable any channel, you must ensure that you disable this channel in all the rules that use the disabled channel, else users continue to receive notifications from the disabled channel.

Working with Delivery Rules and Notification Channels

The default notification channel for emails is SMTP; however, you can choose to change this to Exchange or any other email service provider. If you set, for example, Exchange as the default notification channel, then all notifications such as workflow failures, creation and updates of alerts, incidents, etc, actions pending for some user actions, etc., will all be delivered using Exchange. In such a case you must do the following:

1. Configure the Exchange connector and its 'Health Check' displays 'Available'.
2. Navigate to Notifications > Notifications Channel and click the Email Notification row. In the Update Email Notification Channel wizard, edit the email notification channel to use the Exchange connector instead of the SMTP connector. The Update Email Notification Channel wizard is exactly like the Create New Notification Channel wizard, steps for which are described in the Setting Up Notifications Channels topic.

If however, you want to use SMTP as the default notification channel and use Exchange only for specific use cases, for example, to use Exchange in cases where you want to request decisions or other inputs from non-FortiSOAR users; then, or you want Approvals notifications sent using exchange, then you have to update the respective delivery rules, i.e., Notify On Pending External Manual Input, or Notify On Pending Approval Notification. For our example, we will use exchange for sending pending external manual input notifications:

1. Ensure that you have configured the Exchange connector and set up a new notification channel using the Exchange connector. For steps on setting up a notification channel, see Setting Up Notifications Channels.
2. Update the delivery rule to use Exchange instead of SMTP for delivering pending external manual input notifications:
   1. Navigate to Notifications > Delivery Rules and click the Pending External Manual Input Notification row.
   2. In the Edit Pending External Manual Input Notification wizard, leave the Rules Details screen unchanged and click Continue. On the Select Channel screen, remove Email Notification, which is the default SMTP notification channel, and add the notification channel that you have set up for Exchange. Next, you must specify the details that you want to send through the notifications:
      
      Once you have specified all the details, click Continue.
   3. On the Review Rule Details screen, review the details of the rule you have set up, and if satisfied click Update.
      This updates the Pending External Manual Input Notification rule to send pending external manual input notifications using Exchange.
      

Purging of notifications

FortiSOAR runs a system schedule to purge all read system notifications older than 30 days. By default, this schedule runs every day at midnight (00:00 hrs). The cron expression for this system schedule is present in the /opt/cyops-workflow/sealab/sealab/config.ini file as follows:
PURGE_NOTIFICATION_SCHEDULE: {'minute': '0', 'hour': '0', 'day_of_week': '*', 'day_of_month': '*', 'month_of_year': '*'}

You can update this cron expression if you want to change the default schedule timing window of 12 am, and then run the following command:
$ sudo -u nginx /opt/cyops-workflow/.env/bin/python /opt/cyops-workflow/sealab/manage.py default_schedules
Then restart the services using the following command:
systemctl restart celeryd celerybeatd fsr-workflow

It is highly recommended that you do not update the system schedule for purging notifications.

Similarly, the KEEP_SYSTEM_NOTIFICATION_DAYS parameter in the config.ini sets the default number of days that read system notifications are retained in the system, which by default is set to 30 days as follows:
KEEP_SYSTEM_NOTIFICATION_DAYS = 30
You can change this setting as per your requirements. After you have completed making changes to this setting, you must restart the default schedules using the following command:
$ sudo -u nginx /opt/cyops-workflow/.env/bin/python /opt/cyops-workflow/sealab/manage.py default_schedules
Next, you must restart the services using the following command:
systemctl restart celeryd celerybeatd fsr-workflow

Users with a minimum of Update permissions on the Security Module also use the FortiSOAR UI to purge notifications. To purge notifications, click the Notifications icon on the top-right corner of the FortiSOAR UI to display the Notifications Panel. Then click the Purge All icon to display the Purge Notifications dialog. Click Purge All Notifications to delete all notifications or click Purge All Read Notifications to delete all read notifications:

Data Archival

The volume of data ingested in SOAR platforms grows exponentially as SOCs across the globe automate most of their procedures using SOAR solutions. Over years of usage, as the volume of data grows, which can adversely affect the performance of a SOAR platform as follows:

• Database queries become slower and more and more resource-intensive.
• UI becomes very sluggish as more time is needed to fetch the required data.
• More disk space for storage on the primary system.

Historical data is not required for day-to-day investigation. However, it cannot be discarded completely as organizations need it for audit and compliance reviews, and also for occasional references.

To solve the mentioned issues and to retain historical data for the long term by preserving it in your data lake, FortiSOAR provides a way to archive data. The data archival solution in FortiSOAR provides the following advantages:

• Improves the overall performance of your FortiSOAR instance by helping to lessen the primary data volume.
• Ability to move historical data that is not accessed frequently to less expensive storage.
• Ability to configure timeframes for data to be kept at primary and for data to be archived.
• Ability to search the archive for certain specific records or record attributes.
• Ability to archive certain specific types of records. For example, critical and closed alerts and incidents.

If you are upgrading your FortiSOAR instance from a release prior to 7.2.0 to a 7.2.0 or later release, then ensure that your externalized PostgreSQL database does not contain a database with the name 'data archival', else there might be conflicts with the data archival feature.

The following modules cannot be archived:

• Agents
• Appliances
• Approvals
• People
• Routers
• Saved Reports
• Tenants

Methods of Setting Up Data Archival

• External Database (Recommended): Use an external database for data archival purposes.
• Internal Database: Use an internal database for data archival purposes; this can be used for testing purposes.
• Syslog Forwarding: You can also archive data to an external Syslog server. You can choose to enable Syslog forwarding in addition to archiving data on databases or can set it up as a sole data archival destination.
  Important: Data that you archive using only Syslog Forwarding cannot be searched using FortiSOAR.

You can use a combination of methods for archiving your data. For example, you can choose to archive data in an external Syslog server, in addition to storing that in an internal or external database. If you choose to archive data in both the external Syslog server and a database, then any record that is archived will be forwarded to the Syslog server and will also be stored as a row in the database. You can use such a combination if you want an archival strategy in which you want to forward records to an external Syslog server to keep data there for a longer timeframe say 20 years, but also keep a record in the database for a shorter timeframe say 2 years so that the recent historical records are searchable and for very old records you can go back to the Syslog server.

Setting up an External Database for Data Archival

To set up an external database for data archival, do the following:

1. Create the db_external_config.yml file at the following location /opt/cyops/configs/database/
   Use the following command to create the db_external_config.yml file:
   # cp /opt/cyops/configs/database/db_config.yml /opt/cyops/configs/database/db_external_config.yml
   Note: If you have already externalized your FortiSOAR databases, then a db_external_config.yml file will already be present.
   
2. Edit the db_external_config.yml file to add the details for the data_archival external database as follows:
   In the postgres_archival section:
   1. Set the pg_archival_external parameter to "true".
      This parameter determines whether or not the Postgres archival database needs to be externalized. If it is set to "true", then the Postgres archival database is externalized, and if set to "false" (default), then the Postgres archival database is not externalized.
   2. Update the value of the data archival host (pg_archival_host) and data archival port (pg_archival_port) (if needed) parameters.
   3. Add the encrypted password that you have set on your remote Data Archival server in the pg_archival_password parameter.
      You can encrypt your passwords by running the csadm db --encrypt command as a root user. For more information on csadm, see the FortiSOAR Admin CLI chapter.
3. On the externalized data archival database run the following commands:
   1. To ensure that the data archival server allows connections, open the firewall port:
      # firewall-cmd --add-service=postgresql --permanent
# firewall-cmd --reload
   2. To ensure that the pg_hba.conf file trusts the FortiSOAR server for incoming connections:
      Add the following entry to the file /var/lib/pgsql/12/data/pg_hba.conf file:
      host all all ip/subnetmask trust
      For example, if the ip/subnetmask of your externalized PostgreSQL database is xxx.xxx.xxx.xxx/xx then add the following to the pg_hba.conf file:
      host all all xxx.xxx.xxx.xxx/xx trust
   3. To ensure that the postgresql.conf file trusts the FortiSOAR server for incoming connections:
      Make the following changes to the /var/lib/pgsql/12/data/postgresql.conf file:
      listen_addresses = '*'
port = 5432
   4. Restart PostgreSQL using the following command:
      # systemctl restart postgresql-12
   5. Create a cyberpgsql user using the following commands:
      # psql -U postgres -c "CREATE USER cyberpgsql WITH SUPERUSER PASSWORD '<password>'";
4. SSH to your FortiSOAR VM and log in as a root user.
5. Check the connectivity between the FortiSOAR local instance and remote data archival database using the csadm db --check-connection command.
6. To externalize the data archival database, type the following command:
   # csadm db --archival-externalize
   Or run the following command to externalize all the FortiSOAR databases, including the data archival database:
   # csadm db --externalize
   Once you run the above command, you will be asked to provide the path in which you want to save your database backup file.
   Note: If you run the # csadm db --externalize option more than once (i.e., you are running the option again after the first time), then csadm will display a message such as:
   The databases already exist in postgresql, do you want to delete these databases (y/n): If you want to externalize your PostgreSQL database again you must type y.
7. After you have completed externalizing your PostgreSQL database, you should restart your schedules.
   

You can choose to externalize both the main PostgreSQL database and your archival database to the same external database or a different external database. However, if you have externalized your main PostgreSQL database, then you must externalize your archival database, i.e., the external database for data archival cannot be set to 'localhost'. For more information, see the Externalization of your FortiSOAR PostgreSQL database chapter.

Configuring various settings for Data Archival

Important: To configure various settings for data archival, such as archival frequency, rules for archival, etc., you must have Update permission on the Application module and Create, Read, Update, and Delete permissions on the Data Archival module.

1. Log onto FortiSOAR and in System click the Data Archival option.
2. On the Data Archival page, in the Setting tab, in the Archival Destination section, you can view the details of the database that you have set up for data archival. Details include the host, port, and name of the database and the username that you have set up for the database. In the case of an internal database, details will appear as shown in the following image:
   
   If you have set up an external database for data archival, its details are shown in the Database section. For information on how to set up an external database for data archival, see the Setting up an External Database for Data Archival topic.
   If you want to archive data to an external Syslog server, either in addition to the external or internal database or as a sole archival destination, then to update the Syslog configurations, you must have Security Update permissions and you must ensure that the destination Syslog server IP is reachable from the FortiSOAR instance and should accept TCP/UDP data in port that is set up for communication.
   To configure Syslog, click Setup in Syslog Forwarding and enter the following details in the Archival Syslog Setting dialog:
   1. In the Server field, enter the IP or hostname of the Syslog server that you want to set up for data archival.
   2. From the Protocol drop-down list, choose UDP or TCP as the protocol to be used to communicate with the Syslog server.
   3. In the Port field, enter the port number to be used to communicate with the Syslog server.
   4. Click Save to save the Syslog details.
      
3. In the Archival Frequency section, set up the archival schedule, which is a system schedule that runs periodically as per the timeframe you have configured and archives data:
   1. Click View beside Schedule Status, which is set to Inactive, to open the Schedule Details dialog.
   2. Click Start Schedule to begin the schedule immediately, or you can also set the Start Time and End Time for the schedule.
   3. In the Schedule Frequency section, choose the frequency of running this schedule.
      For example, to run the data archival daily at 6:00 am, click Daily and then in the hour field enter 6 and in the minute field enter 0.
   4. From the Timezone drop-down list, select the timezone in which you want the schedule to run. By default, this is set as UTC.
   5. If you want to ensure that you do not rerun the workflow, if previous scheduled instance is yet running, then click Limit execution to one active instance at a time.
   6. (Optional) From the Start Time field, select the date and time from when the schedule should start running.
   7. (Optional) From the End Time field, select the date and time till when the schedule should run, i.e., the date and time to stop the schedule.
      For more details on schedules, see the Schedules chapter in the "User Guide."
   8. Click Save to save the schedule.
      Once the schedule is saved, you can see that the Schedule Status has changed to Active:
      
4. In the Archival Rules section, you can choose the modules that you want to archive as well as set up rules for archival:
   1. From the Choose Module To Archive drop-down list, select the module whose records you want to archive and click Add Module.
      For example, select Alerts and click Add Module.
   2. In the Archive all data modified earlier than field, enter the number of months earlier than which you want to archive the records. For example, if you enter 12 in this field, then it means that all records, which were modified earlier than 12 months will be archived.
      Note: The value that you mention in this field must be in multiples of 3.
   3. From the Retain archived data for drop-down list, choose the number of years the archived data should be retained in the specified archival destination.
   4. In the Additional Criteria section, add conditions that refine the selection of data to be archived.
      For example, if you want to archive closed alerts only, then click Add Condition and from the Select a field drop-down list, select Status, from the Operator drop-down list, select Equals, and then select Closed.
      
   5. Click Save and Start Archival to save the settings and start data archival for the specified module. Settings are saved in the Draft mode if you do not click Save and Start Archival.
      In the Archived Modules section, you can Pause and Resume a particular archival or Pause and Resume all ongoing archivals.
      You can also edit the settings for any archival, by clicking Edit Settings.

A record gets archived along with their entire relationships, but the actual relationship records get archived according to their own schedule. For example, if an alert has an indicator as its related record, then the alert is archived along with its indicator relationship, i.e., the indicator's value and reputation; however, the actual indicator record will be archived according to its own schedule. Also, unique Constraints will not be considered across the primary and archived tables. For example, Alerts have unique constraints defined on “source Id” fields, once an alert is moved to the archival, new alerts with the same “source Id” can be created. Additionally, there are no constraints on data residing in an archival.

Viewing and Searching Archived Records

To view archived records, you must have permissions on the module to view the archived records, for example, to view archived alert records, you must have permissions on the Alerts module. Team ownership and user ownership of the records as at the time of archival is carried forward and honored while rendering and searching across archived data.

To view or search archived records, click the Archival Search tab on the Data Archival page:

You can search for archived records based on the module of the record, and the ID or Display Name of the record. Additionally, you can filter archived records based on their modified date and time. For example, to filter archived records from the 'Alerts' module whose modified date is between '1st January 2021' to '31st March 2021', select Alerts from the Select Module to Search drop-down list, and in the Modified Date To calendar, select 1st January 2021 and similarly, from the From calendar select 31st March 2021:

To view the details of a record, click that record's row:

The record detail view displays the primary data of the record and it contains only those fields whose values are not null or which are lookup fields. The Correlation Data section displays the relationship data of the record in their respective tabs. The archived record also contains an integrity check (required for auditing), which checks that the archived record has not been tampered with or modified (in the database itself). The Integrity Check Passed check indicates that the signature of the record's current state matches the original value, and there has been no tampering of the archived record.

Blocking specific HTML tags and attributes

Rich Text fields can be used to accept and render the HTML input making it possible for users to inject HTML code into FortiSOAR to insert content such as a link or an image. These can be used to trick a user into taking harmful actions or into believing misinformation. To avoid this, administrators can choose from the following options:

• Use the Text Area field instead of the Rich Text field.
• If you need to use the Rich Text Field, then you can choose between the following options:
  • Configure an iFrame or an iFrame sandbox (using the iFrame Widget) if you want to render HTML content
  • Block specific HTML tags and attributes if you want to add, edit, and render the HTML content with restrictions on a few tags or attributes.
    Note: By default, safe HTML tags and attributes are allowed.

To add the configuration for allowing or disallowing specific HTML tags and attributes, do the following:

1. SSH to your FortiSOAR VM and log in as a root user.
2. Open the config.json file using vi /opt/cyops-ui/vendor/config.json.
3. Update the config.json as per your requirements and then save the file.
   Note: The tags and attributes that you restrict in the config.json will apply to all instances of the Rich Text Field throughout your FortiSOAR instance.
   

Example of the config.json file:

{
    "markdown": {
        "allowedHTMLTagsAndAttrs": {
            "HTMLTags": ["button"],
            "HTMLAttrs": "",
            "AllowSVGContent": true
        },
        "blockHTMLTagsAndAttrs": {
            "HTMLTags": ["img","style”],
            "HTMLAttrs": [“style”]
        }
    },
    "pdfmake": {
        "font": {
            "normal": "Roboto-Regular.ttf",
            "bold": "Roboto-Medium.ttf",
            "italics": "Roboto-Italic.ttf",
            "bolditalics": "Roboto-MediumItalic.ttf"
        }
    }
}