Overview
FortiSOAR™ provides you with a number of pre-installed connectors or built-ins, such as the IMAP or Database connectors 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.
Apart from the FortiSOAR™ Built-in connectors, Fortinet also provides a number of connectors for popular integrations like SIEMs, such as FortiSIEM, Splunk, etc., and Ticketing systems such as Jira. You can see a list of published connectors on the FortiSOAR Connectors Documentation site.
The process of installing, configuring, and using connectors is defined in the Introduction to connectors chapter in the "Connectors Guide", which is part of the FortiSOAR™ documentation or see the Installing a connector and Configuring a connector articles.
FortiSOAR™ Built-in connectors are upgraded by default with a FortiSOAR™ upgrade. Use the Content Hub to upgrade your connectors to the latest version, in case you want to only upgrade the connectors and not FortiSOAR™. For more information on the connector store, see the Introduction to connectors chapter and see the FortiSOAR Built-in connectors article.
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.
IMAP
Use this connector to set up multiple email accounts and fetch emails from different email accounts.
NOTE: The IMAP built-in connector is dependent on the Utilities connector. Therefore, if you remove the Utilities connector, the IMAP connector will not work.
Version information
Connector Version: 3.5.7
Authored By: Fortinet
Certified: Yes
Release Notes for version 3.5.7
Following enhancements have been made to the IMAP connector in version 3.5.7:
- Updated the 'Documentation' link to point to the specific version of the IMAP connector.
NOTE: For more information on previous releases of the IMAP connector, see the IMAP Connector v3.5.6 document.
Configuration parameters
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IMAP connector card. On the connector popup, click the Configurations tab to enter the required configuration details.
| Parameter |
Description |
| Host |
Specify the Hostname of the email server to which you will connect and perform the automated operations. |
| Port |
Specify the Port number used for connecting to the email server. |
| Username |
Specify the username to access the email server to which you will connect and perform automated operations. |
| Password |
Specify the password to access the email server to which you will connect and perform automated operations. |
| Use TLS |
Select this option if you want to use TLS to communicate with the email server. |
| Email Source |
Specify the source from where the IMAP connector should read emails. By default, this is set as 'INBOX'.
NOTE: 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. |
| Email destination |
Specify the destination folder where the IMAP connector should move the email after they are read. By default, this is set as 'PROCESSED'. |
| Enable Email Notification Service |
Select this option if you want to set up a listener that instantly sends a notification to FortiSOAR when a new email arrives in the folder that you have specified as the 'Email Source', for example, 'Inbox'.
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 have selected the 'Enable Email Notification Service' checkbox, then you must specify the following parameters:
- Listener Port: Specify the port number of the listener. By default, it is set as '10010'
- Playbook Trigger: Specify the name of the playbook trigger for fetching emails.
|
| Verify SSL |
Select this option if you want to verify the SSL certificate of the email server.
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. |
Actions supported by the connector
The following automated operations can be included in playbooks:
| Function |
Description |
| Fetch Email(s) |
Fetches emails from the email source folder, for example, Inbox, that you have specified in the 'Configuration' parameters, then this operation breaks the various sections of an email, and returns a dictionary containing the parts of the email as 'keys'. |
| Fetch Email(s) Deprecated |
This operation is retained for backward compatibility and it is recommended that you do not use this action.
Note: This operation does not require any input parameters. |
operation: Fetch Email(s)
Input parameters
| Parameter |
Description |
| Maximum number of emails to fetch |
Specify the maximum number of emails that you want to fetch in a single operation. By default, this is set as '30'. |
| Parse inline images |
Select this option (selected by default) to extract inline images from emails. |
Troubleshooting issues with the IMAP connector
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.
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's 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 logfile 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
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.
The above error can occur due to the following reasons:
- 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.
- 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.
