Fortinet black logo

Version:

Version:

Version:

Version:


Table of Contents

Administration Guide

Download PDF
Copy Link

Application Editor

Use the Application Editor to configure data models contained in modules, to export and import configurations, visually display the nodes related to a particular record, customize your Picklist values, and the left navigation bar.

The Application Editor has following tools for this purpose:

  • Module Editor - for editing the data models in a module
  • Picklist Editor - for changing picklist values and color associations
  • Navigation Editor - for modifying the navigation links and hierarchy in the left navigation bar
  • Correlation Settings - for configure the display of the Visual Correlation widget.
  • Recommendation Engine - for predicting and assigning field values based on Artificial Intelligence/Machine Learning (AI/ML)
  • Configuration Manager - for exporting and importing configurations across environments
Note

To edit these settings, users must be assigned a role that has at a minimum of 'Read' and 'Update' permissions on the "Application" module.
If you want a user to be able to add modules also, then those users must be assigned a role that has at a minimum of 'Read,' 'Create,' and 'Update' permissions on the "Application" module.
To delete picklists or navigation items, you must have 'Delete' permissions on the "Application" module.
These privileges must be granted carefully as unintended application modification could result in data loss.

Module Editor

Use the Module Editor to add new modules and to add new fields and edit existing fields within a module. You can open the module editor by clicking Settings and in the Application Editor section, click Modules. This displays the Modules page.

Module Editor Interface

Important: Some fields in some modules are system fields and only FortiSOAR can create system fields. Changing the properties of the system fields could lead to issues with the working of FortiSOAR. Therefore, you cannot modify any properties of these fields, and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module as shown in the following image:

Field Editor tab- Read-only fields

Creating a New Module

To create a new module, click Settings > Modules. This displays the Modules page. Use the +Create new module option that appears at the top of the editor to define the properties of the module. By default, when choosing the Module Editor, the ability to define the new modules is available.

Adding a new Module

Bear in mind there are requirements to realize the addition of the new module, notwithstanding the need to allow for the interface to recognize this module.

From version 7.0.2 onwards, the process of creating a new module has been simplified so that users needs to provide only the Module Name while creating the module. Legacy fields such as table name, which could cause issues if incorrect inputs were provided are auto-generated. Simplification of module creation enhances user experience and also eliminates errors that occur due to incorrect inputs. In addition to this in case of the many to many relation field type, fields are by default added with same module name to the other side of related module, which simplifies the process of creating many to many relation fields. Also, now users only need to select the Related Module and provide the value in the Field Title field to create relation fields.

To add a module, do the following:

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.
  2. On the Summary tab configure the following fields for defining a module using the Module Editor.
    Note: To add any field to the Summary view, you must ensure that you have already added the field using the Field Editor. See the Modifying an existing module section for information on how to add and edit fields.
    1. Module Name: The name of the module itself, when it is in the singular context (individual record). For example, an Incident refers to an individual record in a module, whereas the module is Incidents.
      Once add the name of the module in the Singular context, the name of the module in the Plural context gets automatically populated.
      Note: The module 'Type' is also automatically populated based on the name you specify in the Singular field. Type is used to identify the module in the API.
    2. Display Template: This field uses an Angular Template expression to display a record appropriately. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ field_name_api }}.
      Important: Ensure that you add the fields that you specify in Display Template in the module that you are creating or updating. For example, if you have added {{ name }} in Display Template, then ensure that you have added Name as a field in the module, its Field Title (Field API Key)attribute will be set as name.
      Display Template
      You can also add an attribute of a picklist as part of the Display Template. See the following Display Template section for more details.
    3. Record Uniqueness: This section allows you to choose one or more published fields from the existing module that would be used to define a unique condition. This ensures that only unique records will be created in FortiSOAR and any record that matches the unique field or the combination of unique fields would not be created.
      For example, Type + Value is a unique combination in the Indicators module as shown in the following image:
      Application Editor: Summary Page - Record Uniqueness section
      This will ensure that indicator records will be created with unique "Type and Values" values.
      If you want to add any other field to for part of the unique combination of fields, then from the Record Uniqueness section, select that field from the Select a Field drop-down list, and then click Add Field. Similarly, if you want to remove any field from the unique combination, you need to click the red X on that field.
    4. Default Sort: Click Add Field to add a field based on which the list of records in the module will be sorted, either in the ascending or descending order. For example, indicators will be sorted based on when they were created, if you add Created On in the Default Sort section, as shown in the following image:
      Module Editor - Existing Incident module
    5. Team Ownable: Records that are ownable can be owned by a Team or Teams. An example of a module that you should make ownable is Incidents. If you do not select this option, then the records are not ownable and are publicly available and visible to any system user, without consideration of the user's team. An example of a module that you can make not ownable is Addresses.
      Note: Records that do not have any owners are visible to "All." If you change a module that was not ownable to ownable, then the records created before you have changed the ownership are visible to "All". However, until owners (teams) are assigned to the record, the record is read-only, i.e., fields in that record cannot be edited until a team is assigned to the record. Also, users' who are editing the same record (with no owners) must assign their team to the records to ensure that the records continue to be visible to those users and/or teams.
    6. User Ownable: Records that are user ownable can be owned by Users or Appliances. An example of a module whose records you should make user ownable is Alerts. If you do not select this option, then the records within this module will be visible to all users.
    7. Trackable: Selecting this option ensures that FortiSOAR tracks the date that the record was created, user who has created the record, date that the record was modified, and user who has modified the record on all records in the module.
      Important: Once a module has been created, you must not modify the Type and Table Name fields. You can edit the Singular and Plural names whenever required. However, note that the Singular name plus an s is used for API endpoint generation during module creation. Changing the Singular name could disrupt existing API calls to the endpoint.
    8. Indexable: Selecting this option ensures that this module has fields that can be indexed.
    9. Taggable: Selecting this option ensures that the selected module is taggable, i.e., you can enter tags to records in this module making it easier to search and filter records in the module.
    10. Enable Recycle Bin: Selecting this option enable soft deletion of selected module's records, i.e., records that are deleted from this module move to the recycle bin from where they can be restored, if needed. For more information on recycle bin, see the Recycle Bin chapter.
      Note: You cannot select the Enable Recycle Bin checkbox for system modules, i.e., for the 'People', 'Appliances', 'Agents', 'Approvals', 'Tenants', 'Routers', 'Comments', and 'Saved Reports' modules. Therefore, recycle bin for these modules cannot be configured and records of these modules are always permanently deleted.
    11. Queueable: Selecting this option ensures that this module is displayed as an option for auto-assignment while creating or configuring queues, i.e., records of this module can be auto-assigned using queues. For more information, see the Queue and Shift Management chapter in the "User Guide."
    12. Data Replication: (Only applicable to multi-tenant setups): Selecting this option enables replication of data for the selected module across peers' setups.
  3. On the Fields Editor tab, add the required fields to the module and click Save. See the Modifying an existing module section for information on how to add and edit fields.
  4. On the Summary tab, click Save to save the changes to save the changes to the module and publish the module to reflect the changes in the system. For information on the Save operation, see the Saving your changes section. For information on publishing, see the Publishing Modules section.
    To clear any changes made in the interface since the last Save event, click Revert.

Modifying an existing module

To modify an existing module, do the following:

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.
  2. To edit an existing module, from the Select a module to edit or create new module drop-down list, select the module.
    For example, select Alerts.
    Module Editor Interface
  3. To add fields to the module, or to edit any of the fields belonging to the module, add or update the fields on the Fields Editor tab on the Modules page.
    Editing Field Properties
    Some fields in some modules are system fields and changing properties of these fields could lead to issues with the working of FortiSOAR. Therefore, you cannot modify any properties of these fields and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module.
    From version 7.0.2 onwards, one-time edits are allowed for read-only fields, in the following cases:
    • If the value of the field had not been set, i.e., it is 'null' or 'blank'
    • If the field name is "tenant", and the field value is "self"
    One-time edits of read-only fields is required since there are scenarios where the value of the fields is not known at the time of record creation. An example of this is that at the time of record (alert) creation, the tenant to be mapped to the alert is not uniquely identifiable. Only after extraction and enrichment of the alert can the tenant be correctly determined. Therefore, now it is possible to change the tenant attribute of a record one time, if the current value is pointing to the local tenant ("Self").
    1. To add fields, on the Modules page, click the Fields Editor tab and click the Add (+) icon beside Fields.
      Note: The Fields Editor pane displays the list of fields that have been defined for the module. You can filter the fields by typing the search term in the Filter Fields textbox:
      Filtering Fields in the Fields Editor
    2. Define the following properties for the newly added field:
      • Field Type: The type of field; it specifies the type of form used to render this attribute. Examples of field types are text, file field, checkbox, integer, decimal, date/time, picklist, and relationship fields.
        It is recommended that when you create a field of type Integer, then you should set its default value as "zero".
        Use the JSON field type for fields such as, Source Data, which commonly store data in the JSON format to allow playbooks to get to the JSON data directly, without having to use a JSON parse step. You can also define the height of the JSON field in pixels by editing your record template.
        Based on the Field Type that you select, you can see an additional field. For example, if you select the field type as Picklist, a Picklist drop-down list will appear, and you must select the picklist associated with the field or click Create new picklist to add a new picklist. Use the Configure Picklist Option Visibility checkbox to filter a picklist field based on specified criteria. Once you check this checkbox, the picklist items are displayed and you can choose whether the item should be Visible, Disabled, Hidden, Conditionally Visible, or Conditionally Enabled. If you choose Conditionally Visible or Conditionally Enabled, you can then define the criterion when this item should be visible. An example would be displaying the Minimal option, in case of the Severity picklist, only if the type of alert is Other / Unknown:
        Configure Picklist Option Visibility
        FortiSOAR also supports a special type of picklist, called "Multiselect Picklist". You can use the multiselect picklist for fields that can contain more than one value. For example, you can have an alert be assigned more than one "Type", i.e., an alert can be of type Brute Force Alert and Malware. In such a case you can assign Multiselect Picklist as the Field Type for the "Type" field. You can then select an existing picklist from the picklist drop-down list, for example AlertType, or click Create new picklist to create a new picklist. You can also click Modify picklist to modify the existing picklist, by adding or removing picklist items or changing the properties of the picklist items.
        Field Type - Multiselect Picklist
        If you select Lookup (One to Many or One to One), Many to One, or Many to Many, a Related Model drop-down list will appear, and you must select the related module, and provide the Field Title before you publish the module.Also, in case of the Many to Many relation field type, fields are by default added with same module name to the other side of related module.
        Notes with respect to Relationship fields:
        • If you have added a Many to One relationship field on a module, then it is recommended that you set up a Lookup relation field on the related module for the modules to work as expected.
        • In the case of Lookup (One to Many or One to One) fields that have People as a related module contain the Filter Setting section. If you select the Only show users with record ownership checkbox in the Filter Settings section, then the list of users displayed in the lookup on the UI is restricted to include only those users who have record ownership. Further, you can also limit the list of users displayed in the lookup based on permissions given to the user on the module using the Limit ownership users to ones with module access to option. In the Limit ownership users to ones with module access to option, you can choose to display users who have Read access or Update (Read + Update) access.
          Filter Settings section
          Example: In the Alerts module, we have an Assigned To field, which is of type Lookup (One to Many or One to One) , with People as the related module. In this case by default, all users will be displayed in the Assigned To lookup, when you open an alert record. However, this could include users who belong to other teams, and who, therefore, would not have access to the record, even if you assign that record to that user.
          Therefore, to restrict the users to only those users who have access to the record, you can select the Only show users with record ownership checkbox. You can further restrict users displayed in the Assigned To lookup based on the module access. For example, if you want to display only those users who can update the record, in the Limit ownership users to ones with module access to field, select the Update checkbox (once you select the Update checkbox, the Read checkbox is automatically checked).
          You can drag and drop files in the "File Field" type field. An example of a "File Field" is "Email"; therefore, if you have an Email field in your record, then you can drag and drop an email to attach it to the record as shown in the following image:
          Example of an "File Field": Email
      • Sub Type: The "Sub Type" field can be used along with the Text and DateTime (from release 7.2.0 onwards) type fields.
        When you select DateTime in the Field Type, then the Sub Type drop-down list is displayed, from which you can select either Date Field or Date/Time Field as the sub types. Select the sub type as Date for fields that do not require the time component, and only require the date to be displayed. For Date fields, the time is considered as 12 A.M.
        Note: From release 7.2.0 onwards, DateTime fields, such as 'Created On', 'Modified On', etc. are stored with milliseconds precision (earlier it was seconds). If you have upgraded to 7.2.0, and users add new values to any existing DateTime fields, then those are stored with milliseconds precision; however, values in the DateTime fields that were present before the upgrade would yet be present in the old format, i.e., stored with the seconds precision.
        When you select Text in the Field Type, then the Sub-Type drop-down list is displayed, from which you can select the sub-types such as, Text Field, Rich Text (Markdown), Rich Text (HTML), Text Area, IPv4, IPv6, Domain, URL, or Filehash. The sub-type field enforces the format of data that the user can enter in that field. For example, in a Rich Text (HTML) or Rich Text (Markdown) fields, you can use formatting options or you can use the IP address and domain field types to lookup threat intelligence tools and whois info. You can also add images in the richtext fields (or in the Richtext Content widget); however, in case of .svg files, the Chrome browser does not restrict expansion of XML entities inside SVGs, which can rendering of image tag with any link in the href attribute that could case a client-side denial of service. Therefore, administrators can choose to not load SVG files enabled in HTML or Markdown Editors by updating the /opt/cyops-ui/vendor/config.json file using SSH. In the config.json file, update the value of the AllowSVGContent parameter to 'false'. In such a case the SVG will render as "<\\img src="https:\/\/link.svg">" in a richtext field, such as the 'Description' or the 'Comment' field.
        Note: For all modules, the default rich text editor is set to "Markdown", i.e., the Rich Text (Markdown) is selected for rich text fields. You can change the editor from markdown to HTML by selecting the appropriate sub-type for a field and then publish the module for the changes to reflect.
      • Field Title: A short descriptive name describing the item.
        TheField API Key is automatically created based on the value of Field Title field. The field can be alphanumeric and starts with a lower-case alphabet and does not contain any spaces, underscores or any special characters. Note that the value of this field does not get changed once the field has been created and the module has been published. This is because there is no migration path from the old name to the new name, so you risk data loss if this value is changed. Therefore even if you change the Field Title value the value of the Field API Key will not be changed.
        Note: If you have a field, in a module, whose Field Title (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.
      • Editable: Selecting this option allows you to modify the field after the creation of a module record. If this option is not selected, then you cannot modify the initial value after the record is created.
      • Delete Associations With Parent: Selecting this option cascades the deletion of a parent record to all the associated records for the Many to One relation type fields. For example, Events and Alerts have a Many to One relationship, i.e., one alert could have many associated events. If you select this option, then if an alert is deleted all its associated events also get deleted. Another example would be the case where one alert has multiple comments, and selecting this option cascade deletes the comments that are associated with a deleted alert.
        Warning: Select this option with caution since RBAC is Not applied for child records. For example, if you have Delete permissions on the Alerts module but not on the Events module, and you have selected this option, then deleting an alert with associated events, leads to the associated events getting deleted, irrespective of the permissions on the Events modules.
      • Searchable: Selecting this option makes this field searchable in the grid view.
      • Default Grid Column: Selecting this option makes the field appear as a column by default in the grid view. The order of the grid columns is defined by order of the fields in the Field Editor list. For information about grids, see the Dashboards, Templates, and Widgets section in the "User Guide."
      • Enable for recommendation: Selecting this option enables this field to accept values generated from the recommendation engine. Once you select this option, then an 'Auto populate' checkbox will appear beside this field while configuring data ingestion and also while creating or updating records using playbooks. This option appears for fields of type 'Picklist' and 'Lookup'.
      • Encrypted: Selecting this option enables encrypting of field values before storing in the database for enhanced security. FortiSOAR UI will continue to display the non-encrypted values. Currently, Text Fields, Email Fields, Rich Text Area and Text Area fields can be encrypted. FortiSOAR uses AES-256 encryption to encrypt and store the values in the database.
        Important: Once you enable encryption you cannot search the field values in FortiSOAR UI. Filters also will not work on encrypted fields. You also cannot use the upsert functionality for fields that are encrypted.
      • Required: Specifies whether the field is a required field.
        The options are: Not required, Required, or Required (by condition).
        Once you select Required (by condition), FortiSOAR displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR also supports advanced date operations and nested conditions for the Required (by condition) fields i.e., the Add Condition Group link is now available for these fields.
        Important: Do not choose the Visibility = Hidden option for Required (by condition) fields.
      • Visibility: Specifies whether the field is visible or not.
        The options are: Hidden, Visible and Visible (by condition).
        If you select the Hidden option, then the field is only accessible at the API level and not shown in the UI.
        If you select the Visible option, then the field is displayed on the UI. If you select the Visible (by condition) option, then the field is displayed on the UI only if the specific conditions are met.
        Once you select Visible (by condition), FortiSOAR displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR also supports advanced date operations nested conditions for the Visible (by condition) fields i.e., the Add Condition Group link is now available for these fields:
        Visible By Condition - Nested Conditions
      • Default Value: Specifies the default value of this field. Once you specify a value in this field, then this value will be displayed, by default when you add a record in the selected module.
        For example, if you want the status of a newly created alert to be set to Open, by default, then select the Status field and from the Default Value drop-down list, select Open as shown in the following image:
        Default Value option
        Once you set the default value, then whenever you add a new record in the Alerts module (in our example), then by default Open will be displayed in the Status field.
        In the Default Value field for the Date/Time field type you can specify either a Static date/time or a Custom date/time. If you select Static, click the Select Date icon to display the Calendar and select the required date/time. If you select Custom, then you can specify a date/time relative to the current date/time such as 1 hour from now, or 3 hours ago.
        Enhanced Default Value field for Date/Time field
        Note: In case you have upgraded to version 5.0.0 or later, then you will have to reselect your datetime default values, since the new datetime format is not backward compatible. You will be able to see the older applied datetime default value in the FortiSOAR fields. However, if you want to edit the default field, then you will have to specify the datetime again in the Default Value field.
      • Tooltip: Brief definitions that you can optionally add to fields. This definition is displayed when you click the information (i) icon of the field that has tooltip information added while creating, updating, or viewing records.
      • Length Constraints: In case of a Text field with sub-type set as Text Field or Text Area, you can specify length constraints by clicking the Add minimum/maximum range checkbox, if you want to override the default field length constraints by providing a minimum-maximum range for a field. Once you select the Add minimum/maximum range checkbox, you can specify the minimum character length for the field in the Minimum field and the maximum character length for the field in the Maximum field. You can enter any number from 0 to the maximum character length that is applicable for that field in the database. FortiSOAR will display a validation message if the maximum character length for the field is exceeded, or if the minimum character length for the field is not met.
      • Bulk Edit: Selecting the Allow Bulk Edit option to allow bulk edit operations on the selected field.
        For example, if you have selected the Severity field, in the Alerts module, and have clicked Allow Bulk Edit, this means the users can select multiple records in the grid view of the Alerts module and change the severity of those records to a particular severity level.
        You must enter the following details for the button that you want to use for the bulk edit operation:
        Button Text: In the Button Text field, type the name of the label that will be displayed on the bulk action button. For example, type Change Type.
        Button Icon: From the Button Icon drop-down list, select the icon that will be displayed on the bulk action button. If you do not want an icon to be displayed, select None.
        Button Classes: From the Button Classes drop-down list, select from the Default, Primary, Danger, or Warning styles.
        Allow Bulk Edit option
        Once you save the changes and publish the module, a Change Severity button is added to the Alerts module in the action bar. For more information on how to use the bulk action button, see the Working with Modules - Alerts & Incidents chapter in the "User Guide". You can add the bulk edit action button for any other fields, such as Status, Assigned To, and Type.
    3. Click Apply to add the field or click Revert to clear any changes made to the field since the last Save event or click Remove to remove the field.
      For information on the save and revert operations, see the Saving your changes section.
  4. You can also define the order of the default grid columns, which is defined by the order of the fields in the Fields Editor list. Fields are listed in the Fields column and you can drag-and-drop the fields to sequence the fields. You can also filter fields using the Filter Fields box.
    Defining the sequence of fields
  5. Click Save to save the changes to the module or click Revert > Revert to last saved to clear any changes made in the interface since the last Save event or click Revert > Revert to last published to clear any changes made since the last Publish event. For fields, you can revert only to the last published instance.
    For information on the save and revert operations, see the Saving your changes section.

Once you have completed making modifications to the module, you must publish the modules to reflect the changes in the system. This takes the system down for up to a few minutes while the changes are made. See the Publishing Modules section for more information.

Note

The Module Editor changes the relational database schema, therefore for changes to go live in the environment, you must perform a Publish to the database. This temporarily takes the application offline while the database operations are being performed. All users in the application must save their work prior to this occurring before this occurs or you risk data loss.

Display Template

A module's Display Template refers to one or more fields in the data model itself that is used to display a record in the general interface. Certain widgets, or visualizations in the interface, use the Display Template to identify records to the user. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ <*name of the module's field*>_name}}. If multiple fields are part of the display template, then you can specify multiple fields as {{field_name1,field_name2,…}}.

Note

If you were to use just the name of the module itself, such as Incidents, every Incident record in the interface would include a label named Incident. So, users see the Incident label with every record, which is not helpful. Therefore, we use Templates with a language to describe how to label your modules.

You can also include an attribute, such as itemValue, of a picklist field in the Display Template, add the following jinja: {{picklistFieldName.itemValue}} . For example if you want to include the status of the alert in the Display Template, then the picklist to be used would be AlertStatus, and the picklist field name would be status:

Example of adding jinja in Display template for picklists

Therefore you require to add the following jinja: {{status.itemValue}} in the Display Template.

Example

We have taken the Asset module as an example. Assets represent computing resources, typically on the network. Assets generally have a hostname, IP Address, or MAC Address. We are using the hostname as an example.

To create a Display Template for the Assets module with the hostname, you must ensure that you have already added the hostname field using the Field Editor. Once the hostname is added as a field in the Assets module, use the following expression in the Display Template field:

{{ hostname }}

The double curly braces, {{ }}, is used to identify a variable, specifically a field name. In our case, we are calling the hostname field. Any expression in the Display Template field that uses a field from the module data fields must use the double curly braces surrounding the field name. When the record is displayed, the hostname of each asset is used in the interface, so users know the asset they are selecting. For example, a user can know that they are selecting an HR Server.

