Fortinet Document Library

Version:


Table of Contents

FortiSOAR™ Built-in connectors

0.0.0
Copy Link

Overview

FortiSOAR™ provides you with a number of pre-installed connectors or built-ins that you can use within FortiSOAR™ playbooks, as a connector step, and perform automated operations. 

These connectors are bundled and named based on the type of operations the connectors can perform. For example, the Database connector would contain actions that you can perform with respect to the database like querying the database. It is easy to extend and enhance these connectors. 

Important: Before you upgrade your FortiSOAR™ version, it is highly recommended that you take a backup of your FortiSOAR™ Built-in connector's (SSH, IMAP, Database, etc.) configuration since the configuration of your FortiSOAR™ Built-in connectors might be reset if there are changes to the configuration parameters across versions.

Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as Splunk and Ticketing systems such as Jira. You can see a list of published connectors on the Fortinet Support Site. After logging on the Support Site, click the Knowledge Base tab and then click Connectors to view the list of connectors published by Fortinet. 

FortiSOAR™ in version 6.0.0 has refactored the output of some operations of some built-in connectors such as the "Email: Extracts email's metadata from email file" operation of the Utilities connector. Due to refactoring, there have been some changes to the output of the Utilities connector which are not backward compatible. For example, the body key in the response now returns a dictionary with keys 'json', 'html' instead of an array of these. It is recommended to switch to the new format. However, if you want to retain the old output format, and you have only upgraded the connector version and not upgraded your FortiSOAR™ version, then you must do the following:

  1. Append the following in the /opt/cyops-integrations/integrations/configs/config.ini file:
    [connector_configuration]
    extract_email_metadata_legacy: true

    The output of the "Email: Extracts email's metadata from email file" operation is determined by the extract_email_metadata_legacy parameter. If the extract_email_metadata_legacy parameter is set as true then the output will be generated in the old format, and if it is set as false, then the output will be generated in the new format.
  2. Add the following at the end of the /opt/cyops-integrations/integrations/integrations/settings.py file:
    APPLICATION_CONFIG = application_config
  3. Restart the uswgi service using the following command:
    # systemctl restart uwsgi

Important: If you are upgrading to FortiSOAR™ 6.0.0, then you need to perform only steps 1 and 3.

Configuring the FortiSOAR™ Built-in connectors

To configure FortiSOAR™ Built-in connectors, you must be assigned a role that has a minimum of Update access to the Connectors module.

The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the FortiSOAR™ documentation or click see the Configuring a connector article.

Upgrading the FortiSOAR™ Built-in connectors

FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. You should use the Connector Store from version 5.0.0 onwards to upgrade your connectors to the latest version. For more information on the connector store, see the Introduction to connectors chapter.

Prior to version 5.0.0, you could upgrade a connector on an existing version, i.e, without upgrading FortiSOAR™, by running the following command as a root user:

# yum update cyops-connector-<connector name>

For example, # yum update cyops-connector-cyops-imap

Important: After you upgrade to FortiSOAR™ 6.0.0 and before you reconfigure ingestion for the same connector configuration, you must deactivate the earlier ingestion playbooks that are present in the ingestion collection for the connector. The links to the ingestion playbooks that were created prior to the upgrade will be present on the System Fixtures page in the "Ingestion Playbooks" section will not be visible in the Data Ingestion tab (new in version 6.0.0) of the "Connectors" page. If your data ingestion is schedule-based, then you must also stop or delete the earlier schedules for the connector.

Built-in connectors

The following built-in connectors that are included by default in FortiSOAR™:

For some of the operations, enhancements, bug fixes, and various versions of the built-in connectors see the Release Notes section.

Utilities 

Use this connector for performing operations in FortiSOAR™, such as performing a FortiSOAR™ search using the Query API, updating a FortiSOAR™ resource, and creating a FortiSOAR™ resource. This connector also contains other useful utilities such as extracting email metadata such as indicators from an email file, uploading a file to FortiSOAR™ and associating that file with an attachment, i.e., providing the File IRI in the output, converting file formats, such as XML to JSON or CEF to JSON, and zipping and password protecting a file.

This connector is ready to use, and you do not need to configure this connector.

Note: Any file that is downloaded on the agent using the download file action of the Utilities connector will not be available to any of the next steps in the playbook. For example, if you create a playbook add then add the Utilities connector operation "File: Download File From URL" step for an FSR Agent configuration, add the download URL, and save the step. Next, you add the "File: Create Attachment From File" step in which provide the file reference from "Download" step and save and run the playbook. The playbook will fail with an error such as "Connector step is failing with error 'Invalid input :: Given filename/filepath /tmp/f68ab00fb7da4dfd9db4bb95abb1471e doesn't exists'". This is expected behavior since when a file download operation is performed on an FSR agent, the operation cleans the file when the response is returned to the base FortiSOAR™ node. Therefore, if any following step expects the downloaded file to be present at the agent will cause that step to fail. For more information on FSR agents, see the Segmented Network Support chapter in the FortiSOAR™ documentation.

An example of the utilities that are included in the Utilities connector is the "Utils: Convert JSON into an HTML table" utility. This utility generates an HTML-formatted string based on the input JSON. The HTML-formatted string will appear as follows:

<table class="cs-data-table">
<tr>
<th>pid</th>
    <th>path</th>
    <th>username</th>
  </tr>
  <tr>
    <td>4</td>
    <td>c:\\windows\\system32\\ntoskrnl.exe</td>
    <td>NT AUTHORITY\\SYSTEM</td>
  </tr>
  <tr>
    <td>296</td>
    <td>c:\\windows\\system32\\smss.exe</td>
    <td>NT AUTHORITY\\SYSTEM</td>
  </tr>
</table>

For the given input JSON: 