Assets have a unique situation. They might only have one of those pieces of identifiable information depending on what is known about a resource. A laptop on a DHCP network might have only a MAC address. If we set the Asset Display Template to always be a hostname, in many cases the asset might have a blank Display Template in the interface. For these situations, the Angular Template expression allows you the flexibility to modify the format of the Display Template in a way that can account for variation. Taking the asset example, asset information is used to help users identify the asset when in the interface. Because using only a single asset field could potentially lead to a lot of blank Display Templates, we use multiple fields such as hostname, IP address and Mac address:

{{ hostname }} {{ ip }} {{ mac }}

This Display Template expression instructs the system to use all three fields based on their field names. If a field is not present, it displays as blank. In some cases, depending on what is known about the asset, the Display Template will include all three pieces of information, in others just one.

You can further extend this to display static information that identifies the parts of the Display Template. The following example includes the static text of Hostname:IP: and MAC: in every Display Template. This might be redundant but is an option.

Hostname:{{ hostname }} IP:{{ ip }} MAC:{{ mac }}

We recommend that to keep things simple, most of the time you would want to use the following expression for a Display Template, assuming you always create a name field for a module:

{{ name }}

This ensures that the Display Template points to whatever is in the name field on any module record. If you create name as a required field, then it will always be populated.

Saving your changes

Whenever you make any changes to a module or a field, you must stage those changes by saving. At the top-right of the Module Editor is the Save button, which applies any changes made to the staged data. To update the database and make your changes to go live, you must Publish the updated modules.

The Revert button clears any changes made in the interface since the last Save event. If you go into a module and realize that you have edited the wrong field, use Revert to clear the changes. However, once you press Save, you require to undo the changes manually.

Viewing your changes

Editing any of the fields of a module does not mean those fields are accessible immediately within the UI or the API. The fields must be first represented in the database. The templates included might automatically discover these fields, or these fields might need to be added manually to the template to specify their location within the interface. However, you can set the grid defaults within the attribute data for the model itself.

To update the database and make your changes to go live, you must Publish the updated modules.

Publishing modules

Whenever you change a field or a module and click Save, the change is staged but is not yet live in the system. You must perform a Publish to ensure that the changes are made in the system.

You initiate a publish action by clicking the Publish All Modules button at the top-right of the Module Editor page. Publishing pushes the changes that you have made to fields and modules to the database. Up until the Publish point, all changes to the data model in the Module Editor are saved as metadata, which is information that describes the structure of other information.

A Publish is the point at which the changes are truly irreversible, meaning that an unintended field deletion could cause irretrievable data loss. Use Publish carefully and verify changes before Publishing to avoid any problems.

Caution

"Publishing is a sensitive operation"
We recommend that you send a prior notification to all users of a publish since while the publish is in progress users are unable to work. We also recommend reviewing each staged change to ensure that only the desired changes are going to take effect.

If there is any error during the publish operation, FortiSOAR displays a meaningful error message at the top of the module editor, so that it becomes easier for you to resolve issues.

Note

If you have not selected an appropriate field from the Related Model drop-down list, for a Many to One, or a Many to Many field, then the publish operation will display an error.

Picklist Editor

Use the Picklist Editor to change the values of any picklist within the modules and add new picklists that might be referenced by a field in any module.

Unlike the Module Editor, changes made in the Picklist Editor are immediately live once they are saved. This is because Picklists names and Picklist values are records in the database.

A UUID (Universally Unique Identifier) identifies picklist values, which means if you modify any of the names or colors of an existing picklist value, the original data is preserved. Therefore, all records that contain that picklist value retains a reference to the UUID for the picklist. This means that if you want to change an Incident Category of Theft to Physically Stolen, you could make that change on the existing Theft value and any records with the value of Theft would now display Physically Stolen.

Picklist Editor

Creating or modifying a picklist

To add or modify a picklist:

  1. Click Settings and in the Application Editor section, click Picklists.
    This displays the Picklist Editor.
  2. Add or edit an existing picklist. To add a picklist, use the +Create new picklist option that appears at the top of the editor to define the properties of the picklist. Start by entering a title for the new picklist in the Title field.
    Or To edit an existing picklist, from the Select a picklist to edit or create new picklist drop-down list, select the picklist.
    For example, select AlertStatus.
  3. In the Items section, in the + Type and Press ENTER To Add New Picklist Item field, enter the name of the new picklist item and press Enter.
    For example, for the AlertStatus picklist, add items such as Open, False Positive, and Verified.
    Or
    To edit a picklist item, click the Edit icon that appears on the item row, update the name of the item or the color assigned to the picklist, and then click the green tick mark icon.
    Editing Picklist items
  4. (Optional) You can add colors to any picklist, by checking the Assign Colors checkbox. Once the Assign colors checkbox is enabled, you can assign each item in the picklist a color.
    Use the color picker box that appears next to each item in the picklist or enter the hexadecimal code for the color to edit the colors. You can use any valid HTML color.
    You can set the picklist color by directly entering the hexadecimal code of the color and assigning that as the picklist color, or by using an API, or you could choose colors by clicking in the color picker.
    The following image shows how to enter a hexadecimal code (#ff0000 for red color) in a picklist:
    Entering picklist colors using hexadecimal values
    Note: Multiple items in a picklist can have the same color.
  5. (Optional) You can also remove all items from the picklist by clicking the Removing All Items button, and you can also change the sort order of the picklist items clicking the Ascending or Descending order icon (Ascending or Descending Order icon).
    Picklist completed
  6. Click Save to save the changes made to the picklist or click Revert to clear any changes made to the picklist since the last Save event or click Remove Picklist to remove the picklist.
    You can also click the Audit Log button to view logs specific to a particular picklist. For more information on Audit Logs, see the System Configuration chapter.

Navigation Editor

Pages are iFramed resources that are accessible from the application interface by the user, such as resource pages and wikis within the local environment or on an accessible website link. Pages must currently be added in the modules API to be present to add in the Editor.

Use the Navigation Editor to modify the system Navigation bar, present on the left-side of the application interface.

Note

Changes that you make to the left navigation bar using the Navigation Editor affects all users. Currently, these changes cannot be made at a user-specific level.

Navigation Editor

There are two types of Navigation values:

  • Single-level navigation item, in which case an icon and title on the Navigation bar represent a module or page
  • Two-level navigation item, in which case an icon and title reveal a menu of additional options. Secondary navigation items might only have a name, not an icon.

You can add an external HTML page in an iFrame or a new tab and display that page as part of the left-navigation in FortiSOAR.

Modifying the Navigation bar

To modify the Navigation bar:

  1. Click Settings and in the Application Editor section, click Navigation. This displays the Navigation Editor.
  2. Add or modify the navigation bar:
    To add a single-level item, select module or pages by clicking the Modules or Pages tab, and click Add To Menu. Single level items on the menu must represent a 1:1 relationship with a module or page.
    To add a two-level item, select modules or pages by clicking the Modules or Pages button, and click Add As Group.
    The second-level navigation item is not a hyperlink or capable of referencing a given module or page. Only the sub-items in the group can be linked as a module or page. Clicking any two-level Navigation group shows and hides the sub-items.
    For example, you want to create a menu-group named Artifacts Management that has Attachments, Comment, and Scans as the menu items. You select the Attachments, Comment, and Scans modules and click Add As Group.
    This creates a menu group as shown in the following image:
    Example of a two-level menu group
  3. Edit the menu items by clicking the Edit icon that appears on the item row, update the name of the menu item or replace the icon of the first-level item in menu group, and click the green tick mark icon.
    You can replace icons by choosing icons from the icon selector at the left of each Navigation item.
    You can also delete a menu item by clicking the Delete icon.
    Example of editing a two-level menu group
  4. Drag-and-drop modules or module groups to change the order of the navigation items in the Navigation bar.
    Note: The top item of the navigation is always the default login page. By default, this is the dashboard page. However, you can modify this to make any other page the home page.
  5. To add an external HTML page in an iFrame or a new tab and display that page as part of the left-navigation in FortiSOAR, click the Pages tab and click the Add More link.
    Navigation Editor: Pages Tab - Add More link
    1. In the Title field, enter the name for the HTML page that you would want to display in the left navigation menu.
      For example, if you want to add a link to the Google website as part of your left-navigation in FortiSOAR, enter Google in the title field.
    2. In the URL field, enter the URL for the HTML page that you want to display in an iFrame or new tab. For our example, enter https://www.google.com.
    3. (Optional) If you want to open the page in a new tab, click the Open in New Tab checkbox.
      If the Open in New Tab checkbox is unchecked (default) the page will open in an iFrame in FortiSOAR.
    4. Click Add Page.
    5. On the Pages tab, select the page you have just added, Google in our example, and then click Add To Menu or Add As Group according to your requirements.
      Adding the HTML page to the Navigation Menu
  6. Click Save to save the changes made to the menu items or click Revert to clear any changes made to the menu items since the last Save event.

Correlation Settings

If you want to use the Visual Correlation widget to visually display the nodes related to a particular record, then you have to configure the display of the various related nodes on the Visual Correlation Setting page.

The following procedure is an example where you are configuring the display of tasks that have associated records.

  1. Click Settings and in the Application Editor section, click Correlation Settings.
  2. On the Visual Correlation Setting page, from the Choose Modules To Define Correlation View Configurations drop-down list, select the module for which you want to define visual correlations and then click Add and Configure.
    Note: FortiSOAR has pre-configured modules such as, Alerts, Assets, Incidents, Indicators, War Rooms, etc. The default depth of the nodes displayed is "3", i.e., if you start from the Alerts node, you view its related indicators and if those indicators have related assets, you can view those related assets. However, if that asset also has a related incident, then you can double-click on that asset node and see its related incident and so on.
  3. To configure the Campaigns module, from the Choose Modules To Define Correlation View Configurations drop-down list, select Campaigns and click Add and Configure.
  4. From the Choose Related Modules drop-down list, select the modules that should be shown in the correlation graph as linked modules, and then click Add Related Modules.
    Note: The modules that are pre-configured already have related modules configured, for example, the Alert module has Alerts, Incidents, Indicators, Vulnerabilities, and Assets configured as related modules.
    For our example, we require to add Alerts, Assets, and Incidents, as related modules to the Tasks module.
    Note: If you add a module that has not been configured for correlation, for example, the Comments module, then you will require to configure that module also before correlations can work. For example, if you choose the Comments module, then you must also configure the Node Label, Node Shape, and Node Color for that module.
  5. From the Node Label drop-down list, select the field that will be shown as a label for the node.
    For our example, choose Campaign Name.
  6. From the Node Shape drop-down list, select a shape that will be shown as the shape of the node.
    For our example, choose Square.
    You can also choose to specify a custom icon as the shape of the node. In this case choose Custom Icon from the Node Shape drop-down list and click Upload to display the Upload an Image dialog. In the Upload an Image dialog, drag-and-drop the icon file, or click the Import icon and browse to the icon file to import the icon file into FortiSOAR and then click Save Image to add the custom icon.
    You can also change the background shape of the custom icon by clicking the shapes present under Background shape of custom icon.
    You can also change the custom icon by clicking Change, which again displays the Upload an Image dialog.
    Note
    : The custom icon should be 15px X 15px and the file size must be less than 10KB.
  7. From the Node Color drop-down list, select the field that will conditionally determine the color of the node.
    For the pre-configured modules, such as alert, this field is set by default. For example, for the Alerts module, this is set as Severity. For the Campaign module, select Status.
    Note: In case of picklists the color of the node is determined by the color that you have assigned to the value of the picklist item. For example, if you have chosen the Priority as the picklist, then the colors that you have assigned to the selected picklist value will be used as the node color. For example, if the Priority is set as Urgent, then the node color will appear as Red, if its High, then the node color will appear as Orange, if its Medium, then the node color will appear as Yellow, etc. Therefore, if the task in which you have added the Visual Correlation widget is Critical, then its node color will be Red. For information on how to add the Visual Correlation widget in the records, see the Dashboards, Templates, and Widgets chapter in the "User Guide."
    You can also assign a custom color for the node by using the Choose custom color picker.
    Node Color - Custom Color picker
    If you do not specify any color, the node will appear with its default color.
  8. Next, you require to define how the related record node will also be displayed. For our example, we have chosen the Alerts and Incidents modules, as related modules all of which are pre-configured modules, so we do not require to configure any module.
  9. Click Save to save the settings for visual correlation.

Now, you can add the Visual Correlation Widget in the detail view of the Campaign records (see the Dashboards, Templates, and Widgets chapter in the "User Guide") to view the Correlations graph. The following image displays the "Visual Correlations" graph, which is an example of a Visual Correlation Widget being added to the detail view of Tasks records:

Display of the configured Visual Correlation Widget in the Tasks Details view

As you can see in the above image, the Correlations graph has a title which is Tasks: Correlated Records. The title can be specified by the user when they are adding the Visual Correlation Widget. The task for which correlated records are displayed is shown as a square node, whose color is determined by its severity, Red in this case since the task has priority set as "Urgent". The name of the task displayed as the label of the node. The associated records are displayed as various nodes, which is determined by the legend given in the left of the graph. The color of the nodes is determined by their "Severity" in case of Incidents and Alerts and "Asset Criticality" in case of Assets. For example, linked records whose severity is critical appear in red, high appear in orange, those that are medium appear in yellow, those that are low appear in green, and so on.

Recommendation Engine

FortiSOAR's Recommendation Engine empowers the product intelligence framework to suggest ranked threat similarities and field predictions, thereby helping to orchestrate better, informed, and holistic investigations. You can choose a suitable recommendation strategy and tune it to match your requirements. The Recommendation Engine analyzes your existing record data, recommends similar records, and predicts and assigns field values in records. From release 7.2.2, the Recommendation Engine also helps in predicting 'Phishing' emails, which improves triaging and the overall investigation process.

To view the 'Recommendation Engine' settings, click Settings, and in the Application Editor section, click Recommendation Engine:

Application Editor - Recommendation Engine
If you do not want FortiSOAR to predict or assign values to fields, display similar records, or predict 'Phishing Emails', then you can disable the 'Recommendation Engine' by toggling the Status button to 'Disabled'. By default, the 'Recommendation Engine' is enabled, i.e., the Status button is set to 'Enabled'.

Permissions required

To work with the Recommendation Engine and get record similarity, field predictions, and phishing classification using the ML engine, you must be assigned a minimum of Read permission on the Security module and on the module on which you require recommendations, and Read, Update, and Execute permissions on the Connectors module.

Record Similarity and Field Predictions

FortiSOAR provides you with the 'Recommendation Engine' that analyzes your existing record data using different algorithms to recommend similar records and predict and assign field values in records. It is based on finding similarities of patterns in historical data.

FortiSOAR provides you with two strategies for record similarity:

  • Elasticsearch Based Text Classification, which is based on analysis of similar records search using Elasticsearch's efficient algorithms to analyze the search results. This is the default recommendation engine.

  • Machine Learning Based Clustering, which is based on training the ML engine using the data existing on your FortiSOAR instance, and it uses traditional machine learning (ML) supervised classification algorithms such as 'K-Nearest Neighbors'.

Elastic Search Based Text Classification

On the Recommendation Engine > Record Similarity page, select either Elasticsearch Based Text Classification (default) as the recommendation strategy. For Elasticsearch Based Text Classification you do not need to configure anything, and FortiSOAR continues to predict and assign field values and display similar records as earlier releases. However, you can set up the record similarity and field prediction in the detail view of records based on which similar records and field predictions get displayed to all other users.

Setting up Record Similarity
  1. Open the Detail view of the alert record.
  2. Click the Workspace icon and then click the Recommendation tab:
    Recommendation tab
  3. To display similar records and specify the similarity criteria do the following:
    1. Click the Settings icon (Settings icon) on the Recommendations tab.
    2. In the Recommendations Settings dialog, on the Similar Records tab, ensure that the Show Similar Records Suggestions is toggled to On, which is the default.
      If it is not, then toggle Show Similar Records Suggestions to On as shown in the following image:
      Enabling Similarity
    3. In the Similarity Criteria section, choose the fields and relations to create the criteria based on which records will be displayed.
      For example, if you want to display the alerts whose indicators, such as domains, IP addresses, URLs, etc match the indicators of the alert record on which you are working and we also want to match the source of the alerts. Therefore, you will choose Indicators and Source from the Select Field drop-down list.
      You can also assign weights to the selected fields based on which the recommended similar records will be ranked. To assign ranks, select the Assign specific weights checkbox, then use the slider to assign weights for each of the selected fields from 1 to 10, with 10 being the highest value. For example, if you want to give higher weightage to similar Indicators as compared to Source, then you can assign a weight of 10 to Indicators and 5 to Source:
      Defining the Similarity Criteria
    4. (Optional) To filter the similar record suggestions, in the Filter Suggestions section, add the filter criteria. For example, if you only want to show similar records that have been created in the last month, then you can add the filter criteria as shown in the following image:
      Defining the filter criteria for similar records
      Adding filters narrows the records down to a smaller set, which in turn returns the results faster. For example, searching for similar records in the last one month will return results faster than searching for similar records in the last one year.
      Note: If you assign a "Custom" filter to a DateTime field, such as Assigned Date, then the date considered will be in the "UTC" time and not your system time.
    5. (Optional) In the Select Playbooks section, from the Choose Playbook list, search and select the playbooks that will be displayed on the Recommendations panel and which you can execute on similar records. For example, you can choose to evaluate indicators and therefore choose to run the Indicator Evaluation playbook on similar records.
    6. To define the layout of the similar records, in the Similarity Record Layout section, you can specify the fields of the similar records that you want to include. For example, you can choose Name, Severity, Assigned To, and Status, as the fields of the similar records that should be displayed.
      You can also define the color of the left border of the card based on a specific picklist or field in the Card Left Border Color Based On field. The color of the card will depend on the colors that you have defined for the picklist items. For example, choose Severity:
      Defining the Similarity Record Layout
    7. To save the similarity settings, click Save.

Based on the similarity criteria that has been defined, the Recommendation pane will display similar alerts as follows:

Recommendation pane - Display of similar alerts

Using the record similarity criteria set, users can view the list of records that are similar to the record that they are working on and can quickly perform various actions across all the similar records such as evaluating similar indicators across the module, marking all the records as 'Resolved', etc. For more information, see the Working with Modules - Alerts & Incidents and the Dashboards, Templates, and Widgets chapters in the "User Guide."

Setting up Field Suggestions
  1. Open the Detail view of the alert record.
  2. Click the Workspace icon and then click the Recommendation tab:
  3. To display prediction of values of fields and specify the criteria for the same, do the following:
    1. Click the Settings icon (Settings icon) on the Recommendations tab.
    2. In the Recommendations Settings dialog, on the Field Suggestions tab, ensure that the Show Field Suggestions is toggled to On.which is the default
      If it is not, then toggle the Show Field Suggestions to On, as shown in the following image:
      Enabling predicting values of field values
    3. In the Fields To Suggest On section, choose the fields for which you want FortiSOAR to predict the field values. For example, you can choose the Severity and Assigned To fields:
      Choosing the fields for prediction
      Important: Fields for which you want to predict values should not be fields that require some workflow or playbooks to be run if the value of the field is changed, since in this case though the value of the field gets updated, the complete workflow will not be completed. An example of such a type of field would be the Escalated field in the "Alerts" module and if you have added Escalated in the Field Suggestions, then even though you can change the value of the Escalated field in the record as per the field suggestions, which we are assuming is set to "Yes"; the complete Escalate workflow is not completed. In this case, even though the Escalated value of the alert record is set to Yes; however, the alert is not escalated to an incident, i.e., no corresponding Incident is created, and therefore the Escalate workflow of remains incomplete.
    4. To use the same criteria to form the field value suggestion as you have defined for similar records, ensure that the Use the same similarity criteria as set in similar record settings checkbox is selected (default).
      If you want to use a different criterion from the field value suggestion, then clear the Use the same similarity criteria as set in similar record settings checkbox. Then, in the Similarity Criteria section, choose the fields that would form the basis for predicting field values. For our example, choose the "Type" and the "Indicators" field.
      You can also assign weights to the selected fields based on which the recommended similar records will be ranked as described in the Setting up Record Similarity section.
      Defining the prediction criteria
    5. (Optional) To filter the field value suggestions, in the Filter Suggestions section, add the filter criteria. For example, if you only want to show similar records that have been created in the last 15 days, then you can add that as a filter criterion.
    6. To save the prediction settings, click Save.

Based on the prediction criteria that has been defined, the Recommendation pane will display field value suggestions as follows:

Recommendation pane - Field Value Suggestions

Using the field suggestions, users can choose to set the value of fields such as severity or assigned to, across all the similar records. For more information, see the Working with Modules - Alerts & Incidents and the Dashboards, Templates, and Widgets chapters in the "User Guide."

Machine Learning Based Clustering Text Classification

On the Recommendation Engine > Record Similarity page, select Machine Learning Based Clustering as the recommendation strategy. For Machine Learning Based Clustering, you need to train the ML engine using the data existing on your FortiSOAR instance. AI/ML technology can leverage past learning and similar patterns to smart predict values of record fields such as 'Assigned To' and 'Severity'. For example, for an incoming alert of type, Malware, your FortiSOAR system can fall back to similar Malware alerts that already existed in your system, and based on the similarity in patterns suggest values to the 'Assigned To' and 'Severity' fields in the new record. This saves time in a SOC as the task of sifting through records and assigning them is now done automatically.

Note

After you have upgraded your system to release 7.2.0 or later from a release prior to 7.2.0, and you observe that errors are being displayed for field suggestions and record similarity, then you must retrain your Machine Learning model.

To configure and train the ML engine, do the following

  1. On the 'Recommendation Engine' > 'Record Similarity' page, ensure that the Status of the Recommendation Engine is set to 'Enabled' and the Machine Learning Based Clustering option is selected.
    You will observe the FortiSOAR ML Engine is selected in the Selected Recommendation Connector drop-down list.
    Configuring the Recommendation Engine
  2. To configure FortiSOAR ML Engine, in the Configuration Name field, add a unique name for the configuration. The configuration name needs to be unique since you can have multiple configurations.
    Select the Mark As Default Configuration checkbox, if you want this particular configuration to be the default configuration of this connector, on this particular FortiSOAR instance.
    Note: You must select one configuration to be the default configuration of the FortiSOAR ML Engine connector.
    To add a new configuration, click the Select Configuration drop-down list and click + Add new configuration. You can specify different training datasets (modules) for each configuration and can also create different training schedules for the datasets for each configuration. However, as a best practice and for consistent results, you should have a single configuration per module.
  3. To train the FortiSOAR ML Engine, do the following:
    1. From the Module to train for drop-down list, select the module from which you want to select the fields for training and the fields that you want to predict. By default, the Alert module is selected.
    2. From the Feature Set list, select the field(s) using which you want to predict the field values. To select multiple fields, press Ctrl and select the field.
      For our example, where we want to predict the 'Assigned To' and 'Severity' fields based on the 'Type' of alert, select the Type field.
    3. From the Verdict list, select the field(s) that you want to predict. To select multiple fields, press Ctrl and select the field.
      For our example, we want to predict the 'Assigned To' and 'Severity' fields, therefore select the Assigned To and Severity fields.
    4. From the Date Range drop-down list, select the time range of records based on which you want to populate the training set.
      You can select from options such as Last Month, Last 6 months, Last year, etc. You can also select Custom and then specify the last X days to populate the training set.
    5. The Training Set Size specifies the number of records that make up the training set. It is set as 1000 records.
      Note: The value that you select from the Date Range drop-down list overrides this parameter
    6. From the Algorithm drop-down list, select the ML supervised classification algorithm using which you want to predict the fields. You can choose between K-Nearest Neighbors (default) or Decision Tree.
    7. In the Listener Port field, specify the port number of the socket where the ML Engine connector will load the ML models for efficient storage and delivery. By default, this is set as 10443.
      Recommendation Engine - Training Dataset
  4. Once you have specified the dataset to be used for training the FortiSOAR ML Engine, click Save & Train Model. Clicking Save & Train Model saves the specified parameters and trains the model, 'Alerts' in our example, based on these parameters.
    You will observe that the Configuration of the connector displays as Completed and the Heath Check of the connector displays as Available.
    Recommendation Engine - Configured along with the training dataset
    If you make any changes to the training dataset, such as adding or removing a field from the Feature Set or Verdict, click Train to update the dataset. To ensure that the dataset is trained on new incoming data regularly, you can also choose to train your dataset at regular intervals by scheduling training of the dataset by clicking Schedule. Clicking Schedule opens the Schedule Details dialog using which you can create a schedule for training your dataset. For more information on schedules, see the Schedules chapter in the "User Guide."

Once you have trained your dataset, FortiSOAR starts to analyze your dataset and based on the analysis displays records that are similar to the record you are working on, as well, predicts the values of field records that you have added to the Verdict field. Since we have trained the dataset, in our example, to predict the 'Assigned To' and 'Severity' fields based on the 'Type' field, FortiSOAR provides suggestions for those fields as shown in the following image:

Field Suggestions provided by FortiSOAR based on the recommendation engine

If you agree to the recommendations, then click the green check box beside the field, and that will populate that field in the record. For example, clicking the Severity green checkbox assigns 'Medium' as the record severity.

Assigning values to fields based on field suggestion

Similarly, you can view the list of records that are similar to the record that you are working on enabling you to quickly take remedial action. For more information on using record similarity and predicting values of field values in a record see the Working with Modules - Alerts & Incidents chapter in the "User Guide."

Phishing Classification

Phishing is probably the most common form of cyber-attack, largely because it is easy to accomplish, and surprisingly effective. It is a type of social engineering attack wherein an attacker impersonates to be a trusted contact and sends the victim fake mails. Therefore, in release 7.2.0, FortiSOAR introduces the 'Phishing Classification' feature. Phishing Classifier is a Machine Learning-based classifier that helps to predict emails that can be 'Phishing' emails, which helps speed up the triage and overall investigation process.

FortiSOAR provides you with two methods for training the 'Phishing Classifier' connector to predict phishing emails

  • Pre-trained Model: This model is trained using thousands of real-world phishing emails from Fortinet's security team. It is a quick-start way to understand the classification process.

  • FortiSOAR Module: This model is a new machine-learning (ML) model that you create by training your local dataset using an existing FortiSOAR module and its records.

Note

In the case of HA environments, all the training and predictions operations take place on the primary node.

Tooltip

You should configure the 'Phishing Classifier' on either your FortiSOAR node or your FSR Agent node, but not simultaneously on your FortiSOAR node and your FSR Agent node.

Administrators can see the Advanced Settings topic if they want to make some advanced changes such as changing the port used by the ML engine, or changing the normalization technique used by the phishing classifier.

Configuring Phishing Classification based on the Pre-trained Model

  1. On the 'Recommendation Engine' > 'Phishing Classification' page, ensure that the status of Recommendation Engine is set to Enabled. You will observe the Phishing Classifier is selected in the Selected Connector drop-down list.
    Recommendation Engine - Phishing Classification
  2. To configure the Phishing Classifier connector, in the Configuration Name field, add a unique name for the configuration. The configuration name needs to be unique since you can have multiple configurations.
    Select the Mark As Default Configuration checkbox, if you want this particular configuration to be the default configuration of this connector, on this particular FortiSOAR instance.
    Note: You must select one configuration to be the default configuration of the Phishing Classifier connector.
    If you have an existing configuration, then to add a new configuration, click the Select Configuration drop-down list and click + Add new configuration. You can specify different training datasets for each configuration and can also create different training schedules for the datasets for each configuration. However, as a best practice and for consistent results, you should have a single configuration per module.
  3. On the Configure Parameters tab, configure the following parameters:
    1. From the Type of Training Data drop-down list, select Pre-Trained.
      Choosing Pre-Trained means that you want to use the pre-trained dataset to predict 'Phishing Emails'.
    2. From the Display Predictions For Module drop-down list, select the module for whose records you want to display the predictions. For example, if you select Alerts, it means that you want to predictions for alert records.
    3. (Optional) To add further filtering on these records, click Add Data Filters and add additional filters. In this case, prediction will be shown for only those records that satisfy the filters. For example, add Type Equals Suspicious Email, to classify only those alerts whose type is suspicious email.
    4. In Feature Set Mapping, specify which fields of the module selected for prediction ('Alerts' in our example) maps to the ML model fields. You have to map the following fields: Email From, Email Subject, and Email Body.
  4. Once you have specified the configurations for training the Phishing Classifier connector, click Save Configuration, which saves the specified parameters and begins training the model, 'Alerts', in our example, based on these parameters. At this step, the pre-trained model is loaded into memory for predictions. If this operation is successful, the 'Heath Check' of the connector displays as 'Available':
    Pre-Trained Model - Phishing Classification Configuration Complete
  5. Click the Model Performance Summary tab to view the performance of the model in terms of precision per class:
    Model Performance Summary Page

Configuring Phishing Classification based on a FortiSOAR Model

  1. Configure the Phishing Classifier connector as mentioned in steps 1 and 2 of the Configuring Phishing Classification based on the Pre-trained Model section.
  2. After you have configured the Phishing Classifier connector you need to specify its training dataset:
    1. From the Type of Training Data drop-down list, select FortiSOAR Module.
      Choosing FortiSOAR Module means that you want to use the data from your FortiSOAR instance to predict 'Phishing Emails'.
    2. From the Module to Train For drop-down list, select the module for which you want to train the data. For example, if you select Alerts, then alert records existing in your system are used to train the model, and then subsequently predictions will be displayed on the alert records.
    3. (Optional) To add further filtering on these records, click Add Data Filters and add additional filters. In this case, prediction will be shown for only those records that satisfy the filters. For example, add Type Equals Suspicious Email, to classify only those alerts whose type is suspicious email.
    4. From the Date Range drop-down list, select the time range of records based on which you want to populate the training set.
      You can select from options such as Last Month, Last 6 months, Last year, etc. You can also select Custom and then specify the last X days to populate the training set.
    5. The Training Set Size specifies the number of records that make up the training set. It is set as 1000 records.
      Note: The value that you select from the Date Range drop-down list overrides this parameter.
    6. In Feature Set Mapping, specify which fields of the module selected for prediction ('Alerts' in our example) maps to the ML model fields. You have to map the following fields: Email From, Email Subject, and Email Body.
    7. In this case, since you are using an existing module for training, the model needs to know the classification of each email before the training. For this, you must specify which values of the field constitute as phishing and which constitute as non-phishing. Therefore, in Verdict Field Mapping, map the values of the picklist (field) in Phishing and Non-Phishing buckets that you want to train as the verdict of the model.
      By default, for the Alerts module a picklist named 'Email Classification' is added that has two items, Phishing and Non Phishing, which can be used by the users to classify the record:
      Phishing Classification - FSR Module Default Field Mapping and Verdict Mapping
      However, you can choose any other picklist (field) based on which you want to classify emails. For example, you can choose the verdict field as 'Type' and then in the 'Phishing' bucket put alerts whose type is Brute Force Attempt, Denial of Service, or Policy Violation, and in the 'Non Phishing' bucket put alerts whose type is Compliance.
      Phishing Classification - FSR Module Field Mapping and Verdict Mapping for the 'Type' field
  3. Once you have specified the dataset for training the Phishing Classifier connector, you can click Save & Train Model or Save Configuration.
    Clicking Save Configuration saves the specified parameters.
    Clicking Save & Train Model saves the specified parameters and also begins to train the model, 'Alerts', in our example, based to these parameters. Once the training is completed, the 'Heath Check' of the connector displays as 'Available':
    Phishing Classification - FSR Module Training Completed
    If you make any changes to the training dataset, such as adding or removing a field from the Verdict Field Mapping, click Train to update the dataset. To ensure that the dataset is trained on new incoming data regularly, you can also choose to train your dataset at regular intervals by scheduling training of the dataset by clicking Schedule. Clicking Schedule opens the Schedule Details dialog using which you can create a schedule for training your dataset. For more information on schedules, see the Schedules chapter in the "User Guide."

Once you have trained your dataset, FortiSOAR starts to analyze your dataset and based on the analysis displays suggestions on whether or not an alert record can be classified as a 'Phishing' record as shown in the following image:
Alert Details View - Phishing Suggestion
Open the detail view of an alert record, and click the Recommendations tab on the Workspace panel, to see a Suggestion section that contains the Is this Phishing? question followed by the answer to that question and the corresponding confidence level. For example, in the above image, the answer to the Is this Phishing? question is Yes, with 99% confidence that it is a phishing email (record). Using this suggestion and its corresponding confidence value it becomes easy for analysts to classify records into 'Phishing' and 'Non Phishing' and accordingly proceed with the investigation process.

Note

In the case of HA environments in which a 'Takeover' operation has been performed; post-takeover, you have to retrain data on the new primary node to use the machine learning services to predict phishing suggestions.

Notes with respect to FSR agents:

  • If you have installed and configured the Phishing Classifier connector on an agent node, and not on the FortiSOAR (base) node, then suggestions are not displayed in the Recommendations tab on the Workspace pane; however, you can use the agent configuration in connector actions in playbooks to get the predictions.

  • As FSR agents need to interact with modules to display suggestions, you require to modify the FortiSOAR Agent role to include access to the modules for which predictions are configured. For example, if you have set up predictions for the 'Alerts' module, then you must update the FortiSOAR Agent role with the minimum of Read permissions on the 'Alerts' module.

Advanced Settings

  • By default, the ML engine runs on port 10449. If the same port is occupied by some other process in the system, then the administrator can change the port number in the SERVER section of the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file, and then restart the uwsgi service.
  • The TFIDF section in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file enables the administrator to provision controlling the frequency of a word in the corpus. A term is excluded from the feature set if it does not satisfy the min_df (minimum document frequency) or max_df (maximum document frequency). If you update the TFIDF section, then you must restart the uwsgi service.
    For more information, see https://scikit-learn.org/stable/modules/generated/sklearn.feature_extraction.text.TfidfVectorizer.html
  • Words that are included in the ignore_words field in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file are excluded from the feature set. This allows administrators to exclude organization-specific words that should not be part of the feature set. If you make any changes to the ignore_words field, then you must restart the uwsgi service.
  • Words that are included in the function_words field in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file contain words that are generally found in phishing emails. Administrators can update words that are part of the function_words field. If you make any changes to the function_words field, then you must restart the uwsgi service.
  • As part of pre-processing, unimportant words are removed from the data and the words are converted to their base forms to avoid redundancy. There are two methods to achieve this normalization: 'stem' and 'lemmatize'. By default, the Phishing Classifier uses the 'stem' method. You might want to change the normalization technique to lemmatize if you think that it might improve the prediction accuracy. To change the normalization technique to lemmatize, do the following:
    1. Download the nltk data file on your FortiSOAR instance from https://repo.fortisoar.fortinet.com/downloads/scripts/nltk_data.tar.
    2. Copy the downloaded .tar file to the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/ folder.
    3. Untar the nltk data file using the following command:
      tar -xvf nltk_data.tar
    4. Provide appropriate permissions to the nltk data file using the following commands:
      chmod -R 654 /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/nltk_data
      chown -R nginx:nginx /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/nltk_data
    5. In the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file, update the value of the word_normalization_technique parameter from stem to lemmatize.
    6. Restart the uwsgi service and retrain the model.

Export and Import Wizards

FortiSOAR provides you with a wizard-based export and import of record data, configuration information, dashboards, application settings, etc., which enhances the user experience and improved architecture. These enhancements also allow for scheduled, API-based export and imports. For information about the export and import APIs, see the API Methods chapter in the "API Guide."

FortiSOAR version 7.0.0 enhances the Import and Export Wizards to support the import and export of templates, installed connectors, connector configurations, widgets, teams, and users.

From version 7.0.2 onwards, the export wizard creates a zip file for all the exported content. Prior to version 7.0.2 content was exported in the JSON format. You can use both the zip and JSON (for content exported from a FortiSOAR system prior to 7.0.2) to import content using the Import Wizard. The zip file contains a folder for each entity that is exported, along with a json file (export.metadata.json) that contains metadata information such as the FortiSOAR version from which the content was exported, user who exported the content, datetime of when the content was exported, etc.

For example, if you have exported the alerts and incidents modules configurations, record data for the alerts and incidents modules, some dashboards, and some roles, the folder structure will be as follows:

FortiSOAR Export DatetTme folder
--+ modules
---+ alerts
------+ detail-layout.json
------+ form-layout.json
------+ list-layout.json
------+ mmd-layout.json
---+ incidents
------+ detail-layout.json
------+ form-layout.json
------+ list-layout.json
------+ mmd-layout.json
---+ records
------+ alerts
---------+ alerts0001.json
----+ incidents
---------+ incidents0001.json
---+ dashboards
------+ System Dashboard.json
------+ T1 Analyst.json
---+ roles
------+ T1 Analyst-<UUID>.json
------+ Security Administrator-<UUID>.json

Important: The record set file will have maximum 100 records.

Permissions required

  • To export and import record data and configurations using the Wizards or APIs, users who will be performing the import/export operations must be assigned a role that has Create, Read and Update permissions on the Application, Security, and Playbook modules.
    • Users who require to import files must additionally be assigned a role that has Create and Read permissions on the Files module.
    • Users who require to import connectors must additionally be assigned a role that has Create, Read, and Update permissions on the Connectors module.
    • Users who require to export connectors must additionally be assigned a role that has Read permissions on the Connectors module.
  • If a playbook is running the import and export using the API, your playbook appliance also requires the same permissions.

Export Wizard

You can use the Export Wizard to export modules information such as record data, module metadata, field definitions, picklists, view templates, etc. of your modules. You can also export playbook collections, dashboards, reports, and administrative settings such as, application configuration, system views, etc.

To export configurations, do the following:

  1. Click Settings and in the Application Editor section, click Export Wizard.
    This displays the Export Wizard page.
    Configuration Export page - Export Templates page
    To import an exported template, click the Import button
  2. To begin a new export for configurations and create an export template, click the Export Templates tab, and then click New Export Template.
    This displays the Choose Entities page in the Export Wizard, in which you can choose all or any of the entities such as modules, playbooks, dashboards, etc. that you want to export.
    To run an existing configuration again, click the Run icon in the Actions column, which displays the "Run Export' screen of the Export Wizard using which you can rerun an existing configuration.
    To edit an existing configuration, click the Edit icon in the Actions column, which displays the "Choose Entities" screen of the Export Wizard using which you can edit the configurations you want to export as per your requirements. To delete an existing configuration template, click the Delete icon in the Actions column.
    If you want to use a playbook to schedule exporting configurations using an existing export template, you will require to add the UUID of the export template in the playbook. You can get the UUID of the export template by click the Copy UUID to Clipboard icon in the Actions column.
    The Export History page displays a list of configurations that have been exported:
    Configuration Export page - Export History page
    To download the exported file in the zip format, click the Download icon in the Actions column, and to delete a configuration file, click the Delete icon in the Actions column.

Exporting Modules and/or picklists

From version 7.0.2 onwards, export and import of record data is supported. The ability to export and import all data and configurations enables creating a near-exact replica of a FortiSOAR environment.

Note

The maximum number of records that can be exported is 100000 per module. Also, note that importing a large number of records can greatly increase the duration of the import, and before you start exporting records, ensure that there is sufficient space in the /tmp/ folder.

  1. On the Choose Entities page, in Export Wizard, select Modules and click Continue.
    Export Wizard - Choose Entities page
    Note: You can choose to export one, all, or multiple entities.
  2. On the Filter Data page, click the Modules option, and select the modules that you want to export. You can choose to export one, all, or multiple modules. You can also choose to export record data and all or any of the configuration information associated with a module, i.e., the module's schema, listing view, record view, and add views.
    The List View, Detail View, and Add View exports the configuration information of the templates that you have created for the selected module(s). The Records exports the record data of the selected module(s). You can choose whether you want to export the correlation data along with the module's data. If you want to export the correlation data, then click Correlations.
    Important: When you are exporting (or importing) Queues or Shifts, you must select the Queues and Shifts module as well as their records. Queues and Shifts are exported as records and the configuration of the Queue Management page is exported using the System View Template. For more information on Queue and Shifts, see the Queue and Shift Management chapter in the "User Guide."
    To include all the selected entities, click the Include Everything checkbox. In this case, it exports the record data for all the modules and all its associated configuration information including the module's schema, views, and all the picklists.
    Note: You cannot export or import record data for the system modules, i.e., the People, Appliances, and Approvals modules.
    To export module configurations, choose the modules and their related configurations you want to export. From release 7.2.0 onwards, you can choose to export selective fields from a module. Click the Review button to select the fields that you want to export; by default, all fields are exported. For example, if you do not want to export the 'Bytes Transferred' and 'Vulnerability Severity' fields, clear those check boxes:
    Export Wizard - Selective exporting of fields
    You will also observe that the Auto-Select Required Picklists checkbox is selected by default since the picklists associated with the module must also be exported when you are exporting the configuration information for the modules to ensure there are no issues when you import the configuration to another environment. Therefore, for example, if you select Schema for the "Alerts" module, you will observe that "9" picklists that are required for the "Alerts" module are automatically selected.
    To export record data, click the Modules menu item, and in the Choose Modules and Views to Export table choose the modules whose record data you want to export. For example, if you want to export records of the 'Alerts' module, click Records in the 'Alerts' module row:
    Exporting Alert Data
    Once you click Records, an Add Filters link and a Correlations button are displayed. If you want to export the records' correlations such as the records' related incidents, assets, etc., then click the Correlations button. You can also choose to filter the records you want to export, allowing customization of which records to export. To filter records, click the Add Filters link. For example, if you do not want to export alert records that are 'Closed', you can add that filter in the Filter Alerts dialog. You can also update the maximum number of records you want to export in the Limit field, the default being 100 records (maximum 100000),and also choose how you want to sort the exported data, by selecting a field from the Default Sort drop-down list. Once you have competed filtering the records, click Update Query.
    Note: If a record set is included in the export, then the module schema for that record set is required and gets automatically included in the export.
    Filtering alert data while export
    Click the check boxes in the header row to perform bulk actions. For example, clicking the Export All checkbox selects all the modules their associated configurations, but not their record data. Similarly, clicking the Schemas checkbox in the header row changes Export to Yes for all modules and selects the schema for all the modules.
    To enable export of configurations and record data for a particular module, in that module's row, toggle the Export button to Yes, which selects all the configuration information associated with a module, i.e., the module's schema, listing view, record view, and add views. If you do not want to export some configuration information, for example, add view, toggle the Add View button to disable exporting the add view configuration.
    Note: The export and import wizards do not take care of data replication settings for modules. For example, in the case of an MSSP system, on a tenant node, if you have set up data replication on the 'Comment' Module, and if you export this module and import it to another system, you will observe that the data replication flag is not set for the 'Comment' module.
    If you want to export only picklists, click the Picklists menu item, and select the picklists you want to export. Using this menu item, you can export the picklists that are not associated with any module.
    Note: When you import a picklist, by clicking Import Wizard and if that picklist already exists on your system, then the "Import Wizard" replaces the existing picklist.
    Once you have complete choosing the modules and picklists that you want to export, click Continue.
  3. On the Review Export page, you can review the record data and configuration information that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the specified configuration information in a zip file that you can download and use in another environment, or click Save to save the configuration information.
    FortiSOAR also displays warnings if there are any inconsistencies in the data, such as templates not found, to be exported. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the specified configuration information as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard in which you can edit the configurations you want to export as per your requirements.

Exporting Playbooks and/or Global Variables

You can export playbook collections and global variables. Currently, you have to export the complete playbook collection, and cannot select specific playbooks to be exported from within a playbook collection.

  1. On the Choose Entities page, in Export Wizard, select Playbooks and click Continue.
  2. On the Filter Data page, select the playbook collections and/or global variables that you want to export.
    In the Choose Playbook Collections and Global Variables To Export page, in the Playbook Collections section, click the Playbook Name checkbox to select or deselect all the playbook collections. To export specific playbook collections, select those playbook collections. To include versions of your playbooks while exporting playbook collections, click the Include Versions checkbox.
    Similarly, in the Global Variables section, click the Global Variable Name checkbox to select or deselect all the global variables. To export specific global variables, select those global variables.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the playbook collections and global variables.
    Once you have complete choosing the playbook collections and/or global variables that you want to export, click Continue.
  3. On the Review Export page, you can review the playbook collections/global variables that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the playbook collections/global variables in a zip file that you can download and use in another environment or click Save to save the playbook collections/global variables. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the playbook collections/global variables configuration as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import a playbook collection, by clicking Import Wizard, and if that playbook collection exists, you can choose to either overwrite the existing playbook collection or create a new playbook collection and appending the original playbook collection name with a number. For more information, see Importing configurations.
    When you import a global variable, by clicking Import Wizard and if that global variable already exists on your system, then the "Import Wizard" replaces the existing global variable.

Exporting Dashboards, Reports, Rules, and Rule Channels

  1. On the Choose Entities page, in Export Wizard, select Dashboards, Reports and Rules & Channels, and then click Continue.
  2. On the Filter Data page, select the dashboards, reports, rules & channels that you want to export.
    Click the Dashboards menu item, and in the Choose Dashboards To Export table, click the Dashboard Name checkbox to select or deselect all the dashboards. To export specific dashboards, select those dashboards.
    Similarly, click the Reports menu item, and in the Choose Reports To Export table, click the Report Name checkbox to select or deselect all the reports. To export specific reports, select those reports.
    Click the Rules menu item, and in the Choose Rules To Export table, click the Rule Name checkbox to select or deselect all the rules. To export specific rules, select those rules.
    Similarly, click the Rule Channels menu item, and in the Choose Rule Channels To Export table, click the Rule Channel Name checkbox to select or deselect all the rules. To export specific rule channels, select those rule channels.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the dashboards and reports.
    Once you have complete choosing the dashboards and/or reports that you want to export, click Continue.
  3. On the Review Export page, you can review the dashboards, reports, rules, and rule channels that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the dashboards, reports, rules, and rule channels in a zip file that you can download and use in another environment or click Save to save the dashboards, reports, rules, and rule channels. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the dashboard/report template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import dashboards, reports, rules, or rule channels, by clicking Import Wizard and if that dashboard or report already exists on your system, then the "Import Wizard" replaces the existing dashboard or report.

Exporting Connectors

You can export connectors that are installed on your system. You can export connector installation and their configurations. From version 7.0.2 onwards, you can also export and import .tgz files of widgets and connectors. If a connector version is not found in the global connector repository, then the export wizard will export the .tgz file of the connector instead of the 'rpm' name. Similarly, if a widget version is not found in the widgets repository, the export wizard will export the .tgz file for the widget.

Caution

Password and API keys are NOT encrypted during export, which means that anyone who has access to the exported file will be able to access the connectors. Therefore, you must be careful while exporting the connector configurations.

  1. On the Choose Entities page, in Export Wizard, select Connectors and click Continue.
  2. On the Filter Data page, select the connectors that you want to export. You can choose to export one, all, or multiple connectors. You can also choose to export the configuration information associated with a connector.
    Click the Connectors menu item, and in the Choose Connector To Export table, select the connectors that you want to export. To export both the installation and the configuration for a particular connector, in that connector's row, toggle the Export button to Yes. If you want to export only the configuration for a connector, then toggle the Installation button to disable exporting the installation for that connector, or toggle the Configurations button to disable exporting the configurations.
    Click the checkboxes in the header row to perform bulk actions. For example, clicking the Export All checkbox, selects all the connectors their associated configurations. Similarly, clicking the Configuration checkbox in the header row, changes Export to Yes for all connectors and selects the configurations for all the connectors.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports the installations and configurations for all the connectors.
    Once you have complete choosing the connectors that you want to export, click Continue.
  3. On the Review Export page, you can review the connectors that you are exporting, and can also specify the name of the template that you are exporting, as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the connectors in a zip file that you can download and use in another environment or click Save to save the connectors.
    If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the connector template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.

Exporting Widgets

You can export widgets that are installed on your system. From version 7.0.2 onwards, users can also export and import .tgz files of widgets and connectors. If a widget version is not found in the widget repository, then the export wizard will export the .tgz file for the widget.

  1. On the Choose Entities page, in Export Wizard, select Widgets and click Continue.
  2. On the Filter Data page, select the widgets that you want to export. You can choose to export one, all, or multiple widgets.
    Click the Widgets menu item, and in the Choose Widgets To Export table, select the widgets that you want to export, and click Continue.
  3. On the Review Export page, you can review the widgets that you are exporting, and can also specify the name of the template that you are exporting, as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the widgets in a zip file that you can download and use in another environment or click Save to save the widgets.
    If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the widget template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.

Exporting Administrative Settings and System Views

You can export system views, and administrative settings with the customizations that you have applied across your FortiSOAR instance. For example, you can export your application settings such as branding and notifications, SSO, LDAP, Radius configurations, proxy and environment variables, etc.

Tooltip Passwords are write-only fields and therefore they cannot be exported using Configuration Manager. Therefore, if for example, you have exported your LDAP configurations and imported that into another FortiSOAR system, then since the passwords are not copied, you have to manually enter the passwords for all the users to be able to perform any activity related to users, such as searching for users or updating details of users.
  1. On the Choose Entities page, in the Export Wizard, select Administrative Settings and click Continue.
  2. On the Filter Data page, select the roles and/or settings that you want to export.
    Click the Administrative Settings menu item, and in the Choose Administrative Settings To Export table, in the Administrative Settings section, click the Settings Name checkbox to select or deselect all the administrative settings. To export specific administrative settings, select those administrative settings.
    Similarly, Click the System Views menu item, click the Views Name checkbox to select or deselect all the system views. To export specific system views, select those system views.
    You can choose to customize the navigation structure you want to export. Click the Review button to display the items included in the navigation and then select the individual items from the navigation to export the custom navigation:
    Export Wizard - Exporting a custom navigation
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the system views and administrative settings.
    Once you have complete choosing the settings, and administrative settings that you want to export, click Continue.
  3. On the Review Export page, you can review the settings that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the settings/views in a zip file that you can download and use in another environment or click Save to save the settings. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the settings template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    When you import the exported configurations into a system, all the application settings that were applied on the system from which the application settings were exported get applied on the system where you import and install the settings. For example, if the system from which the application settings were exported had its "Audit Log Purge" enabled with the logs to be retained for the last month, the same Audit Log policy will apply on the system in which you import and install the application settings.
    Important: If you have exported your SSO configuration and imported the SSO (SAML) configurations into a different FortiSOAR system, you require to make certain updates before SAML users can log into FortiSOAR. For more information, see Updates required to be done after importing SSO configurations.
    Note: When you import the queue management configuration system view or any administration setting by clicking Import Wizard, and if the queue management configuration system view or administrative setting already exists on your system, then the Import Wizard will overwrite the same. In the case of the navigation structure, you can choose to merge or replace the navigation structure in your system.

Exporting Security Settings

You can export security settings, which includes users, teams, and roles, that are present in your FortiSOAR instance.

From version 7.0.1 onwards, access type information, i.e., named or concurrent, is also exported along with the other user details, and the same are accordingly imported. If users are being imported from a version earlier than 7.0.1, i.e., 7.0.0, then those users do not have any access type information, and in this case, these users are imported as 'named' users.

  1. On the Choose Entities page, in the Export Wizard, select Security Settings and click Continue.
  2. On the Filter Data page, select the roles, teams, or users that you want to export.
    To export roles, click the Roles menu item, and in the Choose Roles To Export table, click the Role Name checkbox to select or deselect all the roles.
    To export specific roles, select those roles. You can export roles such as Full App Permissions, Application Administrator, T1 Analyst, Security Administrator, etc.
    From version 7.0.2 onward, you can choose to export specific module access for a particular role. For example, if you want to export the 'SOC Analyst' role, without having access to the 'Announcements' module, select the SOC Analyst role, then click the Review button, to display all the module permissions associated with this role. Clear the Announcements checkbox to remove the permissions associated with the Announcements module. When you import this role to another FortiSOAR system the 'Announcements' permissions for the SOC Analyst role will be removed:
    Exporting a role with specific permissions for a selected module
    To export teams, click the Teams menu item, and in the Choose Teams To Export table, click the Team Name checkbox to select or deselect all the teams. To export a specific team, select that team.
    Similarly, to export users, click the Users menu item, and in the Choose Users To Export table, click the Name checkbox to select or deselect all the users. To export a specific user, select that user.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the roles, teams, and users.
    Once you have complete choosing the roles, teams, and users that you want to export, click Continue.
  3. On the Review Export page, you can review the roles, teams, and users that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the roles, teams, and users in a zip file that you can download and use in another environment or click Save to save the settings/roles. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the roles, teams, and users template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import a role, user, or team by clicking Import Wizard, and if that role, user, or team already exists on your system, the Import Wizard will overwrite the existing role, user, or team.

Import Wizard

You can use the import wizard to import record data, configurations or metadata information for modules, playbook collections, dashboards, etc. from other environments into FortiSOAR. Using the import wizard, you can move model metadata, picklists, system view templates, dashboards, reports, roles, playbooks, and application settings across environments.

Importing configurations

The following section provides an example of importing modules. You can import dashboard, system views, playbooks, etc., using the same method.

Note

To import configurations into FortiSOAR the configurations file must be in the JSON/ZIP format. FortiSOAR ensures that you either revert or publish staged changes prior to importing configurations so that there are no issues during the import process.

  1. Click Settings and in the Application Editor section, click Import Wizard.
    This displays the Import Wizard page.
    Configuration Import Page
    If you close the wizard without clicking Run Import, then the status of your import will display as "Reviewing", and you can click the Continue icon in the Actions column to display the "Configurations" screen of the Import Wizard, and you can continue review of the import configurations. If you have clicked Run Import, and the import process is completed, then the status of your import will display as "Import Complete". You can also the configuration at any time by clicking the Reimport icon in the Actions column to display the "Configurations" screen of the Import Wizard.
  2. Click Import From File.
    This displays the Upload File page in Import Wizard. On this page, drag and drop the JSON or ZIP file, or click the Download icon and browse to the JSON or ZIP file to import configurations into FortiSOAR. If the JSON format is incorrect, FortiSOAR displays an error message and not import the file. If the JSON format is correct, FortiSOAR imports the configurations and displays details of what is being imported on the Configurations page.
  3. On the Configurations page, choose the configurations that you want to import, and click Continue.
    Import Configurations - Configurations page
  4. Importing Configurations:
    Importing Dashboards, Reports, Widgets, Rules, Rule Channels, System Views, Administrative and Security (User, Team, Role) Settings:
    To import Dashboards, Reports, Rules, or Rule Channels on the Options page, click the Dashboards or Reports menu item. The "Observation" column displays whether the dashboards or reports that you are importing are "New" or "Existing". Click the Dashboard Name or Report Name checkbox to select or deselect all the dashboards or reports, or click the checkbox alongside the individual dashboard or report name to import particular dashboard or report.
    If you are importing Dashboards and or Reports, then apart from displaying whether it is an existing or new dashboard or report, you can assign a default role to the dashboard or report:
    Import Configurations - Dashboards
    The Options page for Widgets, Rules and Rule Channels, Roles, Users, and Teams are similar to the Dashboards page, except that their Options page does not have any role assignment drop-down list.
    Important: Concurrent users are imported as per their original state, i.e 'Active' or 'Inactive'; whereas named users are imported in the 'Inactive' state. Administrators must change their state manually to 'Active' as required. Also, from version 7.0.1 onwards, access type information, i.e., named or concurrent, is also imported along with the other user details. If users are being imported from a version earlier than 7.0.1, i.e., 7.0.0, then those users do not have any access type information, and in this case, when these users are imported they are imported as 'named' users.
    The Options page for Administrative Settings, System Views, Teams, Users, Roles, and are also similar to the Dashboards page, except that the Administrative Settings and System Views pages do not have the "Observation" column.
    Use the <Name of the Option> Name checkbox to select or deselect all the configurations of a particular type on their respective pages. For example, if you want to import all the administrative settings, click the Administrative Settings menu item, and then in the Administrative Settings section, click the Setting Name checkbox to select or deselect all the administrative settings.
    In the case of System Views, click the System Views menu item, and then click the View Name checkbox to select or deselect all the system views. In the case of Navigation Structure, you can choose to Merge (Default) or Replace the navigation structure existing in your system. Merge appends the extra navigation items available in the import configuration to the navigation structure existing in your system. Replace replaces your existing navigation structure with the items and structure that are specified in the import configuration. If you have selected the Merge option, then you can also selectively choose to Skip or Append (Default) individual navigation items by clicking the Review button:
    Import Wizard - Navigation Structure items - Append or Skip
    Important: If dashboards, reports, global variables, widgets, roles, uses, teams, system views (apart from navigation structure), rules, rule channels, or administrative settings that you are importing already exist in your system, then the Import Wizard overwrites the configurations of these entities in your system. In the case of widgets, when you try to import a specific version of a widget using the import configuration file, and that widget is not present in the FortiSOAR repository, then the latest version of that widget gets installed in your FortiSOAR system.
    Importing Connectors:
    To import connectors, on the Options page, click the Connectors menu item. The "Choose Connectors to Import" page displays whether the connectors that you are importing are "New" or "Existing":

    - If the connectors are new, then the connector import installs and configures the connector on your system.
    - If the connectors are existing, and if the version of the installed connector on your system is the same or higher, then the connector import replaces only the connector configuration on your system.
    - If the connectors are existing, and if the version of the installed connector on your system is the lower, then the connector import upgrades the connector on your system and replaces its configuration with the imported configuration.
    - If the connectors are existing, and if the version of the installed connector on your system is the same or higher, and you are importing a connector with no configuration information, then nothing is replaced on your system.
    Click the Import All checkbox in their respective sections to import all the connectors and their configurations in the respective 'Existing Connectors' or 'New Connectors' section. Similarly, click the Installation and Configuration checkboxes in the header to import all the installations and all the configurations respectively.
    Toggle Import to Yes in a connector row to import that connector's installation and configuration and similarly toggling off the Install or Configuration buttons does not import the said installation or configuration.
    Importing Playbook Collections and Global Variables:
    To import playbook collections, on the Options page, click the Playbook Collections menu item. Currently, you have to import the complete playbook collection, and cannot select specific playbooks to be imported from within a playbook collection. The playbook collections and global variables page displays the list of "New Playbook Collections", "Existing Playbook Collections", "New Global Variables" and "Existing Global Variables". In case of new playbook collections and global variables, click the Import All checkbox in their respective sections to select or deselect all the new playbook collections and global variables. To import particular playbook collections or global variables, click the checkbox alongside the individual playbook collections or global variables. In case of existing playbook collections, apart from the Import All checkbox in the header, the Import Wizard also displays the following the "Bulk Actions" that you can take for existing playbook collections: Replace Existing Collections, Replace Existing Collection (append number), Merge Collections (replace existing playbooks) or Merge Collections (skip existing playbooks), which is the default option. You can choose to apply this action across all the playbook collections you are importing or you can choose the action to be performed for each playbook collection that you are importing:
    - If you retain Merge Collections (skip existing playbooks) action, then the Import Wizard merges the playbook collection by skipping the existing playbooks. For example, if have exported a 'Demo' playbook collection, that has a two playbooks 'Create Demo Records' and 'Test Manual Input', and you are importing this into a system that has the 'Demo' playbook collection with the 'Create Demo Records' playbook, then the Import wizard merges the 'Demo' playbook collection such that it will not overwrite the 'Create Demo Records' playbook; however it will add the 'Test Manual Input' playbook.
    - If you choose the Merge Collections (replace existing playbooks) action. then the Import Wizard merges the playbook collection by replacing the existing playbooks. For example, if have exported a 'Demo' playbook collection, that has a two playbooks 'Create Demo Records' and 'Test Manual Input', and you are importing this into a system that has the 'Demo' playbook collection with the 'Create Demo Records' playbook, then the Import wizard merges the 'Demo' playbook collection by overwriting the existing 'Create Demo Records' playbook and adding the 'Test Manual Input' playbook.
    - If you choose the Replace Existing Collections action, then the Import Wizard overwrites the playbook collections in your system.
    - If you select Replace Existing Collections (append number), then the Import Wizard creates a new playbook collection and appends a number to the original playbook collection name. For example, if you have exported a playbook collection named 'Demo' and you are importing the same playbook collection with Replace Existing Collections (append number) selected, then the imported collection will automatically be created as a new playbook collection named as 'Demo (1)'.
    Import Configurations - Playbook Collections
    Importing Record Data:
    To import record data, on the Options page, click the Record Set(s) menu item. The Options page displays the module name for which the records are being imported, the count of records to be imported, and the overwrite settings, i.e., you can choose to either Overwrite records if they exist or can choose to skip records if they exist.
    Import Wizard - Importing Record Data
    Note: If a record set is included in the import, then the module schema for that record set is required and gets automatically included in the import.
    Importing Modules Configurations and Picklists:
    When you import configurations for existing modules, and if the modules that you are importing contain fields that conflicts with the existing fields that prevent some fields from being imported, then those modules are displayed in Existing Modules With Conflicts section as shown in the following image:
    Import Configurations - Modules Page - Existing Modules With Conflicts
    Modules whose fields have no conflicts with existing fields are displayed in the Existing Modules Without Conflicts section as shown in the following image:
    Import Configurations - Modules Page
    Choose the options in the header row to perform bulk actions. For example, if you want to import all the modules, click the Import All checkbox, etc.
    For schemas of the modules that you are importing, you can choose if you want to Merge With Existing configurations, Replace Existing configurations, or Append New Fields to the configurations. You can click the Review Field Level Actions icon to view the detailed schema of the module you are importing.
    Merge With Exisiting, merges then the configurations, i.e., for example if you are importing an existing module, say Alerts, which has 3 new fields in the configuration that you are importing and 10 existing fields and you choose Merge, then post-import the Alerts modules will have 13 fields. Therefore, merge overwrites existing fields, adds new fields, and keeps non-imported fields.
    Replace Existing, replaces the existing configuration with the imported configuration, i.e., it overwrites existing fields, adds new fields, and deletes non-imported fields.
    Appends New Fields, keeps the existing fields as well as adds new fields, i.e., it keeps existing fields, adds new fields, and keeps non-imported fields
    Click the Review button to view the module's schema details and includes information about fields such as, which fields are replaced, which fields are retained, which fields are going to be created, and which fields are going to be ignored. You can therefore selectively decide what they want to do with fields that are different in the existing modules and in the configurations that they are importing. Select between various options such as Create field, Ignore field, Keep old version, or Delete field, or Overwrite with new version, etc., which are present in the Actions column of the respective fields and decide which fields are going to be imported.
    You can choose to sort how the fields are displayed in the grid by clicking the Sort drop-down list. The Sort drop-down list has the Default, A-Z, or Z-A options.
    Import Configurations - Detailed schema of existing modules
    Observations displayed for various fields: New Field Found: Fields that are present only in the configuration that you want to import, i.e., fields that are newly added to the configuration. Available user actions are Create field or Ignore field.
    Note: If you select Ignore field then the newly added field is not included in the mmd when you import the configuration.No Match Found: Fields that are present only in the existing module and not in the configuration that you want to import, i.e., fields that are deleted from the configuration. Available user actions are Keep field or Delete field.
    Note: Delete field will delete the field from the mmd file.
    • Matching Field Found: Fields that are present in both the configuration that you want to import and in the existing module, but which have different properties in the configuration that you want to import and in the existing module. These are fields that a user should replace with the newer version of the field. However, ensure that you review all the fields before choosing the import option since replacing a field with its newer version should not result in the publish failing due to for example, conversion of the field to an Unsupported type. Available user actions are Replace with new version or Keep old version.
    • System Field: Fields, whose properties cannot be changed by users. An example of a system field would be the First Name field in the People module, which cannot be changed by users. For more information on system fields, see Module Editor.
      Note: The name and properties of the Lookup (One to Many or One to One), Many to Many, and Many to One fields must not be changed once they have been defined. For example, the Alerts module contains a Many to Many with the Indicators field, and if in the configuration that you are importing the name of this field is changed to Indicator1 then the new field Indicator1 will not be imported.
      Once you have competed reviewing the import options, click Continue.
    Importing Picklists
    From release 7.2.0, you can choose to merge or replace picklists. These options are visible while importing picklists, if the picklist that you are importing already exists in the FortiSOAR environment:
    Importing Picklists
    If you choose Merge With Existing (default), the picklists items that are being imported get added in the existing picklist. If you choose Replace Existing, then the imported picklists replace the existing picklists.
  5. On the Review Import page, you can review the import details that you are importing, including details of which entities, views, etc., you are importing, the number of records being imported from modules, etc.
    Once you have reviewed the import details displayed by the Import Wizard, click Run Import to begin the import process or you can close the wizard. Clicking Run Import displays a configuration dialog, where you can click, I have reviewed the changes - Publish to import and publish the configuration into your FortiSOAR environment. Once the configuration publish begins, FortiSOAR displays the list of configurations being imported along with progress of the import. For example, Publishing Modules (36%) or Importing Connectors, etc., and once the process is completed the Import Process Completed Successfully message is displayed. If there are any issues with the configuration that you are trying to import then "Publish" operation fails and the wizard displays a message containing information about which configuration has failed such as Error while Importing Reports, and also the details of the error that caused the failure.
Note

While importing connector configurations, the system does not perform health checks to ensure that the connector configurations are accessible. Therefore, the import will show successful even if a connector's health check returns “Disconnected”. It is your responsibility to review the configurations of imported connectors to ensure they are active.

Points to be considered while importing modules

  • If a Tenant or Agent is imported then their status will be inactive you will need to re-configure the Master node on the tenant or agent.

  • The Secure Message Exchange is imported as configured, if the secure message exchange is reachable from the FortiSOAR system and there is no change to its certificates or credentials.

  • If you have edited a picklist on an environment (Env)1 and you import the Env1 configuration into Env2, in this case, the edited picklist items will be replaced.
  • If you have added a field, say test1, to Env1 and added a field, say test2, to Env2, to the Alerts module in both environments. Now, if you export the Alerts module from Env1 and import the Alerts module to Env2, then the Alerts module in Env2 gets completely overridden, i.e., the Alerts module in Env2 will now only contain the test1 field, and the test2 field gets overridden.
    You can also select the Merge option to retain fields that were present in an existing module but which are not present in the exported (new) module.

Updates required to be done after importing SSO configurations

If you have exported your SSO configuration and imported the SSO (SAML) configurations into a different FortiSOAR system, you require to make the following updates to the service provider portal, before SAML users can log into FortiSOAR:

  1. Update the "Single Sign On URL" to the URL of the system that is importing the SSO configuration.
  2. Update any other field in the service provider's portal that mentions the FortiSOAR system URL.
  3. Generate the X509 certificate for the FortiSOAR system that is importing the SSO configuration.

Once you have generated the X509 certificate, you must update the newly generated X509 certificate details on the SSO Configuration page in the FortiSOAR system that is importing the SSO configuration. To open the SSO Configuration page, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, in the X509 Certificate field update the details of the newly generated X509 certificate.

Application Editor

Use the Application Editor to configure data models contained in modules, to export and import configurations, visually display the nodes related to a particular record, customize your Picklist values, and the left navigation bar.

The Application Editor has following tools for this purpose:

  • Module Editor - for editing the data models in a module
  • Picklist Editor - for changing picklist values and color associations
  • Navigation Editor - for modifying the navigation links and hierarchy in the left navigation bar
  • Correlation Settings - for configure the display of the Visual Correlation widget.
  • Recommendation Engine - for predicting and assigning field values based on Artificial Intelligence/Machine Learning (AI/ML)
  • Configuration Manager - for exporting and importing configurations across environments
Note

To edit these settings, users must be assigned a role that has at a minimum of 'Read' and 'Update' permissions on the "Application" module.
If you want a user to be able to add modules also, then those users must be assigned a role that has at a minimum of 'Read,' 'Create,' and 'Update' permissions on the "Application" module.
To delete picklists or navigation items, you must have 'Delete' permissions on the "Application" module.
These privileges must be granted carefully as unintended application modification could result in data loss.

Module Editor

Use the Module Editor to add new modules and to add new fields and edit existing fields within a module. You can open the module editor by clicking Settings and in the Application Editor section, click Modules. This displays the Modules page.

Module Editor Interface

Important: Some fields in some modules are system fields and only FortiSOAR can create system fields. Changing the properties of the system fields could lead to issues with the working of FortiSOAR. Therefore, you cannot modify any properties of these fields, and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module as shown in the following image:

Field Editor tab- Read-only fields

Creating a New Module

To create a new module, click Settings > Modules. This displays the Modules page. Use the +Create new module option that appears at the top of the editor to define the properties of the module. By default, when choosing the Module Editor, the ability to define the new modules is available.

Adding a new Module

Bear in mind there are requirements to realize the addition of the new module, notwithstanding the need to allow for the interface to recognize this module.

From version 7.0.2 onwards, the process of creating a new module has been simplified so that users needs to provide only the Module Name while creating the module. Legacy fields such as table name, which could cause issues if incorrect inputs were provided are auto-generated. Simplification of module creation enhances user experience and also eliminates errors that occur due to incorrect inputs. In addition to this in case of the many to many relation field type, fields are by default added with same module name to the other side of related module, which simplifies the process of creating many to many relation fields. Also, now users only need to select the Related Module and provide the value in the Field Title field to create relation fields.

To add a module, do the following:

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.
  2. On the Summary tab configure the following fields for defining a module using the Module Editor.
    Note: To add any field to the Summary view, you must ensure that you have already added the field using the Field Editor. See the Modifying an existing module section for information on how to add and edit fields.
    1. Module Name: The name of the module itself, when it is in the singular context (individual record). For example, an Incident refers to an individual record in a module, whereas the module is Incidents.
      Once add the name of the module in the Singular context, the name of the module in the Plural context gets automatically populated.
      Note: The module 'Type' is also automatically populated based on the name you specify in the Singular field. Type is used to identify the module in the API.
    2. Display Template: This field uses an Angular Template expression to display a record appropriately. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ field_name_api }}.
      Important: Ensure that you add the fields that you specify in Display Template in the module that you are creating or updating. For example, if you have added {{ name }} in Display Template, then ensure that you have added Name as a field in the module, its Field Title (Field API Key)attribute will be set as name.
      Display Template
      You can also add an attribute of a picklist as part of the Display Template. See the following Display Template section for more details.
    3. Record Uniqueness: This section allows you to choose one or more published fields from the existing module that would be used to define a unique condition. This ensures that only unique records will be created in FortiSOAR and any record that matches the unique field or the combination of unique fields would not be created.
      For example, Type + Value is a unique combination in the Indicators module as shown in the following image:
      Application Editor: Summary Page - Record Uniqueness section
      This will ensure that indicator records will be created with unique "Type and Values" values.
      If you want to add any other field to for part of the unique combination of fields, then from the Record Uniqueness section, select that field from the Select a Field drop-down list, and then click Add Field. Similarly, if you want to remove any field from the unique combination, you need to click the red X on that field.
    4. Default Sort: Click Add Field to add a field based on which the list of records in the module will be sorted, either in the ascending or descending order. For example, indicators will be sorted based on when they were created, if you add Created On in the Default Sort section, as shown in the following image:
      Module Editor - Existing Incident module
    5. Team Ownable: Records that are ownable can be owned by a Team or Teams. An example of a module that you should make ownable is Incidents. If you do not select this option, then the records are not ownable and are publicly available and visible to any system user, without consideration of the user's team. An example of a module that you can make not ownable is Addresses.
      Note: Records that do not have any owners are visible to "All." If you change a module that was not ownable to ownable, then the records created before you have changed the ownership are visible to "All". However, until owners (teams) are assigned to the record, the record is read-only, i.e., fields in that record cannot be edited until a team is assigned to the record. Also, users' who are editing the same record (with no owners) must assign their team to the records to ensure that the records continue to be visible to those users and/or teams.
    6. User Ownable: Records that are user ownable can be owned by Users or Appliances. An example of a module whose records you should make user ownable is Alerts. If you do not select this option, then the records within this module will be visible to all users.
    7. Trackable: Selecting this option ensures that FortiSOAR tracks the date that the record was created, user who has created the record, date that the record was modified, and user who has modified the record on all records in the module.
      Important: Once a module has been created, you must not modify the Type and Table Name fields. You can edit the Singular and Plural names whenever required. However, note that the Singular name plus an s is used for API endpoint generation during module creation. Changing the Singular name could disrupt existing API calls to the endpoint.
    8. Indexable: Selecting this option ensures that this module has fields that can be indexed.
    9. Taggable: Selecting this option ensures that the selected module is taggable, i.e., you can enter tags to records in this module making it easier to search and filter records in the module.
    10. Enable Recycle Bin: Selecting this option enable soft deletion of selected module's records, i.e., records that are deleted from this module move to the recycle bin from where they can be restored, if needed. For more information on recycle bin, see the Recycle Bin chapter.
      Note: You cannot select the Enable Recycle Bin checkbox for system modules, i.e., for the 'People', 'Appliances', 'Agents', 'Approvals', 'Tenants', 'Routers', 'Comments', and 'Saved Reports' modules. Therefore, recycle bin for these modules cannot be configured and records of these modules are always permanently deleted.
    11. Queueable: Selecting this option ensures that this module is displayed as an option for auto-assignment while creating or configuring queues, i.e., records of this module can be auto-assigned using queues. For more information, see the Queue and Shift Management chapter in the "User Guide."
    12. Data Replication: (Only applicable to multi-tenant setups): Selecting this option enables replication of data for the selected module across peers' setups.
  3. On the Fields Editor tab, add the required fields to the module and click Save. See the Modifying an existing module section for information on how to add and edit fields.
  4. On the Summary tab, click Save to save the changes to save the changes to the module and publish the module to reflect the changes in the system. For information on the Save operation, see the Saving your changes section. For information on publishing, see the Publishing Modules section.
    To clear any changes made in the interface since the last Save event, click Revert.