{
"operation": "get_process_list",
"data": [
    {
        "path": "c:\\windows\\system32\\ntoskrnl.exe",
        "create_time": 1529090266,
        "command_line": "",
        "parent_guid": "00000004-0000-0000-0000-000000000000",
        "proc_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
        "parent": 0,
        "username": "NT AUTHORITY\\SYSTEM",
        "pid": 4,
        "sid": "s-1-5-18"
    },
    {
    "path": "c:\\windows\\system32\\smss.exe",
    "create_time": 1529090266,
    "command_line": "\\SystemRoot\\System32\\smss.exe",
    "parent_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
    "proc_guid": "00000004-0000-0128-01d4-04dd8ae6291c",
    "parent": 4,
    "username": "NT AUTHORITY\\SYSTEM",
    "pid": 296,
    "sid": "s-1-5-18"
    },
    "status": "Success",
    "message": ""
}

For some of the operations, enhancements, bug fixes, and various versions of the Utilities connector see the Utilities Connector Release Notes section.

Database 

Use this connector to connect to a database and then query the database and retrieve data. You can connect to multiple databases by setting up multiple configurations. 

Note: If you have externalized your PostgreSQL Database, then you will require to update the host information and the credentials in the database connector configuration page, based on the credentials that you have specified for your externalized PostgreSQL database. For more information on the externalization of PostgreSQL Database, see the Externalization of your FortiSOAR™ PostgreSQL database chapter in the FortiSOAR™ documentation.

For some of the enhancements, bug fixes, and various versions of the Database connector, see the Database Connector Release Notes section.

IMAP 

Use this connector to set up multiple email accounts and fetch emails from different email accounts.  

Important: Before you enable the Enable Email Notification Service option in the IMAP connector configuration, ensure that you have activated the Custom API Endpoint trigger playbook that you have specified in the IMAP connector configuration.

If you want the IMAP connector to read emails from your Spam folder also, then you must specify the complete path on the email client, since Spam is not the main folder in any email client. For example, if your email client is Gmail, then set the Email Source as [Gmail]/Spam.

Note: The IMAP builtin connector is dependent on the Utilities connector. Therefore, if you remove the Utilities connector, the IMAP connector will not work.

For some of the operations, enhancements, bug fixes, and various versions of the IMAP connector see the IMAP Connector Release Notes section.

SMTP 

Use this connector to setup SMTP for sending system notifications, including requests for resetting passwords, and also for sending emails outside FortiSOAR™. When you configure the SMTP connector, you must ensure that the Mark As Default Configuration option for the configuration that is to be used for sending system notifications is selected.

You can send emails to 30 most recently created FortiSOAR™-teams or users by selecting teams or users from a pre-populated drop-down list using the Recipient Type drop-down list.

If you select Manual Input from the Recipient Type drop-down list, then you can specify a comma-separated list of email addresses, including email addresses of non-FortiSOAR™ users. However, you can also specify the IRI values for users and/or teams, which allows users to reuse team or user information defined in previous playbook steps as Jinja statements.

If you select Team from the Recipient Type drop-down list, then you can send emails by selecting existing FortiSOAR™ teams from the pre-populated To, CC, or BCC multi-select fields, which enables users to dynamically leverage the email ID which has already been provided in a team record, and the email can be sent to all the members of the team at once.


If you select User from the Recipient Type drop-down list, then you can send emails by selecting existing FortiSOAR™ users from the pre-populated To, CC, or BCC multi-select fields, which enables users to dynamically leverage the email ID which has already been provided in a user record. So now you have the ability to interchangeably send emails in multiple formats by specifying a comma-separated list of email addresses or selecting FortiSOAR™-teams or users, or by reusing team or user information defined in previous playbook steps as Jinja statements.

You can pass an existing email template as an input for the email subject and body (content) allowing you to leverage an existing email template and build upon it, and thereby, avoiding re-work and ensuring consistency. The Send Email step contains a Body Type drop-down list from which you can choose whether you want to send a plain text email (Plain Text), rich text email (Rich Text), or an email based on a template (Email Template).

If you select Rich Text from the Body Type drop-down list, then in the Content field, you can add formatted content, images, and even custom jinja expressions using Dynamic Values:

If you select Email Template from the Body Type drop-down list, the Email Template drop-down list is displayed, using which you can select the template that you want to use to send the email:

For some of the operations, enhancements, bug fixes, and various versions of the SMTP connector see the SMTP Connector Release Notes section.

SOAP

Use this connector to make SOAP calls by sending SOAP functions and receiving data. 

The SOAP connector (version 2.3.0) contains a full-fledged SOAP client that reads WSDL from the configuration and populates the list of actions and all the required/optional inputs from WSDL. Therefore, now you can use the newly added SOAP Call action to integrate SOAP web services with FortiSOAR™. To use the SOAP client, from the Action drop-down list select SOAP Call, then select the SOAP Service that you want to use, based on which you select the Port Type and the Function Name, after which all the required or optional parameters get displayed. The headers list gets populated and even the output schema of this step gets populated in the next steps of the playbook according to the function you have selected. A new field "Additional SOAP Headers" is added to the SOAP Call action, using which you can specify any extra headers, which are required for the requests.

Important: This new feature, i.e., the SOAP Call action, is supported for FortiSOAR™ version 6.4.1 and later.

The SOAP connector also has the SOAP Call (Generic) action that is present for backward compatibility, where you could specify a SOAP function and define its parameters. A new field "Additional SOAP Headers" is added to the SOAP Call (Generic) action, using which you can specify any extra headers, which are required for the requests.

For some of the enhancements, bug fixes, and various versions of the SOAP connector see the SOAP Connector Release Notes section.

SSH 

Use this connector to connect to different servers and execute commands and python scripts on those servers.  

For some of the enhancements, bug fixes, and various versions of the SSH connector see the SSH Connector Release Notes section.

Code Snippet

Use the Code Snippet connector to run a python function as part of playbooks. 

To configure this connector, click Automation > Connectors in the left-navigation, and on the Connectors page, click the Code Snippet connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details.

If you check the Allow All Imports checkbox, then users can import all python modules, and users are required to include the import statement for any modules they want to use. 

If you clear the Allow All Imports checkbox, then in the Allow Following Imports field, users can specify the list of modules that they want to import. Users can then use these modules, without having to include the import statement in the python code. Note that, in this case, users will not be allowed to import modules that are not part of the list of specified modules.

Add the "Code Snippet" connector in a playbook as a connector step and execute a python code as part of a playbook. 

If the value of the variable that you are defining in the python code is a string, then you must add double-quotes. For example:
description = "{{vars.input.records[0].description | striptag}}"

If the value of the variable that you are defining in the python code is a dictionary or array, then you can use is without double-quotes. For example: 
description = {{vars.input.records[0].description | striptag}}

You must add the print statement to the python code. The print statement values can then be provided as an output of the "Code Snippet" connector step and can be consumed by the next playbook step. 

In a "Code Snippet" connector step if you need to import a Python library that is not shipped by default with the product, you can install it using the following steps: 

  1. Import the Python library (custom module).
  2. To use the custom module install the custom module in the integrations virtual environment, using the following command:
    sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install <module name>
    For example, if you want to add a module named "whois", use the following command:
    sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install whois

For some of the enhancements, bug fixes, and various versions of the Code Snippet connector see the Code Snippet Connector Release Notes section.

System Monitoring

Use the System Monitoring connector to display information about disk space utilization for different partitions, virtual memory utilization, and CPU utilization of the running FortiSOAR™ instance. It also provides information about the status of all FortiSOAR™ services.

For some of the enhancements, bug fixes, and various versions of the System Monitoring connector see the System Monitoring Connector Release Notes section.

BPMN

Use the BPMN connector to convert BPMN workflows that are created in tools such as Flowable or Camuda to FortiSOAR™ playbooks.

This connector is ready to use, and you do not need to configure this connector. For more information on BPMN workflows and how they can be imported and used as FortiSOAR™ playbooks, see the "Importing the BPMN Shareable Workflows as FortiSOAR™ Playbooks" topic in the Playbooks Overview chapter in the FortiSOAR™ documentation.

For some of the enhancements, bug fixes, and various versions of the BPMN connector see the BPMN Connector Release Notes section.

Report Engine 

The Report Engine connector is used to generate FortiSOAR™ reports and save this report as a text pdf in the Reports > History page.

For some of the enhancements, bug fixes, and various versions of the Report Engine connector see the Report Engine Connector Release Notes section.

Troubleshooting the FortiSOAR™ Built-in connectors

IMAP connector displays an error when you perform a Health Check

The IMAP Built-in connector could display an error such as [ALERT Please log in via your web browser: https://support.google.com/mail/accounts/answer/78754 (Failure)] when you perform a Health Check by clicking the Refresh icon that is present in the Health Check bar.

Resolution

This issue occurs due to the Gmail security guidelines that consider that an untrusted device has tried to log in to the mail account. You must change the password of your mail account to resolve this issue.

IMAP connector displays errors while you are configuring the connector

The IMAP Built-in connector could display any of the following errors while you are configuring the connector:

  • CS-IMAP-2: <parameter_name> is mandatory arguments
    This message is displayed when you are configuring the IMAP connector (new version or new installation) and you do not specify the value for a required parameter.
  • CS-IMAP-3: Invalid function argument
    This message is displayed when you are configuring the IMAP connector (new version or new installation) or when you are activating or deactivating the connector or when you are checking the health of the connector with the Enable Email Notification Service option checked.
  • > IMAP > Fetch" has failed because: CS-INTEGRATION-5: Error occurred while executing the connector action ERROR :: create failed: [ALREADYEXISTS] Folder name conflicts with existing folder name. (Failure) URL : https://127.0.0.1:9595/integration/execute/?format=json
    This message is displayed if the "Email destination" folder specified on the server is similar to an existing folder. Mailbox names are case sensitive on the creation of folders using the IMAP client, for example, if you specify MyFolder in the Email destination field and a folder named myfolder already exists on the server, then this error will be displayed.

Resolution

  • Check that you have specified the values for all the required parameters.
  • Check that the first argument that you have specified for sending a message to the "listener" script is valid and the format of sending the message is correct.

IMAP connector displays an error when the application private and public keys are missing in the integration module

The following error message is displayed when the application private and public keys are missing in the integration module:

CS-IMAP-11: Error occurred while getting the private or public key. File not found for keys. ERROR :: <error_message>

Resolution

Copy the appliance key from /opt/cyops-workflow/sealab/.envdir/APPLIANCE_*_KEY to the opt/cyops-integrations/integrations/configs folder and change its permissions to -rw-r--r-- nginx:nginx. Then, restart the uwsgi service.

IMAP connector displays an error when you try to restart the email notification service

The following error message is displayed when you try to restart the email notification service with the listener that is already in an inactive state:

CS-IMAP-17: Notification service is already down, bringing up the service

Resolution

Deactivate the connector, restart the uwsgi service, and again activate the connector. For more information on the error, check the log file located at: /var/log/cyops/cyops-integrations/imap/listener.log.

IMAP connector displays the`ERROR :: create failed: [ALREADYEXISTS] Folder name ...  error

The following error can occur when you are fetching data from IMAP using the Email Notification service:

> IMAP > Fetch" has failed because: CS-INTEGRATION-5: Error occurred while executing the connector action ERROR :: create failed: [ALREADYEXISTS] Folder name conflicts with existing folder name. (Failure) URL : https://127.0.0.1:9595/integration/execute/?format=json

The above error can occur due to the following reasons:

  • This message is displayed if the Email destination folder specified on server is similar to an existing folder. Mailbox names are case sensitive on creation of folders using the IMAP client, for example, if you specify MyFolder in the in the Email destination field and a folder named myfolder already exists on the server, then this error will be displayed.
  • This error also occurs if the folder that you have specified does not have permission for the IMAP client.

Resolution

  • In the IMAP connector configuration pane, update the folder name in the Email destination field and save the configuration.
  • Ensure that you provide appropriate permissions to the email destination folder for the IMAP client.

Release Notes

Utilities Connector Release Notes

Version 3.0.5

  • Added compatibility fixes to make the Utilities connector v3.0.5 compatible with FortiSOAR™ versions earlier to 6.4.3, i.e., version 3.0.5 of the connector is compatible with 6.4.1, 6.4.0, and earlier versions of FortiSOAR™. 
  • Added support for executing 'File-related' operations such as "File: Download File from URL", "File: Create Attachment from File, etc. on the "Agent" machine from FortiSOAR™ version 6.4.3 onwards.
  • Updated the output schema of the "Email: Extracts email's metadata from email file" operation to generalize the Message-id as message-id. This also fixes the issue of data ingestion failing if the email has .msg files as attachments.

Version 3.0.4

  • Updated the "File: Create File from String" operation to support binary data.
  • Updated the "Email: Extracts email's metadata from email file" operation to solve the issue due to which this operation did not extract all the characters from an email attachment. 
    This issue occurs due to a limit set on the content length of an email, which trimmed out content exceeding the limit. Now, this limit has been made configurable in the EMAIL_CHARACTER_COUNT_MAX parameter, and by default, it is set to 100000 characters. To change the limit, edit the EMAIL_CHARACTER_COUNT_MAX parameter that is present in the /opt/cyops-integrations/integrations/configs/config.ini file. For example:
    EMAIL_CHARACTER_COUNT_MAX = 100000 <- Change this value as per your requirement.  
    If you have updated the value of the EMAIL_CHARACTER_COUNT_MAX parameter then you have to restart the uwsgi and celeryd services for the change to take effect.
    Use the # systemctl restart celeryd and # systemctl restart uwsgi commands to restart the celeryd and uswgi services.  
    Important: FortiSOAR™ version 6.4.3 and later supports configuring the EMAIL_CHARACTER_COUNT_MAX parameter. 

Version 3.0.3

  • Updated the CSS of the "Utils: Convert JSON into a HTML Table" operation to display the Show More button only if there are more than "5" rows in the table. This enables effortless viewing and editing large tables in the Collaboration Panel that have been converted from JSON to HTML using this operation and added into the alert using a playbook.

Version 3.0.2

  • Optimized the output of the "Utils: Convert JSON into a HTML Table" operation so that the Show More button is not visible in case there are fewer than 5 records in the table.
  • Fixed a bug in the "Email: Extracts email's metadata from email file" operation, which did not delete the attachment that is downloaded to the /tmp directory once the playbook completes its execution. Now, when the "Email: Extracts email's metadata from email file" operation extracts any eml file that contains an attachment, then the attachment is downloaded as a temporary file, and stored in the /tmp directory, which will now be deleted once the playbook completes its execution.

Version 3.0.1

  • Updated the branding for the Utilities connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes. For example, the "CyOPs: Extract Artifacts from String" action has been renamed to "FSR: Extract Artifacts from String", the "CyOPs: Update Global Variables" action has been renamed to "FSR: Update Global Variables", the "CyOPs: Make CyOPs API Call" action has been renamed to "FSR: Make FortiSOAR API Call", the "File: Upload a file to CyOPs and Create an Attachment" action has been renamed to "File: Upload a file in the system and create an attachment", and the "File: Create CyOps Attachment From File" has been renamed to "File: Create Attachment from File". Also, updated parameters within actions to match the branding, for example in the "File: Zip" action, renamed the "CyOPs File IRI or Filename" field to "File IRI or Filename". 

Version 3.0.0

  • Added support for URL encoding and decoding in the "CyOPs: Extract Artifacts from String" operation.
  • Added support to create a vertical table template, using the HTML template, in the "Utils: Convert JSON into a HTML table" operation. A Styling checkbox has also been added, which provides support for applying custom HTML styles to the table. If you select this checkbox, then you can add custom HTML styles in the Table Styling field.
  • Refactored the output of the "Email: Extracts email's metadata from email file" operation. 
  • Due to refactoring, there have been some changes to the output of the Utilities connector which are not backward compatible. For example, the body key in the response now returns a dictionary with keys 'json', 'html' instead of an array of these. It is recommended to switch to the new format. If you want to retain the old output format, then you can update the extract_email_metadata_legacy to true in the /opt/cyops-integrations/integrations/configs/connectors.yml file. By default, extract_email_metadata_legacy is set as false
  • Once you have updated the key, restart the uwsgi service using the following command: 
  • # systemctl restart uwsgi
  • Renamed the action "CyOPs: Update Macro" to "CyOPs: Update Global Variables".
  • The connector logo has also been updated in version 3.0.0 of the Utilities connector.

Version 2.7.0

  • Added support for IPv6 address in the "CyOPs: Extract Artifacts from String" operation.
  • Enhanced the "Email: Extracts email's metadata from email file" operation to allow the extraction of embedded emails or messages up to a depth of 4 levels.
  • Enhanced the logic of extraction of emails and messages to make the extraction process more efficient. Also, fixed the issue of freezing of artifacts for long URLs using the Extract Artifacts operation.
  • Added small fixes and enhancements to improve the functionality and readability of various actions.

Important: If you upgrade the Utilities connector to v2.7.0, then playbooks that contain the "Utils: Make REST API Call" and "CyOPs: Make CyOPs API Call" operations reset the get, put, post, and delete methods if they were not written in capital letters. This occurs due to the current enhancements in the Utilities connector v2.7.0. However, there will not be any functional impact due to this since the playbook will execute successfully after the upgrade, and you can correctly add the methods to the playbook post-upgrade.

Version 2.6.0 

  • Fixed important bug such as modifying the URL regex in the "Extract Artifacts from String" operation.

Version 2.4.1 

  • Updated the output of the Utils: Is IP in CIDR operation so that consistency is maintained in the output format for both the matched IP result and the unmatched IP result. It also contains an enhanced logo for the Utilities connector.

Version 2.4.0

  • Added the "File: Unzip" operation that you can use to unzip a file or a password-protected file that is present in your FortiSOAR™ instance, i.e., the file must either be present in the Attachment module in FortiSOAR™ or in the /tmp folder of your FortiSOAR™ instance.
  • Added the "File: XOR Decryption" operation to perform XOR Bitwise operations on a file that is present in your FortiSOAR™ instance. This operation stores the output of the operation, i.e., the decrypted data in a file that you have specified.
  • Updated the "Utils: Convert XML, CSV, XLS or XLSX Files to Dictionary" to add the support of converting files that are in XLS or XLSX format to a dictionary. Earlier only XML and CSV formats were supported.
  • Updated the "CyOPs: Extract Artifacts from String" operation as follows: 
    • Renamed the Whitelist field to Whitelist Artifacts. In this field, you can add a comma-separated list of artifacts such as, domains, CIDR Ranges, and IP addresses that will be omitted from the extraction results. For example, if you have specified "example.com" in the Whitelist Artifacts field, then all related artifacts such as "test@example.com", and "example.com/sub1/sub2" will be considered as whitelisted.
    • Added the Whitelist Private Addresses checkbox. Select this checkbox to allow private addresses to be whitelisted. If you do not select this checkbox, then private RFC1918 IPv4 addresses such as, 10.0.0.0/8 will not be whitelisted.
    • Added the Override URL Extraction Settings checkbox. Select this checkbox to edit the default regex expression or provide a custom regex that will override the default URL extraction settings.
      The RegEx Expression For URL Extraction field is displayed only when you select this option.
  • Renamed the "File: Zip and Password Protect" operation to "File: Zip" and updated this operation as follows:
    • Updated the Filename field to CyOPs File IRI or Filename since now you can either specify a file IRI or a file name as an input to this operation. Earlier you could only specify a filename.
    • Updated the Password field to be a not required field, which means that you can now create the zip file with or without a password. Earlier you could only create the zip file with password protection.

Apart from the above enhancements, the Utilities connector also contains better error handling, which includes displaying of enhanced, precise, and detailed error messages, making it easier for you to debug Utilities connector issues. For information on common Utilities connector issues, see the Common Utilities connector errors section in the Debugging common playbook and connector issues article present in the Fortinet Knowledge Base.

Version 2.3.0

  • Enhanced the "CyOPs: Extract Artifacts from String" operation as follows:
    • Inclusion of a new parameter named Whitelist parameter. This operation extracts indicators from the specified string which are used for further processing. This enhancement provides you with the ability to add a comma-separated list of indicators that you want to whitelist, i.e., these indicators will not be included in the result of this operation. The output schema of this operation now displays only the results and the whitelisted_results fields; all the other output fields are not visible. However, the other output fields will yet be supported for a couple of more releases to ensure backward compatibility.
    • Extraction of URLs only if they are pre-pended with http, https, ftp, or sftp.
  • Enhanced the "Email: Extract email's metadata from email file" operation to also extract attachments from the .eml or .msg files. Earlier only the metadata used to be extracted (and not the attachments) from the .eml or .msg files.

Version 2.2.0

  • Updated the "Email: Extracts email's metadata from email file" step to allow users to specify a file path of the attachment as an input to this step. This action has also been enhanced to make the File Type an optional parameter since the action now automatically recognizes the file type of the attachment. Therefore, users do not require to specify the file type explicitly.
  • Updated the Create Attachment checkbox to be an optional field in the "File: Upload a file to CyOPs and Create an Attachment" operation, so that users can use this operation without mandatorily having to create an attachment record.

Version 2.1.3

  • Fixed the "File: Create CyOPs Attachment from File" step to not require authentication as a part of the header in the playbook step.
  • Fixed the "CyOPs: Extract Artifacts from String" step in the Utilities connector to parse email addresses and URLs correctly, and this step is also enhanced to allow the format of the result to be loopable, i.e., all results in unified_result.
  • Better error handling: Display of enhanced, precise, and detailed error messages, making it easier for you to debug Utilities connector issues.

Version 2.1.2

  • Added a new function named "Utils: Convert XML or CSV Files to Dictionary". This function converts XML or CSV files to JSON. The "Utils: Convert XML to Dictionary" function has changed to support converting an XML string to JSON. This version also includes some bug fixes such as marking the "Name" field as mandatory for the "Create CyOps Attachment From File" function. Earlier, you could leave the "Name" field empty and run the playbook, which would cause the playbook to fail.

Version 2.1.0

  • Added new functions such as the "Zip and Password Protect" function and enhancements to a number of functions such as the "Compute Hash" function has been enhanced to contain the downloaded file path as a result in the file path.  

Database Connector Release Notes

Version 2.1.1

  • Fixed the issue of Python dependency now the database connector will require only a specific version of the Python library, which is pymssql==2.1.4. The connector logo has also been updated in version 2.1.1 of the Database connector.

Version 2.1.0

  • Fixed the issue of Python dependency issues occurring while working with the database connector.

Version 2.0.2

  • Fixed the issue of update and insert queries. Now, the update and insert queries, updates, or inserts a table in the database appropriately. It also contains an enhanced logo for the "Database" connector.

Version 2.0.1

  • Enhanced the Database Connector's configuration parameter "Engine", to a drop-down list containing the valid options, which are postgresql, mssql, and mysql. Earlier it was a text field, and therefore it was possible that an invalid option could be entered in this field.

IMAP Connector Release Notes

Version 3.5.4

  • Added support for extracting inline images from emails when the Fetch Email(s) operation is executed. To support the extraction of inline images, a new checkbox named Parse inline images (selected by default) is added to the "Fetch Emails" operation. If you do not want to extract inline images from emails, clear the Parse inline images checkbox.
    Note: Extraction of inline images from an eml/msg file using the "Fetch Email(s)" operation, is currently not supported. However, you can extract inline images that are part of the email using the "Fetch Email(s)" operation.
  • Added support for listener-based connector configuration on a FortiSOAR™ Agent. Listener-based connectors listen for live events on a server, and then these events are notified to FortiSOAR™ by triggering a playbook. For example, the IMAP connector, which has enabled its listener-based configuration, starts a live listener for the specified email account. Therefore, if any new emails are received in the configured account or folder, the connector fetches that emails and triggers playbooks, such as the ingestion playbook, which is specified in the configuration. For more information, see the Segmented Network support in FortiSOAR™ chapter in the FortiSOAR™ documentation.
  • Fixed the configuration issue not of being able to set "Verify SSL" to true if you have enabled the notification service, i.e., selected the "Enable Email Notification Service" checkbox.

Version 3.5.2

  • Fixed important bugs such as solving the issue of the IMAP connector that was configured with an exchange server used to get disconnected after a certain time such as 3 to 4 hours after it had got connected on FortiSOAR™. Deactivating and reactivating the connector used to solve this issue but this issue was a recurring one, which has now been solved.

Version 3.5.1

  • Updated the branding for the IMAP connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes.

Version 3.5.0

  • Resolved the issues in notification service while using the Microsoft server and refactoring the output of the "Fetch Email(s)" operation.
    Due to refactoring, there have been some changes to the output of the IMAP connector which are not backward compatible. For example, the body key in the response now returns a dictionary with keys 'json', 'html' instead of an array of these. It is recommended to switch to the new format. If you want to retain the old output format, then you can update the extract_email_metadata_legacy to true in the /opt/cyops-integrations/integrations/configs/connectors.yml file. By default, extract_email_metadata_legacy is set as false.
    Once you have updated the key, restart the uwsgi service using the following command: 
    # systemctl restart uwsgi
  • Added new parameter named Maximum number of emails to fetch in the "Fetch Email(s)" action. You can add an integer value in the Maximum number of emails to fetch parameter to restrict the number of unread emails that are fetched. By default, the count is set to 30, i.e., the IMAP connector will by default fetch 30 unread emails.
  • Updated the connector logo.

Version 3.5.4

Fixed important bugs such as fixing the issue of failure to deactivate the IMAP connector if you had specified a non-default port. This issue used to occur when you were using the notification service in the IMAP connector, and you had specified a port that was not the default port, then you would get an error when you tried to deactivate the connector.

Version 3.3.2

  • Contains enhancements made to the data ingestion playbooks.

Version 3.3.1

  • Enabled for data ingestion and includes an enhanced logo.

Version 3.3.0

  • Enhanced the IMAP configuration to check that the listener port that you have specified in the connector configuration for fetching emails is being used by any other process, then the Enable Email Notification Service will throw an error.
  • Enhanced the IMAP configuration to ensure that the Verify SSL checkbox works correctly. Earlier, if you would check or clear the Verify SSL checkbox, then the connector configuration would throw an error, and the IMAP connector would not be available.
  • Added support for .eml files that have content-type multipart/mixed, multipart/related, and multipart/alternative.
  • Enhanced the ExplodedEmailFile output parameter to include attachments of type .eml or .msg.
  • Removed the Raw Field from the connector output step since it could cause a crash in the FortiSOAR™ UI in case of large emails or attachments and the Raw Field was not being utilized in any other process.

Version 3.2.0

  • The ability to select the Enable Email Notification Service option in the IMAP connector configuration without having to add the username/password of the FortiSOAR™ instance as part of the configuration. Now, HMAC authentication using appliance keys is implemented to fetch new emails dynamically in the same instance based on the Custom API Endpoint Playbook specified as part of the configuration.
  • The ability to choose if you want to Verify SSL in the IMAP connector configuration section. When the Verify SSL checkbox is cleared, then the IMAP connector bypasses the verification of the SSL certificate, thereby allowing you to use TLS (self-signed certificate) on the IMAP server.
  • The ability to verify (using the connector output) in the Fetch Emails action, if there is a .eml or .msg type of attachments received in the fetched email so that users can utilize the exploded output of the .eml or .msg attachments available in the connector output.
  • The ability to get the exploded and parsed output for .eml or .msg type of attachments in the connector output received in the fetched email so that users can directly use the same in their workflow and avoid the current complexity of parsing such messages.
  • The ability to use the Extract email's metadata from email file action in the utility connector, to specify a file path of an attachment and have the action automatically choose the file type, without the user having to provide the file type as  .eml or .msg in case of fetched emails.
  • Automatically starting all the email notification services when the uwsgi service is restarted. Earlier, users had to deactivate the connector and reactivate the connector on a service restart.
  • The ability to configure the listener port for IMAP, by default the port is set as 10010. The listener port is used for communication between FortiSOAR™ and the IMAP notification service process. You can specify any unused port number if the default port (10010) is unavailable.

Version 3.0.2

  • Contains enhancements and bug fixes such as, the ability to edit parameters without resetting the other parameters and stabilizing the IMAP connector.

Apart from the above enhancements, the IMAP connector also contains better error handling, which includes displaying enhanced, precise, and detailed error messages, making it easier for you to debug IMAP connector issues. For information on common IMAP connector issues, see the Common IMAP connector errors section in the Debugging common playbook and connector errors article present in the Fortinet Knowledge Base.

SMTP Connector Release Notes

Version 2.4.0

  • Enhanced to support the "HTML Editor" when users select the Body Type of the email as "Rich Text", i.e., you can add formatted content, including adding media, links, attachments, etc. to the content of the email and this content will render as HTML. This version has also added support for adding new lines while entering email content when users select Plain Text as the "Body Type". Now, the Plain Text field is of type "Text Area", which enables users to add new lines.

Version 2.3.3

  • Fixed a bug in the "Send Mail" operation, which did not delete the attachment that is downloaded to the /tmp directory once the playbook completes its execution. Now, when in the "Send Mail" operation the user provides an "Attachment IRI", then the attachment is downloaded from FortiSOAR™ and is saved in the /tmp directory, which will now be deleted once the playbook completes its execution.

Version 2.3.2

  • Updated the branding for the SMTP connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes. Names of fields within actions have also been changed to match the branding changes. For example, the "CyOPs Attachment IRI List" field has been renamed to "Attachment IRI List".

Version 2.3.1

Contains an updated logo.

Version 2.3.0

  • The CyOPs Attachment IRI List field in which you could include attachments in the email, required you to specify an array of FortiSOAR™ IRIs (file or attachment IRIs) of attachments. Now, you can specify a comma-separated list of FortiSOAR™ IRIs.
  • User list now contains the complete list of users, earlier it used to only contain the first 30 users.
  • Jinja specified in the Subject field now gets parsed correctly.
  • The From field will now appear blank.
  • An enhanced logo for the "SMTP" connector.

Version 2.2.0

  • The ability to send emails to 30 most recently created FortiSOAR™-teams or users by selecting teams or users from a pre-populated drop-down list using the Recipient Type drop-down list.
  • Support for specifying the IRI values for users and/or teams, allowing users to reuse team or user information defined in previous playbook steps as Jinja statements, if you have selected Manual Input from the Recipient Type drop-down list. You can also specify a comma-separated list of email addresses (which is what was followed in the earlier versions) so that users can continue to use this behavior and also send emails to non-FortiSOAR™ users.
  • The ability to pass an existing email template as an input for the email subject and body (content) using the new "Send Email" action.

Version 2.1.2

  • Fixed important bugs and also contains enhancements, such as adding support for file attachments in the "Send Email" function.

SOAP Connector Release Notes

Version 2.2.1

  • Includes the corrected and updated logo.

Version 2.1.0

  • Includes an enhanced logo for the "SOAP" connector.

SSH Connector Release Notes

Version 2.1.1

  • Includes an updated logo.

Version 2.1.0

  • Fixed the issue of health check not working for this connector. For example, the SSH connector would show "Available" in the Health check, even if the credentials were incorrect. The SSH connector configuration page has also been updated to include a Set Super User Password field, in which you can specify a password for a super user. In a playbook that uses the "SSH" connector, in the "Execute remote command" action, you can choose to execute a remote command as a super user, by clicking the Run as super user checkbox. This version also contains an enhanced logo for the "SSH" connector.

Version 2.0.2

  • Includes a number of bug fixes and enhancements made in the SSH connector.

Code Snippet Connector Release Notes

Version 1.2.4

  • Fixed an important security issue and now the Allow All Imports checkbox is not selected by default.

Version 1.2.3

  • Updated the branding for the Code Snippet connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes. 

Version 1.2.4

  • Fixed important bugs such as solving the issue of python dependencies in the earlier versions of the connector, which were causing failures. The connector logo has also been updated in version 1.2.2 of the Code Snippet connector.

Version 1.2.1 

  • Includes an enhanced log for the Code Snippet connector. Also, the sample playbooks that are shipped with this connector are shipped in the Inactive state. You can activate the playbooks as per your requirement.

Version 1.2.0

  • Contains no changes to the functionality of this connector; however, it contains changes to the internal code of this connector.

System Monitoring Connector Release Notes

Version 1.3.0

Added monitoring of the cyops-integration-agent service, which supports running actions on remote agents.

Version 1.2.1

  • Updated the branding for the System Monitoring connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes. 

Version 1.2.0

Fixed an issue with the System Health Status dashboard to show the correct version of PostgreSQL, i.e, postgresql -12, in the Service Status listing. Version 1.2.0 also contains an updated logo.

BPMN Connector Release Notes

Version 1.0.2

  • Updated the branding for the BPMN connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes. Names of fields within actions have also been changed to match the branding changes.

Version 1.0.1

  • Contains an updated logo.

Report Engine Connector Release Notes

Version 1.1.0

  • Enhanced the Report Engine connector to support the generation of reports using an "Appliance User". 

Version 1.0.5

  • Fixed a security vulnerability.

Version 1.0.4

  • Updated the branding for the IMAP connector such as updated the connector publisher to "Fortinet" and updated the names, description, and action names of playbooks based on the branding changes.

Version 1.0.3

  • Contains an updated logo.

Version 1.0.2

  • Contains updates (internal) based on scheduling changes that are being done in version 5.0.0. It also contains an enhanced logo for the "Report Engine" connector.

Version 1.0.1

  • Contains an update to the command (internal) used to generate reports.

Overview

FortiSOAR™ provides you with a number of pre-installed connectors or built-ins that you can use within FortiSOAR™ playbooks, as a connector step, and perform automated operations. 

These connectors are bundled and named based on the type of operations the connectors can perform. For example, the Database connector would contain actions that you can perform with respect to the database like querying the database. It is easy to extend and enhance these connectors. 

Important: Before you upgrade your FortiSOAR™ version, it is highly recommended that you take a backup of your FortiSOAR™ Built-in connector's (SSH, IMAP, Database, etc.) configuration since the configuration of your FortiSOAR™ Built-in connectors might be reset if there are changes to the configuration parameters across versions.

Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as Splunk and Ticketing systems such as Jira. You can see a list of published connectors on the Fortinet Support Site. After logging on the Support Site, click the Knowledge Base tab and then click Connectors to view the list of connectors published by Fortinet. 

FortiSOAR™ in version 6.0.0 has refactored the output of some operations of some built-in connectors such as the "Email: Extracts email's metadata from email file" operation of the Utilities connector. Due to refactoring, there have been some changes to the output of the Utilities connector which are not backward compatible. For example, the body key in the response now returns a dictionary with keys 'json', 'html' instead of an array of these. It is recommended to switch to the new format. However, if you want to retain the old output format, and you have only upgraded the connector version and not upgraded your FortiSOAR™ version, then you must do the following:

  1. Append the following in the /opt/cyops-integrations/integrations/configs/config.ini file:
    [connector_configuration]
    extract_email_metadata_legacy: true

    The output of the "Email: Extracts email's metadata from email file" operation is determined by the extract_email_metadata_legacy parameter. If the extract_email_metadata_legacy parameter is set as true then the output will be generated in the old format, and if it is set as false, then the output will be generated in the new format.
  2. Add the following at the end of the /opt/cyops-integrations/integrations/integrations/settings.py file:
    APPLICATION_CONFIG = application_config
  3. Restart the uswgi service using the following command:
    # systemctl restart uwsgi

Important: If you are upgrading to FortiSOAR™ 6.0.0, then you need to perform only steps 1 and 3.

Configuring the FortiSOAR™ Built-in connectors

To configure FortiSOAR™ Built-in connectors, you must be assigned a role that has a minimum of Update access to the Connectors module.

The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the FortiSOAR™ documentation or click see the Configuring a connector article.

Upgrading the FortiSOAR™ Built-in connectors

FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. You should use the Connector Store from version 5.0.0 onwards to upgrade your connectors to the latest version. For more information on the connector store, see the Introduction to connectors chapter.

Prior to version 5.0.0, you could upgrade a connector on an existing version, i.e, without upgrading FortiSOAR™, by running the following command as a root user:

# yum update cyops-connector-<connector name>

For example, # yum update cyops-connector-cyops-imap

Important: After you upgrade to FortiSOAR™ 6.0.0 and before you reconfigure ingestion for the same connector configuration, you must deactivate the earlier ingestion playbooks that are present in the ingestion collection for the connector. The links to the ingestion playbooks that were created prior to the upgrade will be present on the System Fixtures page in the "Ingestion Playbooks" section will not be visible in the Data Ingestion tab (new in version 6.0.0) of the "Connectors" page. If your data ingestion is schedule-based, then you must also stop or delete the earlier schedules for the connector.

Built-in connectors

The following built-in connectors that are included by default in FortiSOAR™:

For some of the operations, enhancements, bug fixes, and various versions of the built-in connectors see the Release Notes section.

Utilities 

Use this connector for performing operations in FortiSOAR™, such as performing a FortiSOAR™ search using the Query API, updating a FortiSOAR™ resource, and creating a FortiSOAR™ resource. This connector also contains other useful utilities such as extracting email metadata such as indicators from an email file, uploading a file to FortiSOAR™ and associating that file with an attachment, i.e., providing the File IRI in the output, converting file formats, such as XML to JSON or CEF to JSON, and zipping and password protecting a file.

This connector is ready to use, and you do not need to configure this connector.

Note: Any file that is downloaded on the agent using the download file action of the Utilities connector will not be available to any of the next steps in the playbook. For example, if you create a playbook add then add the Utilities connector operation "File: Download File From URL" step for an FSR Agent configuration, add the download URL, and save the step. Next, you add the "File: Create Attachment From File" step in which provide the file reference from "Download" step and save and run the playbook. The playbook will fail with an error such as "Connector step is failing with error 'Invalid input :: Given filename/filepath /tmp/f68ab00fb7da4dfd9db4bb95abb1471e doesn't exists'". This is expected behavior since when a file download operation is performed on an FSR agent, the operation cleans the file when the response is returned to the base FortiSOAR™ node. Therefore, if any following step expects the downloaded file to be present at the agent will cause that step to fail. For more information on FSR agents, see the Segmented Network Support chapter in the FortiSOAR™ documentation.

An example of the utilities that are included in the Utilities connector is the "Utils: Convert JSON into an HTML table" utility. This utility generates an HTML-formatted string based on the input JSON. The HTML-formatted string will appear as follows:

<table class="cs-data-table">
<tr>
<th>pid</th>
    <th>path</th>
    <th>username</th>
  </tr>
  <tr>
    <td>4</td>
    <td>c:\\windows\\system32\\ntoskrnl.exe</td>
    <td>NT AUTHORITY\\SYSTEM</td>
  </tr>
  <tr>
    <td>296</td>
    <td>c:\\windows\\system32\\smss.exe</td>
    <td>NT AUTHORITY\\SYSTEM</td>
  </tr>
</table>

For the given input JSON: 

{
"operation": "get_process_list",
"data": [
    {
        "path": "c:\\windows\\system32\\ntoskrnl.exe",
        "create_time": 1529090266,
        "command_line": "",
        "parent_guid": "00000004-0000-0000-0000-000000000000",
        "proc_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
        "parent": 0,
        "username": "NT AUTHORITY\\SYSTEM",
        "pid": 4,
        "sid": "s-1-5-18"
    },
    {
    "path": "c:\\windows\\system32\\smss.exe",
    "create_time": 1529090266,
    "command_line": "\\SystemRoot\\System32\\smss.exe",
    "parent_guid": "00000004-0000-0004-01d4-04dd8adc9fb8",
    "proc_guid": "00000004-0000-0128-01d4-04dd8ae6291c",
    "parent": 4,
    "username": "NT AUTHORITY\\SYSTEM",
    "pid": 296,
    "sid": "s-1-5-18"
    },
    "status": "Success",
    "message": ""
}

For some of the operations, enhancements, bug fixes, and various versions of the Utilities connector see the Utilities Connector Release Notes section.

Database 

Use this connector to connect to a database and then query the database and retrieve data. You can connect to multiple databases by setting up multiple configurations. 

Note: If you have externalized your PostgreSQL Database, then you will require to update the host information and the credentials in the database connector configuration page, based on the credentials that you have specified for your externalized PostgreSQL database. For more information on the externalization of PostgreSQL Database, see the Externalization of your FortiSOAR™ PostgreSQL database chapter in the FortiSOAR™ documentation.

For some of the enhancements, bug fixes, and various versions of the Database connector, see the Database Connector Release Notes section.

IMAP 

Use this connector to set up multiple email accounts and fetch emails from different email accounts.  

Important: Before you enable the Enable Email Notification Service option in the IMAP connector configuration, ensure that you have activated the Custom API Endpoint trigger playbook that you have specified in the IMAP connector configuration.

If you want the IMAP connector to read emails from your Spam folder also, then you must specify the complete path on the email client, since Spam is not the main folder in any email client. For example, if your email client is Gmail, then set the Email Source as [Gmail]/Spam.

Note: The IMAP builtin connector is dependent on the Utilities connector. Therefore, if you remove the Utilities connector, the IMAP connector will not work.

For some of the operations, enhancements, bug fixes, and various versions of the IMAP connector see the IMAP Connector Release Notes section.

SMTP 

Use this connector to setup SMTP for sending system notifications, including requests for resetting passwords, and also for sending emails outside FortiSOAR™. When you configure the SMTP connector, you must ensure that the Mark As Default Configuration option for the configuration that is to be used for sending system notifications is selected.

You can send emails to 30 most recently created FortiSOAR™-teams or users by selecting teams or users from a pre-populated drop-down list using the Recipient Type drop-down list.

If you select Manual Input from the Recipient Type drop-down list, then you can specify a comma-separated list of email addresses, including email addresses of non-FortiSOAR™ users. However, you can also specify the IRI values for users and/or teams, which allows users to reuse team or user information defined in previous playbook steps as Jinja statements.

If you select Team from the Recipient Type drop-down list, then you can send emails by selecting existing FortiSOAR™ teams from the pre-populated To, CC, or BCC multi-select fields, which enables users to dynamically leverage the email ID which has already been provided in a team record, and the email can be sent to all the members of the team at once.


If you select User from the Recipient Type drop-down list, then you can send emails by selecting existing FortiSOAR™ users from the pre-populated To, CC, or BCC multi-select fields, which enables users to dynamically leverage the email ID which has already been provided in a user record. So now you have the ability to interchangeably send emails in multiple formats by specifying a comma-separated list of email addresses or selecting FortiSOAR™-teams or users, or by reusing team or user information defined in previous playbook steps as Jinja statements.

You can pass an existing email template as an input for the email subject and body (content) allowing you to leverage an existing email template and build upon it, and thereby, avoiding re-work and ensuring consistency. The Send Email step contains a Body Type drop-down list from which you can choose whether you want to send a plain text email (Plain Text), rich text email (Rich Text), or an email based on a template (Email Template).

If you select Rich Text from the Body Type drop-down list, then in the Content field, you can add formatted content, images, and even custom jinja expressions using Dynamic Values:

If you select Email Template from the Body Type drop-down list, the Email Template drop-down list is displayed, using which you can select the template that you want to use to send the email:

For some of the operations, enhancements, bug fixes, and various versions of the SMTP connector see the SMTP Connector Release Notes section.

SOAP

Use this connector to make SOAP calls by sending SOAP functions and receiving data. 

The SOAP connector (version 2.3.0) contains a full-fledged SOAP client that reads WSDL from the configuration and populates the list of actions and all the required/optional inputs from WSDL. Therefore, now you can use the newly added SOAP Call action to integrate SOAP web services with FortiSOAR™. To use the SOAP client, from the Action drop-down list select SOAP Call, then select the SOAP Service that you want to use, based on which you select the Port Type and the Function Name, after which all the required or optional parameters get displayed. The headers list gets populated and even the output schema of this step gets populated in the next steps of the playbook according to the function you have selected. A new field "Additional SOAP Headers" is added to the SOAP Call action, using which you can specify any extra headers, which are required for the requests.

Important: This new feature, i.e., the SOAP Call action, is supported for FortiSOAR™ version 6.4.1 and later.

The SOAP connector also has the SOAP Call (Generic) action that is present for backward compatibility, where you could specify a SOAP function and define its parameters. A new field "Additional SOAP Headers" is added to the SOAP Call (Generic) action, using which you can specify any extra headers, which are required for the requests.

For some of the enhancements, bug fixes, and various versions of the SOAP connector see the SOAP Connector Release Notes section.

SSH 

Use this connector to connect to different servers and execute commands and python scripts on those servers.  

For some of the enhancements, bug fixes, and various versions of the SSH connector see the SSH Connector Release Notes section.

Code Snippet

Use the Code Snippet connector to run a python function as part of playbooks. 

To configure this connector, click Automation > Connectors in the left-navigation, and on the Connectors page, click the Code Snippet connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details.

If you check the Allow All Imports checkbox, then users can import all python modules, and users are required to include the import statement for any modules they want to use. 

If you clear the Allow All Imports checkbox, then in the Allow Following Imports field, users can specify the list of modules that they want to import. Users can then use these modules, without having to include the import statement in the python code. Note that, in this case, users will not be allowed to import modules that are not part of the list of specified modules.

Add the "Code Snippet" connector in a playbook as a connector step and execute a python code as part of a playbook. 

If the value of the variable that you are defining in the python code is a string, then you must add double-quotes. For example:
description = "{{vars.input.records[0].description | striptag}}"

If the value of the variable that you are defining in the python code is a dictionary or array, then you can use is without double-quotes. For example: 
description = {{vars.input.records[0].description | striptag}}

You must add the print statement to the python code. The print statement values can then be provided as an output of the "Code Snippet" connector step and can be consumed by the next playbook step. 

In a "Code Snippet" connector step if you need to import a Python library that is not shipped by default with the product, you can install it using the following steps: 

  1. Import the Python library (custom module).
  2. To use the custom module install the custom module in the integrations virtual environment, using the following command:
    sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install <module name>
    For example, if you want to add a module named "whois", use the following command:
    sudo -u nginx /opt/cyops-integrations/.env/bin/pip3 install whois

For some of the enhancements, bug fixes, and various versions of the Code Snippet connector see the Code Snippet Connector Release Notes section.

System Monitoring

Use the System Monitoring connector to display information about disk space utilization for different partitions, virtual memory utilization, and CPU utilization of the running FortiSOAR™ instance. It also provides information about the status of all FortiSOAR™ services.

For some of the enhancements, bug fixes, and various versions of the System Monitoring connector see the System Monitoring Connector Release Notes section.

BPMN

Use the BPMN connector to convert BPMN workflows that are created in tools such as Flowable or Camuda to FortiSOAR™ playbooks.

This connector is ready to use, and you do not need to configure this connector. For more information on BPMN workflows and how they can be imported and used as FortiSOAR™ playbooks, see the "Importing the BPMN Shareable Workflows as FortiSOAR™ Playbooks" topic in the Playbooks Overview chapter in the FortiSOAR™ documentation.

For some of the enhancements, bug fixes, and various versions of the BPMN connector see the BPMN Connector Release Notes section.

Report Engine 

The Report Engine connector is used to generate FortiSOAR™ reports and save this report as a text pdf in the Reports > History page.

For some of the enhancements, bug fixes, and various versions of the Report Engine connector see the Report Engine Connector Release Notes section.

Troubleshooting the FortiSOAR™ Built-in connectors

IMAP connector displays an error when you perform a Health Check

The IMAP Built-in connector could display an error such as [ALERT Please log in via your web browser: https://support.google.com/mail/accounts/answer/78754 (Failure)] when you perform a Health Check by clicking the Refresh icon that is present in the Health Check bar.

Resolution

This issue occurs due to the Gmail security guidelines that consider that an untrusted device has tried to log in to the mail account. You must change the password of your mail account to resolve this issue.

IMAP connector displays errors while you are configuring the connector

The IMAP Built-in connector could display any of the following errors while you are configuring the connector:

Resolution

IMAP connector displays an error when the application private and public keys are missing in the integration module

The following error message is displayed when the application private and public keys are missing in the integration module:

CS-IMAP-11: Error occurred while getting the private or public key. File not found for keys. ERROR :: <error_message>

Resolution

Copy the appliance key from /opt/cyops-workflow/sealab/.envdir/APPLIANCE_*_KEY to the opt/cyops-integrations/integrations/configs folder and change its permissions to -rw-r--r-- nginx:nginx. Then, restart the uwsgi service.

IMAP connector displays an error when you try to restart the email notification service

The following error message is displayed when you try to restart the email notification service with the listener that is already in an inactive state:

CS-IMAP-17: Notification service is already down, bringing up the service

Resolution

Deactivate the connector, restart the uwsgi service, and again activate the connector. For more information on the error, check the log file located at: /var/log/cyops/cyops-integrations/imap/listener.log.

IMAP connector displays the`ERROR :: create failed: [ALREADYEXISTS] Folder name ...  error

The following error can occur when you are fetching data from IMAP using the Email Notification service:

> IMAP > Fetch" has failed because: CS-INTEGRATION-5: Error occurred while executing the connector action ERROR :: create failed: [ALREADYEXISTS] Folder name conflicts with existing folder name. (Failure) URL : https://127.0.0.1:9595/integration/execute/?format=json

The above error can occur due to the following reasons:

Resolution

Release Notes

Utilities Connector Release Notes

Version 3.0.5

Version 3.0.4

Version 3.0.3

Version 3.0.2

Version 3.0.1

Version 3.0.0

Version 2.7.0

Important: If you upgrade the Utilities connector to v2.7.0, then playbooks that contain the "Utils: Make REST API Call" and "CyOPs: Make CyOPs API Call" operations reset the get, put, post, and delete methods if they were not written in capital letters. This occurs due to the current enhancements in the Utilities connector v2.7.0. However, there will not be any functional impact due to this since the playbook will execute successfully after the upgrade, and you can correctly add the methods to the playbook post-upgrade.

Version 2.6.0 

Version 2.4.1 

Version 2.4.0

Apart from the above enhancements, the Utilities connector also contains better error handling, which includes displaying of enhanced, precise, and detailed error messages, making it easier for you to debug Utilities connector issues. For information on common Utilities connector issues, see the Common Utilities connector errors section in the Debugging common playbook and connector issues article present in the Fortinet Knowledge Base.

Version 2.3.0

Version 2.2.0

Version 2.1.3

Version 2.1.2

Version 2.1.0

Database Connector Release Notes

Version 2.1.1

Version 2.1.0

Version 2.0.2

Version 2.0.1

IMAP Connector Release Notes

Version 3.5.4

Version 3.5.2

Version 3.5.1

Version 3.5.0

Version 3.5.4

Fixed important bugs such as fixing the issue of failure to deactivate the IMAP connector if you had specified a non-default port. This issue used to occur when you were using the notification service in the IMAP connector, and you had specified a port that was not the default port, then you would get an error when you tried to deactivate the connector.

Version 3.3.2

Version 3.3.1

Version 3.3.0

Version 3.2.0

Version 3.0.2

Apart from the above enhancements, the IMAP connector also contains better error handling, which includes displaying enhanced, precise, and detailed error messages, making it easier for you to debug IMAP connector issues. For information on common IMAP connector issues, see the Common IMAP connector errors section in the Debugging common playbook and connector errors article present in the Fortinet Knowledge Base.

SMTP Connector Release Notes

Version 2.4.0

Version 2.3.3

Version 2.3.2

Version 2.3.1

Contains an updated logo.

Version 2.3.0

Version 2.2.0

Version 2.1.2

SOAP Connector Release Notes

Version 2.2.1

Version 2.1.0

SSH Connector Release Notes

Version 2.1.1

Version 2.1.0

Version 2.0.2

Code Snippet Connector Release Notes

Version 1.2.4

Version 1.2.3

Version 1.2.4

Version 1.2.1 

Version 1.2.0

System Monitoring Connector Release Notes

Version 1.3.0

Added monitoring of the cyops-integration-agent service, which supports running actions on remote agents.

Version 1.2.1

Version 1.2.0

Fixed an issue with the System Health Status dashboard to show the correct version of PostgreSQL, i.e, postgresql -12, in the Service Status listing. Version 1.2.0 also contains an updated logo.

BPMN Connector Release Notes

Version 1.0.2

Version 1.0.1

Report Engine Connector Release Notes

Version 1.1.0

Version 1.0.5

Version 1.0.4

Version 1.0.3

Version 1.0.2

Version 1.0.1