Modifying an existing module

To modify an existing module, do the following:

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.
  2. To edit an existing module, from the Select a module to edit or create new module drop-down list, select the module.
    For example, select Alerts.
    Module Editor Interface
  3. To add fields to the module, or to edit any of the fields belonging to the module, add or update the fields on the Fields Editor tab on the Modules page.
    Editing Field Properties
    Some fields in some modules are system fields and changing properties of these fields could lead to issues with the working of FortiSOAR. Therefore, you cannot modify any properties of these fields and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module.
    From version 7.0.2 onwards, one-time edits are allowed for read-only fields, in the following cases:
    • If the value of the field had not been set, i.e., it is 'null' or 'blank'
    • If the field name is "tenant", and the field value is "self"
    One-time edits of read-only fields is required since there are scenarios where the value of the fields is not known at the time of record creation. An example of this is that at the time of record (alert) creation, the tenant to be mapped to the alert is not uniquely identifiable. Only after extraction and enrichment of the alert can the tenant be correctly determined. Therefore, now it is possible to change the tenant attribute of a record one time, if the current value is pointing to the local tenant ("Self").
    1. To add fields, on the Modules page, click the Fields Editor tab and click the Add (+) icon beside Fields.
      Note: The Fields Editor pane displays the list of fields that have been defined for the module. You can filter the fields by typing the search term in the Filter Fields textbox:
      Filtering Fields in the Fields Editor
    2. Define the following properties for the newly added field:
      • Field Type: The type of field; it specifies the type of form used to render this attribute. Examples of field types are text, file field, checkbox, integer, decimal, date/time, picklist, and relationship fields.
        It is recommended that when you create a field of type Integer, then you should set its default value as "zero".
        Use the JSON field type for fields such as, Source Data, which commonly store data in the JSON format to allow playbooks to get to the JSON data directly, without having to use a JSON parse step. You can also define the height of the JSON field in pixels by editing your record template.
        Based on the Field Type that you select, you can see an additional field. For example, if you select the field type as Picklist, a Picklist drop-down list will appear, and you must select the picklist associated with the field or click Create new picklist to add a new picklist. Use the Configure Picklist Option Visibility checkbox to filter a picklist field based on specified criteria. Once you check this checkbox, the picklist items are displayed and you can choose whether the item should be Visible, Disabled, Hidden, Conditionally Visible, or Conditionally Enabled. If you choose Conditionally Visible or Conditionally Enabled, you can then define the criterion when this item should be visible. An example would be displaying the Minimal option, in case of the Severity picklist, only if the type of alert is Other / Unknown:
        Configure Picklist Option Visibility
        FortiSOAR also supports a special type of picklist, called "Multiselect Picklist". You can use the multiselect picklist for fields that can contain more than one value. For example, you can have an alert be assigned more than one "Type", i.e., an alert can be of type Brute Force Alert and Malware. In such a case you can assign Multiselect Picklist as the Field Type for the "Type" field. You can then select an existing picklist from the picklist drop-down list, for example AlertType, or click Create new picklist to create a new picklist. You can also click Modify picklist to modify the existing picklist, by adding or removing picklist items or changing the properties of the picklist items.
        Field Type - Multiselect Picklist
        If you select Lookup (One to Many or One to One), Many to One, or Many to Many, a Related Model drop-down list will appear, and you must select the related module, and provide the Field Title before you publish the module.Also, in case of the Many to Many relation field type, fields are by default added with same module name to the other side of related module.
        Notes with respect to Relationship fields:
        • If you have added a Many to One relationship field on a module, then it is recommended that you set up a Lookup relation field on the related module for the modules to work as expected.
        • In the case of Lookup (One to Many or One to One) fields that have People as a related module contain the Filter Setting section. If you select the Only show users with record ownership checkbox in the Filter Settings section, then the list of users displayed in the lookup on the UI is restricted to include only those users who have record ownership. Further, you can also limit the list of users displayed in the lookup based on permissions given to the user on the module using the Limit ownership users to ones with module access to option. In the Limit ownership users to ones with module access to option, you can choose to display users who have Read access or Update (Read + Update) access.
          Filter Settings section
          Example: In the Alerts module, we have an Assigned To field, which is of type Lookup (One to Many or One to One) , with People as the related module. In this case by default, all users will be displayed in the Assigned To lookup, when you open an alert record. However, this could include users who belong to other teams, and who, therefore, would not have access to the record, even if you assign that record to that user.
          Therefore, to restrict the users to only those users who have access to the record, you can select the Only show users with record ownership checkbox. You can further restrict users displayed in the Assigned To lookup based on the module access. For example, if you want to display only those users who can update the record, in the Limit ownership users to ones with module access to field, select the Update checkbox (once you select the Update checkbox, the Read checkbox is automatically checked).
          You can drag and drop files in the "File Field" type field. An example of a "File Field" is "Email"; therefore, if you have an Email field in your record, then you can drag and drop an email to attach it to the record as shown in the following image:
          Example of an "File Field": Email
      • Sub Type: The "Sub Type" field can be used along with the Text and DateTime (from release 7.2.0 onwards) type fields.
        When you select DateTime in the Field Type, then the Sub Type drop-down list is displayed, from which you can select either Date Field or Date/Time Field as the sub types. Select the sub type as Date for fields that do not require the time component, and only require the date to be displayed. For Date fields, the time is considered as 12 A.M.
        Note: From release 7.2.0 onwards, DateTime fields, such as 'Created On', 'Modified On', etc. are stored with milliseconds precision (earlier it was seconds). If you have upgraded to 7.2.0, and users add new values to any existing DateTime fields, then those are stored with milliseconds precision; however, values in the DateTime fields that were present before the upgrade would yet be present in the old format, i.e., stored with the seconds precision.
        When you select Text in the Field Type, then the Sub-Type drop-down list is displayed, from which you can select the sub-types such as, Text Field, Rich Text (Markdown), Rich Text (HTML), Text Area, IPv4, IPv6, Domain, URL, or Filehash. The sub-type field enforces the format of data that the user can enter in that field. For example, in a Rich Text (HTML) or Rich Text (Markdown) fields, you can use formatting options or you can use the IP address and domain field types to lookup threat intelligence tools and whois info. You can also add images in the richtext fields (or in the Richtext Content widget); however, in case of .svg files, the Chrome browser does not restrict expansion of XML entities inside SVGs, which can rendering of image tag with any link in the href attribute that could case a client-side denial of service. Therefore, administrators can choose to not load SVG files enabled in HTML or Markdown Editors by updating the /opt/cyops-ui/vendor/config.json file using SSH. In the config.json file, update the value of the AllowSVGContent parameter to 'false'. In such a case the SVG will render as "<\\img src="https:\/\/link.svg">" in a richtext field, such as the 'Description' or the 'Comment' field.
        Note: For all modules, the default rich text editor is set to "Markdown", i.e., the Rich Text (Markdown) is selected for rich text fields. You can change the editor from markdown to HTML by selecting the appropriate sub-type for a field and then publish the module for the changes to reflect.
      • Field Title: A short descriptive name describing the item.
        TheField API Key is automatically created based on the value of Field Title field. The field can be alphanumeric and starts with a lower-case alphabet and does not contain any spaces, underscores or any special characters. Note that the value of this field does not get changed once the field has been created and the module has been published. This is because there is no migration path from the old name to the new name, so you risk data loss if this value is changed. Therefore even if you change the Field Title value the value of the Field API Key will not be changed.
        Note: If you have a field, in a module, whose Field Title (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.
      • Editable: Selecting this option allows you to modify the field after the creation of a module record. If this option is not selected, then you cannot modify the initial value after the record is created.
      • Delete Associations With Parent: Selecting this option cascades the deletion of a parent record to all the associated records for the Many to One relation type fields. For example, Events and Alerts have a Many to One relationship, i.e., one alert could have many associated events. If you select this option, then if an alert is deleted all its associated events also get deleted. Another example would be the case where one alert has multiple comments, and selecting this option cascade deletes the comments that are associated with a deleted alert.
        Warning: Select this option with caution since RBAC is Not applied for child records. For example, if you have Delete permissions on the Alerts module but not on the Events module, and you have selected this option, then deleting an alert with associated events, leads to the associated events getting deleted, irrespective of the permissions on the Events modules.
      • Searchable: Selecting this option makes this field searchable in the grid view.
      • Default Grid Column: Selecting this option makes the field appear as a column by default in the grid view. The order of the grid columns is defined by order of the fields in the Field Editor list. For information about grids, see the Dashboards, Templates, and Widgets section in the "User Guide."
      • Enable for recommendation: Selecting this option enables this field to accept values generated from the recommendation engine. Once you select this option, then an 'Auto populate' checkbox will appear beside this field while configuring data ingestion and also while creating or updating records using playbooks. This option appears for fields of type 'Picklist' and 'Lookup'.
      • Encrypted: Selecting this option enables encrypting of field values before storing in the database for enhanced security. FortiSOAR UI will continue to display the non-encrypted values. Currently, Text Fields, Email Fields, Rich Text Area and Text Area fields can be encrypted. FortiSOAR uses AES-256 encryption to encrypt and store the values in the database.
        Important: Once you enable encryption you cannot search the field values in FortiSOAR UI. Filters also will not work on encrypted fields. You also cannot use the upsert functionality for fields that are encrypted.
      • Required: Specifies whether the field is a required field.
        The options are: Not required, Required, or Required (by condition).
        Once you select Required (by condition), FortiSOAR displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR also supports advanced date operations and nested conditions for the Required (by condition) fields i.e., the Add Condition Group link is now available for these fields.
        Important: Do not choose the Visibility = Hidden option for Required (by condition) fields.
      • Visibility: Specifies whether the field is visible or not.
        The options are: Hidden, Visible and Visible (by condition).
        If you select the Hidden option, then the field is only accessible at the API level and not shown in the UI.
        If you select the Visible option, then the field is displayed on the UI. If you select the Visible (by condition) option, then the field is displayed on the UI only if the specific conditions are met.
        Once you select Visible (by condition), FortiSOAR displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR also supports advanced date operations nested conditions for the Visible (by condition) fields i.e., the Add Condition Group link is now available for these fields:
        Visible By Condition - Nested Conditions
      • Default Value: Specifies the default value of this field. Once you specify a value in this field, then this value will be displayed, by default when you add a record in the selected module.
        For example, if you want the status of a newly created alert to be set to Open, by default, then select the Status field and from the Default Value drop-down list, select Open as shown in the following image:
        Default Value option
        Once you set the default value, then whenever you add a new record in the Alerts module (in our example), then by default Open will be displayed in the Status field.
        In the Default Value field for the Date/Time field type you can specify either a Static date/time or a Custom date/time. If you select Static, click the Select Date icon to display the Calendar and select the required date/time. If you select Custom, then you can specify a date/time relative to the current date/time such as 1 hour from now, or 3 hours ago.
        Enhanced Default Value field for Date/Time field
        Note: In case you have upgraded to version 5.0.0 or later, then you will have to reselect your datetime default values, since the new datetime format is not backward compatible. You will be able to see the older applied datetime default value in the FortiSOAR fields. However, if you want to edit the default field, then you will have to specify the datetime again in the Default Value field.
      • Tooltip: Brief definitions that you can optionally add to fields. This definition is displayed when you click the information (i) icon of the field that has tooltip information added while creating, updating, or viewing records.
      • Length Constraints: In case of a Text field with sub-type set as Text Field or Text Area, you can specify length constraints by clicking the Add minimum/maximum range checkbox, if you want to override the default field length constraints by providing a minimum-maximum range for a field. Once you select the Add minimum/maximum range checkbox, you can specify the minimum character length for the field in the Minimum field and the maximum character length for the field in the Maximum field. You can enter any number from 0 to the maximum character length that is applicable for that field in the database. FortiSOAR will display a validation message if the maximum character length for the field is exceeded, or if the minimum character length for the field is not met.
      • Bulk Edit: Selecting the Allow Bulk Edit option to allow bulk edit operations on the selected field.
        For example, if you have selected the Severity field, in the Alerts module, and have clicked Allow Bulk Edit, this means the users can select multiple records in the grid view of the Alerts module and change the severity of those records to a particular severity level.
        You must enter the following details for the button that you want to use for the bulk edit operation:
        Button Text: In the Button Text field, type the name of the label that will be displayed on the bulk action button. For example, type Change Type.
        Button Icon: From the Button Icon drop-down list, select the icon that will be displayed on the bulk action button. If you do not want an icon to be displayed, select None.
        Button Classes: From the Button Classes drop-down list, select from the Default, Primary, Danger, or Warning styles.
        Allow Bulk Edit option
        Once you save the changes and publish the module, a Change Severity button is added to the Alerts module in the action bar. For more information on how to use the bulk action button, see the Working with Modules - Alerts & Incidents chapter in the "User Guide". You can add the bulk edit action button for any other fields, such as Status, Assigned To, and Type.
    3. Click Apply to add the field or click Revert to clear any changes made to the field since the last Save event or click Remove to remove the field.
      For information on the save and revert operations, see the Saving your changes section.
  4. You can also define the order of the default grid columns, which is defined by the order of the fields in the Fields Editor list. Fields are listed in the Fields column and you can drag-and-drop the fields to sequence the fields. You can also filter fields using the Filter Fields box.
    Defining the sequence of fields
  5. Click Save to save the changes to the module or click Revert > Revert to last saved to clear any changes made in the interface since the last Save event or click Revert > Revert to last published to clear any changes made since the last Publish event. For fields, you can revert only to the last published instance.
    For information on the save and revert operations, see the Saving your changes section.

Once you have completed making modifications to the module, you must publish the modules to reflect the changes in the system. This takes the system down for up to a few minutes while the changes are made. See the Publishing Modules section for more information.

Note

The Module Editor changes the relational database schema, therefore for changes to go live in the environment, you must perform a Publish to the database. This temporarily takes the application offline while the database operations are being performed. All users in the application must save their work prior to this occurring before this occurs or you risk data loss.

Display Template

A module's Display Template refers to one or more fields in the data model itself that is used to display a record in the general interface. Certain widgets, or visualizations in the interface, use the Display Template to identify records to the user. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ <*name of the module's field*>_name}}. If multiple fields are part of the display template, then you can specify multiple fields as {{field_name1,field_name2,…}}.

Note

If you were to use just the name of the module itself, such as Incidents, every Incident record in the interface would include a label named Incident. So, users see the Incident label with every record, which is not helpful. Therefore, we use Templates with a language to describe how to label your modules.

You can also include an attribute, such as itemValue, of a picklist field in the Display Template, add the following jinja: {{picklistFieldName.itemValue}} . For example if you want to include the status of the alert in the Display Template, then the picklist to be used would be AlertStatus, and the picklist field name would be status:

Example of adding jinja in Display template for picklists

Therefore you require to add the following jinja: {{status.itemValue}} in the Display Template.

Example

We have taken the Asset module as an example. Assets represent computing resources, typically on the network. Assets generally have a hostname, IP Address, or MAC Address. We are using the hostname as an example.

To create a Display Template for the Assets module with the hostname, you must ensure that you have already added the hostname field using the Field Editor. Once the hostname is added as a field in the Assets module, use the following expression in the Display Template field:

{{ hostname }}

The double curly braces, {{ }}, is used to identify a variable, specifically a field name. In our case, we are calling the hostname field. Any expression in the Display Template field that uses a field from the module data fields must use the double curly braces surrounding the field name. When the record is displayed, the hostname of each asset is used in the interface, so users know the asset they are selecting. For example, a user can know that they are selecting an HR Server.

Assets have a unique situation. They might only have one of those pieces of identifiable information depending on what is known about a resource. A laptop on a DHCP network might have only a MAC address. If we set the Asset Display Template to always be a hostname, in many cases the asset might have a blank Display Template in the interface. For these situations, the Angular Template expression allows you the flexibility to modify the format of the Display Template in a way that can account for variation. Taking the asset example, asset information is used to help users identify the asset when in the interface. Because using only a single asset field could potentially lead to a lot of blank Display Templates, we use multiple fields such as hostname, IP address and Mac address:

{{ hostname }} {{ ip }} {{ mac }}

This Display Template expression instructs the system to use all three fields based on their field names. If a field is not present, it displays as blank. In some cases, depending on what is known about the asset, the Display Template will include all three pieces of information, in others just one.

You can further extend this to display static information that identifies the parts of the Display Template. The following example includes the static text of Hostname:IP: and MAC: in every Display Template. This might be redundant but is an option.

Hostname:{{ hostname }} IP:{{ ip }} MAC:{{ mac }}

We recommend that to keep things simple, most of the time you would want to use the following expression for a Display Template, assuming you always create a name field for a module:

{{ name }}

This ensures that the Display Template points to whatever is in the name field on any module record. If you create name as a required field, then it will always be populated.

Saving your changes

Whenever you make any changes to a module or a field, you must stage those changes by saving. At the top-right of the Module Editor is the Save button, which applies any changes made to the staged data. To update the database and make your changes to go live, you must Publish the updated modules.

The Revert button clears any changes made in the interface since the last Save event. If you go into a module and realize that you have edited the wrong field, use Revert to clear the changes. However, once you press Save, you require to undo the changes manually.

Viewing your changes

Editing any of the fields of a module does not mean those fields are accessible immediately within the UI or the API. The fields must be first represented in the database. The templates included might automatically discover these fields, or these fields might need to be added manually to the template to specify their location within the interface. However, you can set the grid defaults within the attribute data for the model itself.

To update the database and make your changes to go live, you must Publish the updated modules.

Publishing modules

Whenever you change a field or a module and click Save, the change is staged but is not yet live in the system. You must perform a Publish to ensure that the changes are made in the system.

You initiate a publish action by clicking the Publish All Modules button at the top-right of the Module Editor page. Publishing pushes the changes that you have made to fields and modules to the database. Up until the Publish point, all changes to the data model in the Module Editor are saved as metadata, which is information that describes the structure of other information.

A Publish is the point at which the changes are truly irreversible, meaning that an unintended field deletion could cause irretrievable data loss. Use Publish carefully and verify changes before Publishing to avoid any problems.

Caution

"Publishing is a sensitive operation"
We recommend that you send a prior notification to all users of a publish since while the publish is in progress users are unable to work. We also recommend reviewing each staged change to ensure that only the desired changes are going to take effect.

If there is any error during the publish operation, FortiSOAR displays a meaningful error message at the top of the module editor, so that it becomes easier for you to resolve issues.

Note

If you have not selected an appropriate field from the Related Model drop-down list, for a Many to One, or a Many to Many field, then the publish operation will display an error.

Picklist Editor

Use the Picklist Editor to change the values of any picklist within the modules and add new picklists that might be referenced by a field in any module.

Unlike the Module Editor, changes made in the Picklist Editor are immediately live once they are saved. This is because Picklists names and Picklist values are records in the database.

A UUID (Universally Unique Identifier) identifies picklist values, which means if you modify any of the names or colors of an existing picklist value, the original data is preserved. Therefore, all records that contain that picklist value retains a reference to the UUID for the picklist. This means that if you want to change an Incident Category of Theft to Physically Stolen, you could make that change on the existing Theft value and any records with the value of Theft would now display Physically Stolen.

Picklist Editor

Creating or modifying a picklist

To add or modify a picklist:

  1. Click Settings and in the Application Editor section, click Picklists.
    This displays the Picklist Editor.
  2. Add or edit an existing picklist. To add a picklist, use the +Create new picklist option that appears at the top of the editor to define the properties of the picklist. Start by entering a title for the new picklist in the Title field.
    Or To edit an existing picklist, from the Select a picklist to edit or create new picklist drop-down list, select the picklist.
    For example, select AlertStatus.
  3. In the Items section, in the + Type and Press ENTER To Add New Picklist Item field, enter the name of the new picklist item and press Enter.
    For example, for the AlertStatus picklist, add items such as Open, False Positive, and Verified.
    Or
    To edit a picklist item, click the Edit icon that appears on the item row, update the name of the item or the color assigned to the picklist, and then click the green tick mark icon.
    Editing Picklist items
  4. (Optional) You can add colors to any picklist, by checking the Assign Colors checkbox. Once the Assign colors checkbox is enabled, you can assign each item in the picklist a color.
    Use the color picker box that appears next to each item in the picklist or enter the hexadecimal code for the color to edit the colors. You can use any valid HTML color.
    You can set the picklist color by directly entering the hexadecimal code of the color and assigning that as the picklist color, or by using an API, or you could choose colors by clicking in the color picker.
    The following image shows how to enter a hexadecimal code (#ff0000 for red color) in a picklist:
    Entering picklist colors using hexadecimal values
    Note: Multiple items in a picklist can have the same color.
  5. (Optional) You can also remove all items from the picklist by clicking the Removing All Items button, and you can also change the sort order of the picklist items clicking the Ascending or Descending order icon (Ascending or Descending Order icon).
    Picklist completed
  6. Click Save to save the changes made to the picklist or click Revert to clear any changes made to the picklist since the last Save event or click Remove Picklist to remove the picklist.
    You can also click the Audit Log button to view logs specific to a particular picklist. For more information on Audit Logs, see the System Configuration chapter.

Navigation Editor

Pages are iFramed resources that are accessible from the application interface by the user, such as resource pages and wikis within the local environment or on an accessible website link. Pages must currently be added in the modules API to be present to add in the Editor.

Use the Navigation Editor to modify the system Navigation bar, present on the left-side of the application interface.

Note

Changes that you make to the left navigation bar using the Navigation Editor affects all users. Currently, these changes cannot be made at a user-specific level.

Navigation Editor

There are two types of Navigation values:

  • Single-level navigation item, in which case an icon and title on the Navigation bar represent a module or page
  • Two-level navigation item, in which case an icon and title reveal a menu of additional options. Secondary navigation items might only have a name, not an icon.

You can add an external HTML page in an iFrame or a new tab and display that page as part of the left-navigation in FortiSOAR.

Modifying the Navigation bar

To modify the Navigation bar:

  1. Click Settings and in the Application Editor section, click Navigation. This displays the Navigation Editor.
  2. Add or modify the navigation bar:
    To add a single-level item, select module or pages by clicking the Modules or Pages tab, and click Add To Menu. Single level items on the menu must represent a 1:1 relationship with a module or page.
    To add a two-level item, select modules or pages by clicking the Modules or Pages button, and click Add As Group.
    The second-level navigation item is not a hyperlink or capable of referencing a given module or page. Only the sub-items in the group can be linked as a module or page. Clicking any two-level Navigation group shows and hides the sub-items.
    For example, you want to create a menu-group named Artifacts Management that has Attachments, Comment, and Scans as the menu items. You select the Attachments, Comment, and Scans modules and click Add As Group.
    This creates a menu group as shown in the following image:
    Example of a two-level menu group
  3. Edit the menu items by clicking the Edit icon that appears on the item row, update the name of the menu item or replace the icon of the first-level item in menu group, and click the green tick mark icon.
    You can replace icons by choosing icons from the icon selector at the left of each Navigation item.
    You can also delete a menu item by clicking the Delete icon.
    Example of editing a two-level menu group
  4. Drag-and-drop modules or module groups to change the order of the navigation items in the Navigation bar.
    Note: The top item of the navigation is always the default login page. By default, this is the dashboard page. However, you can modify this to make any other page the home page.
  5. To add an external HTML page in an iFrame or a new tab and display that page as part of the left-navigation in FortiSOAR, click the Pages tab and click the Add More link.
    Navigation Editor: Pages Tab - Add More link
    1. In the Title field, enter the name for the HTML page that you would want to display in the left navigation menu.
      For example, if you want to add a link to the Google website as part of your left-navigation in FortiSOAR, enter Google in the title field.
    2. In the URL field, enter the URL for the HTML page that you want to display in an iFrame or new tab. For our example, enter https://www.google.com.
    3. (Optional) If you want to open the page in a new tab, click the Open in New Tab checkbox.
      If the Open in New Tab checkbox is unchecked (default) the page will open in an iFrame in FortiSOAR.
    4. Click Add Page.
    5. On the Pages tab, select the page you have just added, Google in our example, and then click Add To Menu or Add As Group according to your requirements.
      Adding the HTML page to the Navigation Menu
  6. Click Save to save the changes made to the menu items or click Revert to clear any changes made to the menu items since the last Save event.

Correlation Settings

If you want to use the Visual Correlation widget to visually display the nodes related to a particular record, then you have to configure the display of the various related nodes on the Visual Correlation Setting page.

The following procedure is an example where you are configuring the display of tasks that have associated records.

  1. Click Settings and in the Application Editor section, click Correlation Settings.
  2. On the Visual Correlation Setting page, from the Choose Modules To Define Correlation View Configurations drop-down list, select the module for which you want to define visual correlations and then click Add and Configure.
    Note: FortiSOAR has pre-configured modules such as, Alerts, Assets, Incidents, Indicators, War Rooms, etc. The default depth of the nodes displayed is "3", i.e., if you start from the Alerts node, you view its related indicators and if those indicators have related assets, you can view those related assets. However, if that asset also has a related incident, then you can double-click on that asset node and see its related incident and so on.
  3. To configure the Campaigns module, from the Choose Modules To Define Correlation View Configurations drop-down list, select Campaigns and click Add and Configure.
  4. From the Choose Related Modules drop-down list, select the modules that should be shown in the correlation graph as linked modules, and then click Add Related Modules.
    Note: The modules that are pre-configured already have related modules configured, for example, the Alert module has Alerts, Incidents, Indicators, Vulnerabilities, and Assets configured as related modules.
    For our example, we require to add Alerts, Assets, and Incidents, as related modules to the Tasks module.
    Note: If you add a module that has not been configured for correlation, for example, the Comments module, then you will require to configure that module also before correlations can work. For example, if you choose the Comments module, then you must also configure the Node Label, Node Shape, and Node Color for that module.
  5. From the Node Label drop-down list, select the field that will be shown as a label for the node.
    For our example, choose Campaign Name.
  6. From the Node Shape drop-down list, select a shape that will be shown as the shape of the node.
    For our example, choose Square.
    You can also choose to specify a custom icon as the shape of the node. In this case choose Custom Icon from the Node Shape drop-down list and click Upload to display the Upload an Image dialog. In the Upload an Image dialog, drag-and-drop the icon file, or click the Import icon and browse to the icon file to import the icon file into FortiSOAR and then click Save Image to add the custom icon.
    You can also change the background shape of the custom icon by clicking the shapes present under Background shape of custom icon.
    You can also change the custom icon by clicking Change, which again displays the Upload an Image dialog.
    Note
    : The custom icon should be 15px X 15px and the file size must be less than 10KB.
  7. From the Node Color drop-down list, select the field that will conditionally determine the color of the node.
    For the pre-configured modules, such as alert, this field is set by default. For example, for the Alerts module, this is set as Severity. For the Campaign module, select Status.
    Note: In case of picklists the color of the node is determined by the color that you have assigned to the value of the picklist item. For example, if you have chosen the Priority as the picklist, then the colors that you have assigned to the selected picklist value will be used as the node color. For example, if the Priority is set as Urgent, then the node color will appear as Red, if its High, then the node color will appear as Orange, if its Medium, then the node color will appear as Yellow, etc. Therefore, if the task in which you have added the Visual Correlation widget is Critical, then its node color will be Red. For information on how to add the Visual Correlation widget in the records, see the Dashboards, Templates, and Widgets chapter in the "User Guide."
    You can also assign a custom color for the node by using the Choose custom color picker.
    Node Color - Custom Color picker
    If you do not specify any color, the node will appear with its default color.
  8. Next, you require to define how the related record node will also be displayed. For our example, we have chosen the Alerts and Incidents modules, as related modules all of which are pre-configured modules, so we do not require to configure any module.
  9. Click Save to save the settings for visual correlation.

Now, you can add the Visual Correlation Widget in the detail view of the Campaign records (see the Dashboards, Templates, and Widgets chapter in the "User Guide") to view the Correlations graph. The following image displays the "Visual Correlations" graph, which is an example of a Visual Correlation Widget being added to the detail view of Tasks records:

Display of the configured Visual Correlation Widget in the Tasks Details view

As you can see in the above image, the Correlations graph has a title which is Tasks: Correlated Records. The title can be specified by the user when they are adding the Visual Correlation Widget. The task for which correlated records are displayed is shown as a square node, whose color is determined by its severity, Red in this case since the task has priority set as "Urgent". The name of the task displayed as the label of the node. The associated records are displayed as various nodes, which is determined by the legend given in the left of the graph. The color of the nodes is determined by their "Severity" in case of Incidents and Alerts and "Asset Criticality" in case of Assets. For example, linked records whose severity is critical appear in red, high appear in orange, those that are medium appear in yellow, those that are low appear in green, and so on.

Recommendation Engine

FortiSOAR's Recommendation Engine empowers the product intelligence framework to suggest ranked threat similarities and field predictions, thereby helping to orchestrate better, informed, and holistic investigations. You can choose a suitable recommendation strategy and tune it to match your requirements. The Recommendation Engine analyzes your existing record data, recommends similar records, and predicts and assigns field values in records. From release 7.2.2, the Recommendation Engine also helps in predicting 'Phishing' emails, which improves triaging and the overall investigation process.

To view the 'Recommendation Engine' settings, click Settings, and in the Application Editor section, click Recommendation Engine:

Application Editor - Recommendation Engine
If you do not want FortiSOAR to predict or assign values to fields, display similar records, or predict 'Phishing Emails', then you can disable the 'Recommendation Engine' by toggling the Status button to 'Disabled'. By default, the 'Recommendation Engine' is enabled, i.e., the Status button is set to 'Enabled'.

Permissions required

To work with the Recommendation Engine and get record similarity, field predictions, and phishing classification using the ML engine, you must be assigned a minimum of Read permission on the Security module and on the module on which you require recommendations, and Read, Update, and Execute permissions on the Connectors module.

Record Similarity and Field Predictions

FortiSOAR provides you with the 'Recommendation Engine' that analyzes your existing record data using different algorithms to recommend similar records and predict and assign field values in records. It is based on finding similarities of patterns in historical data.

FortiSOAR provides you with two strategies for record similarity:

  • Elasticsearch Based Text Classification, which is based on analysis of similar records search using Elasticsearch's efficient algorithms to analyze the search results. This is the default recommendation engine.

  • Machine Learning Based Clustering, which is based on training the ML engine using the data existing on your FortiSOAR instance, and it uses traditional machine learning (ML) supervised classification algorithms such as 'K-Nearest Neighbors'.

Elastic Search Based Text Classification

On the Recommendation Engine > Record Similarity page, select either Elasticsearch Based Text Classification (default) as the recommendation strategy. For Elasticsearch Based Text Classification you do not need to configure anything, and FortiSOAR continues to predict and assign field values and display similar records as earlier releases. However, you can set up the record similarity and field prediction in the detail view of records based on which similar records and field predictions get displayed to all other users.

Setting up Record Similarity
  1. Open the Detail view of the alert record.
  2. Click the Workspace icon and then click the Recommendation tab:
    Recommendation tab
  3. To display similar records and specify the similarity criteria do the following:
    1. Click the Settings icon (Settings icon) on the Recommendations tab.
    2. In the Recommendations Settings dialog, on the Similar Records tab, ensure that the Show Similar Records Suggestions is toggled to On, which is the default.
      If it is not, then toggle Show Similar Records Suggestions to On as shown in the following image:
      Enabling Similarity
    3. In the Similarity Criteria section, choose the fields and relations to create the criteria based on which records will be displayed.
      For example, if you want to display the alerts whose indicators, such as domains, IP addresses, URLs, etc match the indicators of the alert record on which you are working and we also want to match the source of the alerts. Therefore, you will choose Indicators and Source from the Select Field drop-down list.
      You can also assign weights to the selected fields based on which the recommended similar records will be ranked. To assign ranks, select the Assign specific weights checkbox, then use the slider to assign weights for each of the selected fields from 1 to 10, with 10 being the highest value. For example, if you want to give higher weightage to similar Indicators as compared to Source, then you can assign a weight of 10 to Indicators and 5 to Source:
      Defining the Similarity Criteria
    4. (Optional) To filter the similar record suggestions, in the Filter Suggestions section, add the filter criteria. For example, if you only want to show similar records that have been created in the last month, then you can add the filter criteria as shown in the following image:
      Defining the filter criteria for similar records
      Adding filters narrows the records down to a smaller set, which in turn returns the results faster. For example, searching for similar records in the last one month will return results faster than searching for similar records in the last one year.
      Note: If you assign a "Custom" filter to a DateTime field, such as Assigned Date, then the date considered will be in the "UTC" time and not your system time.
    5. (Optional) In the Select Playbooks section, from the Choose Playbook list, search and select the playbooks that will be displayed on the Recommendations panel and which you can execute on similar records. For example, you can choose to evaluate indicators and therefore choose to run the Indicator Evaluation playbook on similar records.
    6. To define the layout of the similar records, in the Similarity Record Layout section, you can specify the fields of the similar records that you want to include. For example, you can choose Name, Severity, Assigned To, and Status, as the fields of the similar records that should be displayed.
      You can also define the color of the left border of the card based on a specific picklist or field in the Card Left Border Color Based On field. The color of the card will depend on the colors that you have defined for the picklist items. For example, choose Severity:
      Defining the Similarity Record Layout
    7. To save the similarity settings, click Save.

Based on the similarity criteria that has been defined, the Recommendation pane will display similar alerts as follows:

Recommendation pane - Display of similar alerts

Using the record similarity criteria set, users can view the list of records that are similar to the record that they are working on and can quickly perform various actions across all the similar records such as evaluating similar indicators across the module, marking all the records as 'Resolved', etc. For more information, see the Working with Modules - Alerts & Incidents and the Dashboards, Templates, and Widgets chapters in the "User Guide."

Setting up Field Suggestions
  1. Open the Detail view of the alert record.
  2. Click the Workspace icon and then click the Recommendation tab:
  3. To display prediction of values of fields and specify the criteria for the same, do the following:
    1. Click the Settings icon (Settings icon) on the Recommendations tab.
    2. In the Recommendations Settings dialog, on the Field Suggestions tab, ensure that the Show Field Suggestions is toggled to On.which is the default
      If it is not, then toggle the Show Field Suggestions to On, as shown in the following image:
      Enabling predicting values of field values
    3. In the Fields To Suggest On section, choose the fields for which you want FortiSOAR to predict the field values. For example, you can choose the Severity and Assigned To fields:
      Choosing the fields for prediction
      Important: Fields for which you want to predict values should not be fields that require some workflow or playbooks to be run if the value of the field is changed, since in this case though the value of the field gets updated, the complete workflow will not be completed. An example of such a type of field would be the Escalated field in the "Alerts" module and if you have added Escalated in the Field Suggestions, then even though you can change the value of the Escalated field in the record as per the field suggestions, which we are assuming is set to "Yes"; the complete Escalate workflow is not completed. In this case, even though the Escalated value of the alert record is set to Yes; however, the alert is not escalated to an incident, i.e., no corresponding Incident is created, and therefore the Escalate workflow of remains incomplete.
    4. To use the same criteria to form the field value suggestion as you have defined for similar records, ensure that the Use the same similarity criteria as set in similar record settings checkbox is selected (default).
      If you want to use a different criterion from the field value suggestion, then clear the Use the same similarity criteria as set in similar record settings checkbox. Then, in the Similarity Criteria section, choose the fields that would form the basis for predicting field values. For our example, choose the "Type" and the "Indicators" field.
      You can also assign weights to the selected fields based on which the recommended similar records will be ranked as described in the Setting up Record Similarity section.
      Defining the prediction criteria
    5. (Optional) To filter the field value suggestions, in the Filter Suggestions section, add the filter criteria. For example, if you only want to show similar records that have been created in the last 15 days, then you can add that as a filter criterion.
    6. To save the prediction settings, click Save.

Based on the prediction criteria that has been defined, the Recommendation pane will display field value suggestions as follows:

Recommendation pane - Field Value Suggestions

Using the field suggestions, users can choose to set the value of fields such as severity or assigned to, across all the similar records. For more information, see the Working with Modules - Alerts & Incidents and the Dashboards, Templates, and Widgets chapters in the "User Guide."

Machine Learning Based Clustering Text Classification

On the Recommendation Engine > Record Similarity page, select Machine Learning Based Clustering as the recommendation strategy. For Machine Learning Based Clustering, you need to train the ML engine using the data existing on your FortiSOAR instance. AI/ML technology can leverage past learning and similar patterns to smart predict values of record fields such as 'Assigned To' and 'Severity'. For example, for an incoming alert of type, Malware, your FortiSOAR system can fall back to similar Malware alerts that already existed in your system, and based on the similarity in patterns suggest values to the 'Assigned To' and 'Severity' fields in the new record. This saves time in a SOC as the task of sifting through records and assigning them is now done automatically.

Note

After you have upgraded your system to release 7.2.0 or later from a release prior to 7.2.0, and you observe that errors are being displayed for field suggestions and record similarity, then you must retrain your Machine Learning model.

To configure and train the ML engine, do the following

  1. On the 'Recommendation Engine' > 'Record Similarity' page, ensure that the Status of the Recommendation Engine is set to 'Enabled' and the Machine Learning Based Clustering option is selected.
    You will observe the FortiSOAR ML Engine is selected in the Selected Recommendation Connector drop-down list.
    Configuring the Recommendation Engine
  2. To configure FortiSOAR ML Engine, in the Configuration Name field, add a unique name for the configuration. The configuration name needs to be unique since you can have multiple configurations.
    Select the Mark As Default Configuration checkbox, if you want this particular configuration to be the default configuration of this connector, on this particular FortiSOAR instance.
    Note: You must select one configuration to be the default configuration of the FortiSOAR ML Engine connector.
    To add a new configuration, click the Select Configuration drop-down list and click + Add new configuration. You can specify different training datasets (modules) for each configuration and can also create different training schedules for the datasets for each configuration. However, as a best practice and for consistent results, you should have a single configuration per module.
  3. To train the FortiSOAR ML Engine, do the following:
    1. From the Module to train for drop-down list, select the module from which you want to select the fields for training and the fields that you want to predict. By default, the Alert module is selected.
    2. From the Feature Set list, select the field(s) using which you want to predict the field values. To select multiple fields, press Ctrl and select the field.
      For our example, where we want to predict the 'Assigned To' and 'Severity' fields based on the 'Type' of alert, select the Type field.
    3. From the Verdict list, select the field(s) that you want to predict. To select multiple fields, press Ctrl and select the field.
      For our example, we want to predict the 'Assigned To' and 'Severity' fields, therefore select the Assigned To and Severity fields.
    4. From the Date Range drop-down list, select the time range of records based on which you want to populate the training set.
      You can select from options such as Last Month, Last 6 months, Last year, etc. You can also select Custom and then specify the last X days to populate the training set.
    5. The Training Set Size specifies the number of records that make up the training set. It is set as 1000 records.
      Note: The value that you select from the Date Range drop-down list overrides this parameter
    6. From the Algorithm drop-down list, select the ML supervised classification algorithm using which you want to predict the fields. You can choose between K-Nearest Neighbors (default) or Decision Tree.
    7. In the Listener Port field, specify the port number of the socket where the ML Engine connector will load the ML models for efficient storage and delivery. By default, this is set as 10443.
      Recommendation Engine - Training Dataset
  4. Once you have specified the dataset to be used for training the FortiSOAR ML Engine, click Save & Train Model. Clicking Save & Train Model saves the specified parameters and trains the model, 'Alerts' in our example, based on these parameters.
    You will observe that the Configuration of the connector displays as Completed and the Heath Check of the connector displays as Available.
    Recommendation Engine - Configured along with the training dataset
    If you make any changes to the training dataset, such as adding or removing a field from the Feature Set or Verdict, click Train to update the dataset. To ensure that the dataset is trained on new incoming data regularly, you can also choose to train your dataset at regular intervals by scheduling training of the dataset by clicking Schedule. Clicking Schedule opens the Schedule Details dialog using which you can create a schedule for training your dataset. For more information on schedules, see the Schedules chapter in the "User Guide."

Once you have trained your dataset, FortiSOAR starts to analyze your dataset and based on the analysis displays records that are similar to the record you are working on, as well, predicts the values of field records that you have added to the Verdict field. Since we have trained the dataset, in our example, to predict the 'Assigned To' and 'Severity' fields based on the 'Type' field, FortiSOAR provides suggestions for those fields as shown in the following image:

Field Suggestions provided by FortiSOAR based on the recommendation engine

If you agree to the recommendations, then click the green check box beside the field, and that will populate that field in the record. For example, clicking the Severity green checkbox assigns 'Medium' as the record severity.

Assigning values to fields based on field suggestion

Similarly, you can view the list of records that are similar to the record that you are working on enabling you to quickly take remedial action. For more information on using record similarity and predicting values of field values in a record see the Working with Modules - Alerts & Incidents chapter in the "User Guide."

Phishing Classification

Phishing is probably the most common form of cyber-attack, largely because it is easy to accomplish, and surprisingly effective. It is a type of social engineering attack wherein an attacker impersonates to be a trusted contact and sends the victim fake mails. Therefore, in release 7.2.0, FortiSOAR introduces the 'Phishing Classification' feature. Phishing Classifier is a Machine Learning-based classifier that helps to predict emails that can be 'Phishing' emails, which helps speed up the triage and overall investigation process.

FortiSOAR provides you with two methods for training the 'Phishing Classifier' connector to predict phishing emails

  • Pre-trained Model: This model is trained using thousands of real-world phishing emails from Fortinet's security team. It is a quick-start way to understand the classification process.

  • FortiSOAR Module: This model is a new machine-learning (ML) model that you create by training your local dataset using an existing FortiSOAR module and its records.

Note

In the case of HA environments, all the training and predictions operations take place on the primary node.

Tooltip

You should configure the 'Phishing Classifier' on either your FortiSOAR node or your FSR Agent node, but not simultaneously on your FortiSOAR node and your FSR Agent node.

Administrators can see the Advanced Settings topic if they want to make some advanced changes such as changing the port used by the ML engine, or changing the normalization technique used by the phishing classifier.

Configuring Phishing Classification based on the Pre-trained Model

  1. On the 'Recommendation Engine' > 'Phishing Classification' page, ensure that the status of Recommendation Engine is set to Enabled. You will observe the Phishing Classifier is selected in the Selected Connector drop-down list.
    Recommendation Engine - Phishing Classification
  2. To configure the Phishing Classifier connector, in the Configuration Name field, add a unique name for the configuration. The configuration name needs to be unique since you can have multiple configurations.
    Select the Mark As Default Configuration checkbox, if you want this particular configuration to be the default configuration of this connector, on this particular FortiSOAR instance.
    Note: You must select one configuration to be the default configuration of the Phishing Classifier connector.
    If you have an existing configuration, then to add a new configuration, click the Select Configuration drop-down list and click + Add new configuration. You can specify different training datasets for each configuration and can also create different training schedules for the datasets for each configuration. However, as a best practice and for consistent results, you should have a single configuration per module.
  3. On the Configure Parameters tab, configure the following parameters:
    1. From the Type of Training Data drop-down list, select Pre-Trained.
      Choosing Pre-Trained means that you want to use the pre-trained dataset to predict 'Phishing Emails'.
    2. From the Display Predictions For Module drop-down list, select the module for whose records you want to display the predictions. For example, if you select Alerts, it means that you want to predictions for alert records.
    3. (Optional) To add further filtering on these records, click Add Data Filters and add additional filters. In this case, prediction will be shown for only those records that satisfy the filters. For example, add Type Equals Suspicious Email, to classify only those alerts whose type is suspicious email.
    4. In Feature Set Mapping, specify which fields of the module selected for prediction ('Alerts' in our example) maps to the ML model fields. You have to map the following fields: Email From, Email Subject, and Email Body.
  4. Once you have specified the configurations for training the Phishing Classifier connector, click Save Configuration, which saves the specified parameters and begins training the model, 'Alerts', in our example, based on these parameters. At this step, the pre-trained model is loaded into memory for predictions. If this operation is successful, the 'Heath Check' of the connector displays as 'Available':
    Pre-Trained Model - Phishing Classification Configuration Complete
  5. Click the Model Performance Summary tab to view the performance of the model in terms of precision per class:
    Model Performance Summary Page

Configuring Phishing Classification based on a FortiSOAR Model

  1. Configure the Phishing Classifier connector as mentioned in steps 1 and 2 of the Configuring Phishing Classification based on the Pre-trained Model section.
  2. After you have configured the Phishing Classifier connector you need to specify its training dataset:
    1. From the Type of Training Data drop-down list, select FortiSOAR Module.
      Choosing FortiSOAR Module means that you want to use the data from your FortiSOAR instance to predict 'Phishing Emails'.
    2. From the Module to Train For drop-down list, select the module for which you want to train the data. For example, if you select Alerts, then alert records existing in your system are used to train the model, and then subsequently predictions will be displayed on the alert records.
    3. (Optional) To add further filtering on these records, click Add Data Filters and add additional filters. In this case, prediction will be shown for only those records that satisfy the filters. For example, add Type Equals Suspicious Email, to classify only those alerts whose type is suspicious email.
    4. From the Date Range drop-down list, select the time range of records based on which you want to populate the training set.
      You can select from options such as Last Month, Last 6 months, Last year, etc. You can also select Custom and then specify the last X days to populate the training set.
    5. The Training Set Size specifies the number of records that make up the training set. It is set as 1000 records.
      Note: The value that you select from the Date Range drop-down list overrides this parameter.
    6. In Feature Set Mapping, specify which fields of the module selected for prediction ('Alerts' in our example) maps to the ML model fields. You have to map the following fields: Email From, Email Subject, and Email Body.
    7. In this case, since you are using an existing module for training, the model needs to know the classification of each email before the training. For this, you must specify which values of the field constitute as phishing and which constitute as non-phishing. Therefore, in Verdict Field Mapping, map the values of the picklist (field) in Phishing and Non-Phishing buckets that you want to train as the verdict of the model.
      By default, for the Alerts module a picklist named 'Email Classification' is added that has two items, Phishing and Non Phishing, which can be used by the users to classify the record:
      Phishing Classification - FSR Module Default Field Mapping and Verdict Mapping
      However, you can choose any other picklist (field) based on which you want to classify emails. For example, you can choose the verdict field as 'Type' and then in the 'Phishing' bucket put alerts whose type is Brute Force Attempt, Denial of Service, or Policy Violation, and in the 'Non Phishing' bucket put alerts whose type is Compliance.
      Phishing Classification - FSR Module Field Mapping and Verdict Mapping for the 'Type' field
  3. Once you have specified the dataset for training the Phishing Classifier connector, you can click Save & Train Model or Save Configuration.
    Clicking Save Configuration saves the specified parameters.
    Clicking Save & Train Model saves the specified parameters and also begins to train the model, 'Alerts', in our example, based to these parameters. Once the training is completed, the 'Heath Check' of the connector displays as 'Available':
    Phishing Classification - FSR Module Training Completed
    If you make any changes to the training dataset, such as adding or removing a field from the Verdict Field Mapping, click Train to update the dataset. To ensure that the dataset is trained on new incoming data regularly, you can also choose to train your dataset at regular intervals by scheduling training of the dataset by clicking Schedule. Clicking Schedule opens the Schedule Details dialog using which you can create a schedule for training your dataset. For more information on schedules, see the Schedules chapter in the "User Guide."

Once you have trained your dataset, FortiSOAR starts to analyze your dataset and based on the analysis displays suggestions on whether or not an alert record can be classified as a 'Phishing' record as shown in the following image:
Alert Details View - Phishing Suggestion
Open the detail view of an alert record, and click the Recommendations tab on the Workspace panel, to see a Suggestion section that contains the Is this Phishing? question followed by the answer to that question and the corresponding confidence level. For example, in the above image, the answer to the Is this Phishing? question is Yes, with 99% confidence that it is a phishing email (record). Using this suggestion and its corresponding confidence value it becomes easy for analysts to classify records into 'Phishing' and 'Non Phishing' and accordingly proceed with the investigation process.

Note

In the case of HA environments in which a 'Takeover' operation has been performed; post-takeover, you have to retrain data on the new primary node to use the machine learning services to predict phishing suggestions.

Notes with respect to FSR agents:

  • If you have installed and configured the Phishing Classifier connector on an agent node, and not on the FortiSOAR (base) node, then suggestions are not displayed in the Recommendations tab on the Workspace pane; however, you can use the agent configuration in connector actions in playbooks to get the predictions.

  • As FSR agents need to interact with modules to display suggestions, you require to modify the FortiSOAR Agent role to include access to the modules for which predictions are configured. For example, if you have set up predictions for the 'Alerts' module, then you must update the FortiSOAR Agent role with the minimum of Read permissions on the 'Alerts' module.

Advanced Settings

  • By default, the ML engine runs on port 10449. If the same port is occupied by some other process in the system, then the administrator can change the port number in the SERVER section of the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file, and then restart the uwsgi service.
  • The TFIDF section in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file enables the administrator to provision controlling the frequency of a word in the corpus. A term is excluded from the feature set if it does not satisfy the min_df (minimum document frequency) or max_df (maximum document frequency). If you update the TFIDF section, then you must restart the uwsgi service.
    For more information, see https://scikit-learn.org/stable/modules/generated/sklearn.feature_extraction.text.TfidfVectorizer.html
  • Words that are included in the ignore_words field in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file are excluded from the feature set. This allows administrators to exclude organization-specific words that should not be part of the feature set. If you make any changes to the ignore_words field, then you must restart the uwsgi service.
  • Words that are included in the function_words field in the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file contain words that are generally found in phishing emails. Administrators can update words that are part of the function_words field. If you make any changes to the function_words field, then you must restart the uwsgi service.
  • As part of pre-processing, unimportant words are removed from the data and the words are converted to their base forms to avoid redundancy. There are two methods to achieve this normalization: 'stem' and 'lemmatize'. By default, the Phishing Classifier uses the 'stem' method. You might want to change the normalization technique to lemmatize if you think that it might improve the prediction accuracy. To change the normalization technique to lemmatize, do the following:
    1. Download the nltk data file on your FortiSOAR instance from https://repo.fortisoar.fortinet.com/downloads/scripts/nltk_data.tar.
    2. Copy the downloaded .tar file to the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/ folder.
    3. Untar the nltk data file using the following command:
      tar -xvf nltk_data.tar
    4. Provide appropriate permissions to the nltk data file using the following commands:
      chmod -R 654 /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/nltk_data
      chown -R nginx:nginx /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/resources/nltk_data
    5. In the /opt/cyops-integrations/integrations/connectors/phishing-classifier_1_0_0/ml_service/config/config.ini file, update the value of the word_normalization_technique parameter from stem to lemmatize.
    6. Restart the uwsgi service and retrain the model.

Export and Import Wizards

FortiSOAR provides you with a wizard-based export and import of record data, configuration information, dashboards, application settings, etc., which enhances the user experience and improved architecture. These enhancements also allow for scheduled, API-based export and imports. For information about the export and import APIs, see the API Methods chapter in the "API Guide."

FortiSOAR version 7.0.0 enhances the Import and Export Wizards to support the import and export of templates, installed connectors, connector configurations, widgets, teams, and users.

From version 7.0.2 onwards, the export wizard creates a zip file for all the exported content. Prior to version 7.0.2 content was exported in the JSON format. You can use both the zip and JSON (for content exported from a FortiSOAR system prior to 7.0.2) to import content using the Import Wizard. The zip file contains a folder for each entity that is exported, along with a json file (export.metadata.json) that contains metadata information such as the FortiSOAR version from which the content was exported, user who exported the content, datetime of when the content was exported, etc.

For example, if you have exported the alerts and incidents modules configurations, record data for the alerts and incidents modules, some dashboards, and some roles, the folder structure will be as follows:

FortiSOAR Export DatetTme folder
--+ modules
---+ alerts
------+ detail-layout.json
------+ form-layout.json
------+ list-layout.json
------+ mmd-layout.json
---+ incidents
------+ detail-layout.json
------+ form-layout.json
------+ list-layout.json
------+ mmd-layout.json
---+ records
------+ alerts
---------+ alerts0001.json
----+ incidents
---------+ incidents0001.json
---+ dashboards
------+ System Dashboard.json
------+ T1 Analyst.json
---+ roles
------+ T1 Analyst-<UUID>.json
------+ Security Administrator-<UUID>.json

Important: The record set file will have maximum 100 records.

Permissions required

  • To export and import record data and configurations using the Wizards or APIs, users who will be performing the import/export operations must be assigned a role that has Create, Read and Update permissions on the Application, Security, and Playbook modules.
    • Users who require to import files must additionally be assigned a role that has Create and Read permissions on the Files module.
    • Users who require to import connectors must additionally be assigned a role that has Create, Read, and Update permissions on the Connectors module.
    • Users who require to export connectors must additionally be assigned a role that has Read permissions on the Connectors module.
  • If a playbook is running the import and export using the API, your playbook appliance also requires the same permissions.

Export Wizard

You can use the Export Wizard to export modules information such as record data, module metadata, field definitions, picklists, view templates, etc. of your modules. You can also export playbook collections, dashboards, reports, and administrative settings such as, application configuration, system views, etc.

To export configurations, do the following:

  1. Click Settings and in the Application Editor section, click Export Wizard.
    This displays the Export Wizard page.
    Configuration Export page - Export Templates page
    To import an exported template, click the Import button
  2. To begin a new export for configurations and create an export template, click the Export Templates tab, and then click New Export Template.
    This displays the Choose Entities page in the Export Wizard, in which you can choose all or any of the entities such as modules, playbooks, dashboards, etc. that you want to export.
    To run an existing configuration again, click the Run icon in the Actions column, which displays the "Run Export' screen of the Export Wizard using which you can rerun an existing configuration.
    To edit an existing configuration, click the Edit icon in the Actions column, which displays the "Choose Entities" screen of the Export Wizard using which you can edit the configurations you want to export as per your requirements. To delete an existing configuration template, click the Delete icon in the Actions column.
    If you want to use a playbook to schedule exporting configurations using an existing export template, you will require to add the UUID of the export template in the playbook. You can get the UUID of the export template by click the Copy UUID to Clipboard icon in the Actions column.
    The Export History page displays a list of configurations that have been exported:
    Configuration Export page - Export History page
    To download the exported file in the zip format, click the Download icon in the Actions column, and to delete a configuration file, click the Delete icon in the Actions column.

Exporting Modules and/or picklists

From version 7.0.2 onwards, export and import of record data is supported. The ability to export and import all data and configurations enables creating a near-exact replica of a FortiSOAR environment.

Note

The maximum number of records that can be exported is 100000 per module. Also, note that importing a large number of records can greatly increase the duration of the import, and before you start exporting records, ensure that there is sufficient space in the /tmp/ folder.

  1. On the Choose Entities page, in Export Wizard, select Modules and click Continue.
    Export Wizard - Choose Entities page
    Note: You can choose to export one, all, or multiple entities.
  2. On the Filter Data page, click the Modules option, and select the modules that you want to export. You can choose to export one, all, or multiple modules. You can also choose to export record data and all or any of the configuration information associated with a module, i.e., the module's schema, listing view, record view, and add views.
    The List View, Detail View, and Add View exports the configuration information of the templates that you have created for the selected module(s). The Records exports the record data of the selected module(s). You can choose whether you want to export the correlation data along with the module's data. If you want to export the correlation data, then click Correlations.
    Important: When you are exporting (or importing) Queues or Shifts, you must select the Queues and Shifts module as well as their records. Queues and Shifts are exported as records and the configuration of the Queue Management page is exported using the System View Template. For more information on Queue and Shifts, see the Queue and Shift Management chapter in the "User Guide."
    To include all the selected entities, click the Include Everything checkbox. In this case, it exports the record data for all the modules and all its associated configuration information including the module's schema, views, and all the picklists.
    Note: You cannot export or import record data for the system modules, i.e., the People, Appliances, and Approvals modules.
    To export module configurations, choose the modules and their related configurations you want to export. From release 7.2.0 onwards, you can choose to export selective fields from a module. Click the Review button to select the fields that you want to export; by default, all fields are exported. For example, if you do not want to export the 'Bytes Transferred' and 'Vulnerability Severity' fields, clear those check boxes:
    Export Wizard - Selective exporting of fields
    You will also observe that the Auto-Select Required Picklists checkbox is selected by default since the picklists associated with the module must also be exported when you are exporting the configuration information for the modules to ensure there are no issues when you import the configuration to another environment. Therefore, for example, if you select Schema for the "Alerts" module, you will observe that "9" picklists that are required for the "Alerts" module are automatically selected.
    To export record data, click the Modules menu item, and in the Choose Modules and Views to Export table choose the modules whose record data you want to export. For example, if you want to export records of the 'Alerts' module, click Records in the 'Alerts' module row:
    Exporting Alert Data
    Once you click Records, an Add Filters link and a Correlations button are displayed. If you want to export the records' correlations such as the records' related incidents, assets, etc., then click the Correlations button. You can also choose to filter the records you want to export, allowing customization of which records to export. To filter records, click the Add Filters link. For example, if you do not want to export alert records that are 'Closed', you can add that filter in the Filter Alerts dialog. You can also update the maximum number of records you want to export in the Limit field, the default being 100 records (maximum 100000),and also choose how you want to sort the exported data, by selecting a field from the Default Sort drop-down list. Once you have competed filtering the records, click Update Query.
    Note: If a record set is included in the export, then the module schema for that record set is required and gets automatically included in the export.
    Filtering alert data while export
    Click the check boxes in the header row to perform bulk actions. For example, clicking the Export All checkbox selects all the modules their associated configurations, but not their record data. Similarly, clicking the Schemas checkbox in the header row changes Export to Yes for all modules and selects the schema for all the modules.
    To enable export of configurations and record data for a particular module, in that module's row, toggle the Export button to Yes, which selects all the configuration information associated with a module, i.e., the module's schema, listing view, record view, and add views. If you do not want to export some configuration information, for example, add view, toggle the Add View button to disable exporting the add view configuration.
    Note: The export and import wizards do not take care of data replication settings for modules. For example, in the case of an MSSP system, on a tenant node, if you have set up data replication on the 'Comment' Module, and if you export this module and import it to another system, you will observe that the data replication flag is not set for the 'Comment' module.
    If you want to export only picklists, click the Picklists menu item, and select the picklists you want to export. Using this menu item, you can export the picklists that are not associated with any module.
    Note: When you import a picklist, by clicking Import Wizard and if that picklist already exists on your system, then the "Import Wizard" replaces the existing picklist.
    Once you have complete choosing the modules and picklists that you want to export, click Continue.
  3. On the Review Export page, you can review the record data and configuration information that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the specified configuration information in a zip file that you can download and use in another environment, or click Save to save the configuration information.
    FortiSOAR also displays warnings if there are any inconsistencies in the data, such as templates not found, to be exported. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the specified configuration information as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard in which you can edit the configurations you want to export as per your requirements.

Exporting Playbooks and/or Global Variables

You can export playbook collections and global variables. Currently, you have to export the complete playbook collection, and cannot select specific playbooks to be exported from within a playbook collection.

  1. On the Choose Entities page, in Export Wizard, select Playbooks and click Continue.
  2. On the Filter Data page, select the playbook collections and/or global variables that you want to export.
    In the Choose Playbook Collections and Global Variables To Export page, in the Playbook Collections section, click the Playbook Name checkbox to select or deselect all the playbook collections. To export specific playbook collections, select those playbook collections. To include versions of your playbooks while exporting playbook collections, click the Include Versions checkbox.
    Similarly, in the Global Variables section, click the Global Variable Name checkbox to select or deselect all the global variables. To export specific global variables, select those global variables.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the playbook collections and global variables.
    Once you have complete choosing the playbook collections and/or global variables that you want to export, click Continue.
  3. On the Review Export page, you can review the playbook collections/global variables that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the playbook collections/global variables in a zip file that you can download and use in another environment or click Save to save the playbook collections/global variables. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the playbook collections/global variables configuration as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import a playbook collection, by clicking Import Wizard, and if that playbook collection exists, you can choose to either overwrite the existing playbook collection or create a new playbook collection and appending the original playbook collection name with a number. For more information, see Importing configurations.
    When you import a global variable, by clicking Import Wizard and if that global variable already exists on your system, then the "Import Wizard" replaces the existing global variable.

Exporting Dashboards, Reports, Rules, and Rule Channels

  1. On the Choose Entities page, in Export Wizard, select Dashboards, Reports and Rules & Channels, and then click Continue.
  2. On the Filter Data page, select the dashboards, reports, rules & channels that you want to export.
    Click the Dashboards menu item, and in the Choose Dashboards To Export table, click the Dashboard Name checkbox to select or deselect all the dashboards. To export specific dashboards, select those dashboards.
    Similarly, click the Reports menu item, and in the Choose Reports To Export table, click the Report Name checkbox to select or deselect all the reports. To export specific reports, select those reports.
    Click the Rules menu item, and in the Choose Rules To Export table, click the Rule Name checkbox to select or deselect all the rules. To export specific rules, select those rules.
    Similarly, click the Rule Channels menu item, and in the Choose Rule Channels To Export table, click the Rule Channel Name checkbox to select or deselect all the rules. To export specific rule channels, select those rule channels.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the dashboards and reports.
    Once you have complete choosing the dashboards and/or reports that you want to export, click Continue.
  3. On the Review Export page, you can review the dashboards, reports, rules, and rule channels that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the dashboards, reports, rules, and rule channels in a zip file that you can download and use in another environment or click Save to save the dashboards, reports, rules, and rule channels. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the dashboard/report template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import dashboards, reports, rules, or rule channels, by clicking Import Wizard and if that dashboard or report already exists on your system, then the "Import Wizard" replaces the existing dashboard or report.

Exporting Connectors

You can export connectors that are installed on your system. You can export connector installation and their configurations. From version 7.0.2 onwards, you can also export and import .tgz files of widgets and connectors. If a connector version is not found in the global connector repository, then the export wizard will export the .tgz file of the connector instead of the 'rpm' name. Similarly, if a widget version is not found in the widgets repository, the export wizard will export the .tgz file for the widget.

Caution

Password and API keys are NOT encrypted during export, which means that anyone who has access to the exported file will be able to access the connectors. Therefore, you must be careful while exporting the connector configurations.

  1. On the Choose Entities page, in Export Wizard, select Connectors and click Continue.
  2. On the Filter Data page, select the connectors that you want to export. You can choose to export one, all, or multiple connectors. You can also choose to export the configuration information associated with a connector.
    Click the Connectors menu item, and in the Choose Connector To Export table, select the connectors that you want to export. To export both the installation and the configuration for a particular connector, in that connector's row, toggle the Export button to Yes. If you want to export only the configuration for a connector, then toggle the Installation button to disable exporting the installation for that connector, or toggle the Configurations button to disable exporting the configurations.
    Click the checkboxes in the header row to perform bulk actions. For example, clicking the Export All checkbox, selects all the connectors their associated configurations. Similarly, clicking the Configuration checkbox in the header row, changes Export to Yes for all connectors and selects the configurations for all the connectors.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports the installations and configurations for all the connectors.
    Once you have complete choosing the connectors that you want to export, click Continue.
  3. On the Review Export page, you can review the connectors that you are exporting, and can also specify the name of the template that you are exporting, as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the connectors in a zip file that you can download and use in another environment or click Save to save the connectors.
    If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the connector template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.

Exporting Widgets

You can export widgets that are installed on your system. From version 7.0.2 onwards, users can also export and import .tgz files of widgets and connectors. If a widget version is not found in the widget repository, then the export wizard will export the .tgz file for the widget.

  1. On the Choose Entities page, in Export Wizard, select Widgets and click Continue.
  2. On the Filter Data page, select the widgets that you want to export. You can choose to export one, all, or multiple widgets.
    Click the Widgets menu item, and in the Choose Widgets To Export table, select the widgets that you want to export, and click Continue.
  3. On the Review Export page, you can review the widgets that you are exporting, and can also specify the name of the template that you are exporting, as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the widgets in a zip file that you can download and use in another environment or click Save to save the widgets.
    If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the widget template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.

Exporting Administrative Settings and System Views

You can export system views, and administrative settings with the customizations that you have applied across your FortiSOAR instance. For example, you can export your application settings such as branding and notifications, SSO, LDAP, Radius configurations, proxy and environment variables, etc.

Tooltip Passwords are write-only fields and therefore they cannot be exported using Configuration Manager. Therefore, if for example, you have exported your LDAP configurations and imported that into another FortiSOAR system, then since the passwords are not copied, you have to manually enter the passwords for all the users to be able to perform any activity related to users, such as searching for users or updating details of users.
  1. On the Choose Entities page, in the Export Wizard, select Administrative Settings and click Continue.
  2. On the Filter Data page, select the roles and/or settings that you want to export.
    Click the Administrative Settings menu item, and in the Choose Administrative Settings To Export table, in the Administrative Settings section, click the Settings Name checkbox to select or deselect all the administrative settings. To export specific administrative settings, select those administrative settings.
    Similarly, Click the System Views menu item, click the Views Name checkbox to select or deselect all the system views. To export specific system views, select those system views.
    You can choose to customize the navigation structure you want to export. Click the Review button to display the items included in the navigation and then select the individual items from the navigation to export the custom navigation:
    Export Wizard - Exporting a custom navigation
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the system views and administrative settings.
    Once you have complete choosing the settings, and administrative settings that you want to export, click Continue.
  3. On the Review Export page, you can review the settings that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the settings/views in a zip file that you can download and use in another environment or click Save to save the settings. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the settings template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    When you import the exported configurations into a system, all the application settings that were applied on the system from which the application settings were exported get applied on the system where you import and install the settings. For example, if the system from which the application settings were exported had its "Audit Log Purge" enabled with the logs to be retained for the last month, the same Audit Log policy will apply on the system in which you import and install the application settings.
    Important: If you have exported your SSO configuration and imported the SSO (SAML) configurations into a different FortiSOAR system, you require to make certain updates before SAML users can log into FortiSOAR. For more information, see Updates required to be done after importing SSO configurations.
    Note: When you import the queue management configuration system view or any administration setting by clicking Import Wizard, and if the queue management configuration system view or administrative setting already exists on your system, then the Import Wizard will overwrite the same. In the case of the navigation structure, you can choose to merge or replace the navigation structure in your system.

Exporting Security Settings

You can export security settings, which includes users, teams, and roles, that are present in your FortiSOAR instance.

From version 7.0.1 onwards, access type information, i.e., named or concurrent, is also exported along with the other user details, and the same are accordingly imported. If users are being imported from a version earlier than 7.0.1, i.e., 7.0.0, then those users do not have any access type information, and in this case, these users are imported as 'named' users.

  1. On the Choose Entities page, in the Export Wizard, select Security Settings and click Continue.
  2. On the Filter Data page, select the roles, teams, or users that you want to export.
    To export roles, click the Roles menu item, and in the Choose Roles To Export table, click the Role Name checkbox to select or deselect all the roles.
    To export specific roles, select those roles. You can export roles such as Full App Permissions, Application Administrator, T1 Analyst, Security Administrator, etc.
    From version 7.0.2 onward, you can choose to export specific module access for a particular role. For example, if you want to export the 'SOC Analyst' role, without having access to the 'Announcements' module, select the SOC Analyst role, then click the Review button, to display all the module permissions associated with this role. Clear the Announcements checkbox to remove the permissions associated with the Announcements module. When you import this role to another FortiSOAR system the 'Announcements' permissions for the SOC Analyst role will be removed:
    Exporting a role with specific permissions for a selected module
    To export teams, click the Teams menu item, and in the Choose Teams To Export table, click the Team Name checkbox to select or deselect all the teams. To export a specific team, select that team.
    Similarly, to export users, click the Users menu item, and in the Choose Users To Export table, click the Name checkbox to select or deselect all the users. To export a specific user, select that user.
    To include all the selected entities, click the Include Everything checkbox. In this case it exports all the roles, teams, and users.
    Once you have complete choosing the roles, teams, and users that you want to export, click Continue.
  3. On the Review Export page, you can review the roles, teams, and users that you are exporting, and can also specify the name of the template that you are exporting as well as the name of the zip file that you want export. If you change the template name, the file name automatically gets updated as per the template name specified.
    Once you have completed reviewing the information, click Save & Run Export to export the roles, teams, and users in a zip file that you can download and use in another environment or click Save to save the settings/roles. If you have clicked Save & Run Export, then the record of export configuration that has been run is added as an entry in both the Export Templates and Export History pages. If you have clicked Save, then FortiSOAR saves the roles, teams, and users template as a record entry only in the Export Templates page. You can edit this configuration at any time by clicking the Edit icon in the Actions column, which again displays the Export Wizard using which you can edit the configurations you want to export as per your requirements.
    Note: When you import a role, user, or team by clicking Import Wizard, and if that role, user, or team already exists on your system, the Import Wizard will overwrite the existing role, user, or team.

Import Wizard

You can use the import wizard to import record data, configurations or metadata information for modules, playbook collections, dashboards, etc. from other environments into FortiSOAR. Using the import wizard, you can move model metadata, picklists, system view templates, dashboards, reports, roles, playbooks, and application settings across environments.

Importing configurations

The following section provides an example of importing modules. You can import dashboard, system views, playbooks, etc., using the same method.

Note

To import configurations into FortiSOAR the configurations file must be in the JSON/ZIP format. FortiSOAR ensures that you either revert or publish staged changes prior to importing configurations so that there are no issues during the import process.

  1. Click Settings and in the Application Editor section, click Import Wizard.
    This displays the Import Wizard page.
    Configuration Import Page
    If you close the wizard without clicking Run Import, then the status of your import will display as "Reviewing", and you can click the Continue icon in the Actions column to display the "Configurations" screen of the Import Wizard, and you can continue review of the import configurations. If you have clicked Run Import, and the import process is completed, then the status of your import will display as "Import Complete". You can also the configuration at any time by clicking the Reimport icon in the Actions column to display the "Configurations" screen of the Import Wizard.
  2. Click Import From File.
    This displays the Upload File page in Import Wizard. On this page, drag and drop the JSON or ZIP file, or click the Download icon and browse to the JSON or ZIP file to import configurations into FortiSOAR. If the JSON format is incorrect, FortiSOAR displays an error message and not import the file. If the JSON format is correct, FortiSOAR imports the configurations and displays details of what is being imported on the Configurations page.
  3. On the Configurations page, choose the configurations that you want to import, and click Continue.
    Import Configurations - Configurations page
  4. Importing Configurations:
    Importing Dashboards, Reports, Widgets, Rules, Rule Channels, System Views, Administrative and Security (User, Team, Role) Settings:
    To import Dashboards, Reports, Rules, or Rule Channels on the Options page, click the Dashboards or Reports menu item. The "Observation" column displays whether the dashboards or reports that you are importing are "New" or "Existing". Click the Dashboard Name or Report Name checkbox to select or deselect all the dashboards or reports, or click the checkbox alongside the individual dashboard or report name to import particular dashboard or report.
    If you are importing Dashboards and or Reports, then apart from displaying whether it is an existing or new dashboard or report, you can assign a default role to the dashboard or report:
    Import Configurations - Dashboards
    The Options page for Widgets, Rules and Rule Channels, Roles, Users, and Teams are similar to the Dashboards page, except that their Options page does not have any role assignment drop-down list.
    Important: Concurrent users are imported as per their original state, i.e 'Active' or 'Inactive'; whereas named users are imported in the 'Inactive' state. Administrators must change their state manually to 'Active' as required. Also, from version 7.0.1 onwards, access type information, i.e., named or concurrent, is also imported along with the other user details. If users are being imported from a version earlier than 7.0.1, i.e., 7.0.0, then those users do not have any access type information, and in this case, when these users are imported they are imported as 'named' users.
    The Options page for Administrative Settings, System Views, Teams, Users, Roles, and are also similar to the Dashboards page, except that the Administrative Settings and System Views pages do not have the "Observation" column.
    Use the <Name of the Option> Name checkbox to select or deselect all the configurations of a particular type on their respective pages. For example, if you want to import all the administrative settings, click the Administrative Settings menu item, and then in the Administrative Settings section, click the Setting Name checkbox to select or deselect all the administrative settings.
    In the case of System Views, click the System Views menu item, and then click the View Name checkbox to select or deselect all the system views. In the case of Navigation Structure, you can choose to Merge (Default) or Replace the navigation structure existing in your system. Merge appends the extra navigation items available in the import configuration to the navigation structure existing in your system. Replace replaces your existing navigation structure with the items and structure that are specified in the import configuration. If you have selected the Merge option, then you can also selectively choose to Skip or Append (Default) individual navigation items by clicking the Review button:
    Import Wizard - Navigation Structure items - Append or Skip
    Important: If dashboards, reports, global variables, widgets, roles, uses, teams, system views (apart from navigation structure), rules, rule channels, or administrative settings that you are importing already exist in your system, then the Import Wizard overwrites the configurations of these entities in your system. In the case of widgets, when you try to import a specific version of a widget using the import configuration file, and that widget is not present in the FortiSOAR repository, then the latest version of that widget gets installed in your FortiSOAR system.
    Importing Connectors:
    To import connectors, on the Options page, click the Connectors menu item. The "Choose Connectors to Import" page displays whether the connectors that you are importing are "New" or "Existing":

    - If the connectors are new, then the connector import installs and configures the connector on your system.
    - If the connectors are existing, and if the version of the installed connector on your system is the same or higher, then the connector import replaces only the connector configuration on your system.
    - If the connectors are existing, and if the version of the installed connector on your system is the lower, then the connector import upgrades the connector on your system and replaces its configuration with the imported configuration.
    - If the connectors are existing, and if the version of the installed connector on your system is the same or higher, and you are importing a connector with no configuration information, then nothing is replaced on your system.
    Click the Import All checkbox in their respective sections to import all the connectors and their configurations in the respective 'Existing Connectors' or 'New Connectors' section. Similarly, click the Installation and Configuration checkboxes in the header to import all the installations and all the configurations respectively.
    Toggle Import to Yes in a connector row to import that connector's installation and configuration and similarly toggling off the Install or Configuration buttons does not import the said installation or configuration.
    Importing Playbook Collections and Global Variables:
    To import playbook collections, on the Options page, click the Playbook Collections menu item. Currently, you have to import the complete playbook collection, and cannot select specific playbooks to be imported from within a playbook collection. The playbook collections and global variables page displays the list of "New Playbook Collections", "Existing Playbook Collections", "New Global Variables" and "Existing Global Variables". In case of new playbook collections and global variables, click the Import All checkbox in their respective sections to select or deselect all the new playbook collections and global variables. To import particular playbook collections or global variables, click the checkbox alongside the individual playbook collections or global variables. In case of existing playbook collections, apart from the Import All checkbox in the header, the Import Wizard also displays the following the "Bulk Actions" that you can take for existing playbook collections: Replace Existing Collections, Replace Existing Collection (append number), Merge Collections (replace existing playbooks) or Merge Collections (skip existing playbooks), which is the default option. You can choose to apply this action across all the playbook collections you are importing or you can choose the action to be performed for each playbook collection that you are importing:
    - If you retain Merge Collections (skip existing playbooks) action, then the Import Wizard merges the playbook collection by skipping the existing playbooks. For example, if have exported a 'Demo' playbook collection, that has a two playbooks 'Create Demo Records' and 'Test Manual Input', and you are importing this into a system that has the 'Demo' playbook collection with the 'Create Demo Records' playbook, then the Import wizard merges the 'Demo' playbook collection such that it will not overwrite the 'Create Demo Records' playbook; however it will add the 'Test Manual Input' playbook.
    - If you choose the Merge Collections (replace existing playbooks) action. then the Import Wizard merges the playbook collection by replacing the existing playbooks. For example, if have exported a 'Demo' playbook collection, that has a two playbooks 'Create Demo Records' and 'Test Manual Input', and you are importing this into a system that has the 'Demo' playbook collection with the 'Create Demo Records' playbook, then the Import wizard merges the 'Demo' playbook collection by overwriting the existing 'Create Demo Records' playbook and adding the 'Test Manual Input' playbook.
    - If you choose the Replace Existing Collections action, then the Import Wizard overwrites the playbook collections in your system.
    - If you select Replace Existing Collections (append number), then the Import Wizard creates a new playbook collection and appends a number to the original playbook collection name. For example, if you have exported a playbook collection named 'Demo' and you are importing the same playbook collection with Replace Existing Collections (append number) selected, then the imported collection will automatically be created as a new playbook collection named as 'Demo (1)'.
    Import Configurations - Playbook Collections
    Importing Record Data:
    To import record data, on the Options page, click the Record Set(s) menu item. The Options page displays the module name for which the records are being imported, the count of records to be imported, and the overwrite settings, i.e., you can choose to either Overwrite records if they exist or can choose to skip records if they exist.
    Import Wizard - Importing Record Data
    Note: If a record set is included in the import, then the module schema for that record set is required and gets automatically included in the import.
    Importing Modules Configurations and Picklists:
    When you import configurations for existing modules, and if the modules that you are importing contain fields that conflicts with the existing fields that prevent some fields from being imported, then those modules are displayed in Existing Modules With Conflicts section as shown in the following image:
    Import Configurations - Modules Page - Existing Modules With Conflicts
    Modules whose fields have no conflicts with existing fields are displayed in the Existing Modules Without Conflicts section as shown in the following image:
    Import Configurations - Modules Page
    Choose the options in the header row to perform bulk actions. For example, if you want to import all the modules, click the Import All checkbox, etc.
    For schemas of the modules that you are importing, you can choose if you want to Merge With Existing configurations, Replace Existing configurations, or Append New Fields to the configurations. You can click the Review Field Level Actions icon to view the detailed schema of the module you are importing.
    Merge With Exisiting, merges then the configurations, i.e., for example if you are importing an existing module, say Alerts, which has 3 new fields in the configuration that you are importing and 10 existing fields and you choose Merge, then post-import the Alerts modules will have 13 fields. Therefore, merge overwrites existing fields, adds new fields, and keeps non-imported fields.
    Replace Existing, replaces the existing configuration with the imported configuration, i.e., it overwrites existing fields, adds new fields, and deletes non-imported fields.
    Appends New Fields, keeps the existing fields as well as adds new fields, i.e., it keeps existing fields, adds new fields, and keeps non-imported fields
    Click the Review button to view the module's schema details and includes information about fields such as, which fields are replaced, which fields are retained, which fields are going to be created, and which fields are going to be ignored. You can therefore selectively decide what they want to do with fields that are different in the existing modules and in the configurations that they are importing. Select between various options such as Create field, Ignore field, Keep old version, or Delete field, or Overwrite with new version, etc., which are present in the Actions column of the respective fields and decide which fields are going to be imported.
    You can choose to sort how the fields are displayed in the grid by clicking the Sort drop-down list. The Sort drop-down list has the Default, A-Z, or Z-A options.
    Import Configurations - Detailed schema of existing modules
    Observations displayed for various fields: New Field Found: Fields that are present only in the configuration that you want to import, i.e., fields that are newly added to the configuration. Available user actions are Create field or Ignore field.
    Note: If you select Ignore field then the newly added field is not included in the mmd when you import the configuration.No Match Found: Fields that are present only in the existing module and not in the configuration that you want to import, i.e., fields that are deleted from the configuration. Available user actions are Keep field or Delete field.
    Note: Delete field will delete the field from the mmd file.
    • Matching Field Found: Fields that are present in both the configuration that you want to import and in the existing module, but which have different properties in the configuration that you want to import and in the existing module. These are fields that a user should replace with the newer version of the field. However, ensure that you review all the fields before choosing the import option since replacing a field with its newer version should not result in the publish failing due to for example, conversion of the field to an Unsupported type. Available user actions are Replace with new version or Keep old version.
    • System Field: Fields, whose properties cannot be changed by users. An example of a system field would be the First Name field in the People module, which cannot be changed by users. For more information on system fields, see Module Editor.
      Note: The name and properties of the Lookup (One to Many or One to One), Many to Many, and Many to One fields must not be changed once they have been defined. For example, the Alerts module contains a Many to Many with the Indicators field, and if in the configuration that you are importing the name of this field is changed to Indicator1 then the new field Indicator1 will not be imported.
      Once you have competed reviewing the import options, click Continue.
    Importing Picklists
    From release 7.2.0, you can choose to merge or replace picklists. These options are visible while importing picklists, if the picklist that you are importing already exists in the FortiSOAR environment:
    Importing Picklists
    If you choose Merge With Existing (default), the picklists items that are being imported get added in the existing picklist. If you choose Replace Existing, then the imported picklists replace the existing picklists.
  5. On the Review Import page, you can review the import details that you are importing, including details of which entities, views, etc., you are importing, the number of records being imported from modules, etc.
    Once you have reviewed the import details displayed by the Import Wizard, click Run Import to begin the import process or you can close the wizard. Clicking Run Import displays a configuration dialog, where you can click, I have reviewed the changes - Publish to import and publish the configuration into your FortiSOAR environment. Once the configuration publish begins, FortiSOAR displays the list of configurations being imported along with progress of the import. For example, Publishing Modules (36%) or Importing Connectors, etc., and once the process is completed the Import Process Completed Successfully message is displayed. If there are any issues with the configuration that you are trying to import then "Publish" operation fails and the wizard displays a message containing information about which configuration has failed such as Error while Importing Reports, and also the details of the error that caused the failure.
Note

While importing connector configurations, the system does not perform health checks to ensure that the connector configurations are accessible. Therefore, the import will show successful even if a connector's health check returns “Disconnected”. It is your responsibility to review the configurations of imported connectors to ensure they are active.

Points to be considered while importing modules

  • If a Tenant or Agent is imported then their status will be inactive you will need to re-configure the Master node on the tenant or agent.

  • The Secure Message Exchange is imported as configured, if the secure message exchange is reachable from the FortiSOAR system and there is no change to its certificates or credentials.

  • If you have edited a picklist on an environment (Env)1 and you import the Env1 configuration into Env2, in this case, the edited picklist items will be replaced.
  • If you have added a field, say test1, to Env1 and added a field, say test2, to Env2, to the Alerts module in both environments. Now, if you export the Alerts module from Env1 and import the Alerts module to Env2, then the Alerts module in Env2 gets completely overridden, i.e., the Alerts module in Env2 will now only contain the test1 field, and the test2 field gets overridden.
    You can also select the Merge option to retain fields that were present in an existing module but which are not present in the exported (new) module.

Updates required to be done after importing SSO configurations

If you have exported your SSO configuration and imported the SSO (SAML) configurations into a different FortiSOAR system, you require to make the following updates to the service provider portal, before SAML users can log into FortiSOAR:

  1. Update the "Single Sign On URL" to the URL of the system that is importing the SSO configuration.
  2. Update any other field in the service provider's portal that mentions the FortiSOAR system URL.
  3. Generate the X509 certificate for the FortiSOAR system that is importing the SSO configuration.

Once you have generated the X509 certificate, you must update the newly generated X509 certificate details on the SSO Configuration page in the FortiSOAR system that is importing the SSO configuration. To open the SSO Configuration page, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, in the X509 Certificate field update the details of the newly generated X509 certificate.