Swimlane Email Connector

The Email connector facilitates the automation of email management and analysis tasks, supporting essential email protocols and enabling seamless integration with email services.

The Email connector for Swimlane Turbine provides a comprehensive suite of actions for email management and automation within security workflows. It enables users to retrieve email metadata, manage email attachments with precision, ingest emails for automated processing, and send emails directly from the Swimlane platform. By integrating with the Email connector, Swimlane Turbine users can streamline their incident response and automate routine email-related tasks, enhancing the efficiency and effectiveness of their security operations.

Prerequisites

To effectively utilize the Email connector within Swimlane Turbine, ensure you have the following prerequisites:

OAuth2 client credentials for Microsoft Graph API authentication with the following parameters:

Host: The server hosting the email service.

Client ID: The unique identifier for your application.

Client Secret: A secret key used to authenticate your application.

Tenant ID: The directory tenant that you want to request permission from.

Refresh Token: Token used to obtain a new access token when the current one expires.

Scopes: Permissions the app requires.

Custom authentication for other email services with the following parameters:

Host: The server hosting the email service.

User: The username required to access the email service.

Authentication for OAuth2 Refresh Token Grant credentials for Microsoft Graph API authentication

Oauth 2.0 refresh token grant, which requires a 'Refresh Token', 'Tenant ID', 'Client ID' and 'Client Secret'. Use this auth with accounts which have MFA enabled. To generate a refresh token please follow the instructions below.

In step 3 of the above-mentioned setup instructions, please provide a 'Redirect URI' and select the platform as 'Web', before clicking on 'Register' at the the bottom.

Proceed with the remaining steps to generate 'Client ID', 'Tenant ID' and 'Client Secret'.

The Swimlane team will provide a Python script and instructions on how to use the script to generate the Refresh Token.

Capabilities

The Swimlane Email connector has the following capabilities:

Ingest Emails from IMAP4 or POP3 Server (configure protocol in the custom asset)

Send Email to SMTP Server

Action: Send Email

The action Send Email allows to override the headers of the email. However, "txt_msg", "html_msg", "from" and "to" are not allowed to be overridden. The "override_headers" field needs to be a JSON valid string:

{
  "Subject": "New Subject",
  "X-custom-header": "Custom Header Value",
  "Bcc": "[email protected]"
}

To use OAuth2 Refresh Token Grant credentials for Microsoft Graph API authentication:

Open the Microsoft 365 admin center and go to Users > Active users.

Select the user, and in the flyout that appears, select Mail.

In the Email apps section, select Manage email apps.

Verify the Authenticated SMTP setting: unchecked = disabled, checked = enabled.

When you're finished, select Save changes.

Common Errors

[errno 101] Network is unreachable: This can be caused by choosing the wrong Verify SSL option in the asset. The port changes depending on whether ssl is enabled or not, so if you try to connect to a server that only allows ssl connections with Verify SSL disabled, it could cause this error.

Configurations

IMAP/SMTP Authentication

Configuration Parameters

Parameter	Description	Type	Required
host	The host of the email server.	string	Required
user	User	string	Required
password	Password	string	Optional
protocol	Protocol used for ingesting emails. IMAP4 supports multiple mailboxes and filters; POP3 uses a single inbox and fetches all messages.	string	Optional
use_ssl	Use SSL	boolean	Optional
imap_starttls	Enable STARTTLS to upgrade the connection to SSL/TLS.	boolean	Optional
imap_port	Port of the IMAP4 Server.	number	Optional
pop3_port	Port of the POP3 Server (typically 995 for SSL, 110 for non-SSL).	number	Optional
smtp_starttls	Enable STARTTLS to upgrade the connection to SSL/TLS.	boolean	Optional
smtp_port	Port of the SMTP Server.	number	Optional

Swimlane Email Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials and refresh token. This is used for Microsoft Graph API.

Configuration Parameters

Parameter	Description	Type	Required
host	The host of the email server.	string	Required
tenant_id	The tenant ID.	string	Required
client_id	The client ID.	string	Required
client_secret	The client secret.	string	Required
refresh_token	The refresh token.	string	Required
scope	Permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate.	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Get Email Metadata

Retrieve metadata, including headers and relevant details, for a specified email attachment.

Endpoint

Method: GET

Input

Argument Name	Type	Required	Description
email_attachment	array	Required	File to be attached
rfc882	boolean	Optional	Check if emails adhere to rfc882 format
remove_raw_content	boolean	Optional	Remove the RAW_CONTENT key of the email from the outputs. Defaults to False.
remove_content_id	boolean	Optional	Removes the Content-ID property from the Raw content
remove_raw_headers	boolean	Optional	Remove the RAW_HEADERS key of the email from the response. Defaults to False.
exclude_extensions	string	Optional	A csv of extensions you would like to ignore. Useful if image files are being parsed out of email footer as attachments. Default is .jp(e)g, .png, .gif. Filling this value will OVERWRITE existing default
include_only_extensions	string	Optional	Only include these extension types from the attachments of the parsed email. Overrides excluded extensions. Defaults to None.
remove_embedded_images	boolean	Optional	If True, removes all image elements from text and HTML bodies. Defaults to False.
ignore_errors	boolean	Optional	Ignore errors parsing an email. Defaults to False
use_cid_names	boolean	Optional	Use CIDs as filenames in eml files.

Input Example

{"email_attachment":["string"],"rfc882":true,"remove_raw_content":true,"remove_content_id":true,"remove_raw_headers":true,"exclude_extensions":"string","include_only_extensions":"string","remove_embedded_images":true,"ignore_errors":true,"use_cid_names":true}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
headers	object	HTTP headers for the request
reason	string	Response reason phrase
metadata	object	Response data
metadata.result	string	Response data
metadata.attachments_sha1	string	Response data
metadata.attachments_md5	string	Response data
metadata.attach_info	array	Response data
metadata.attach_info.content-type	string	Response data
metadata.attach_info.content-disposition	string	Response data
metadata.attach_info.content-transfer-encoding	string	Response data
metadata.attach_info.content-id	string	Response data
metadata.attach_info.x-attachment-id	string	Response data
metadata.headers	string	Response data
metadata.recipients	string	Response data
metadata.subject	string	Response data
metadata.text_body	string	Response data
metadata.html_body	string	Response data
metadata.type	string	Response data
metadata.attachments_sha256	string	Response data
metadata.cc	string	Response data
metadata.bcc	string	Response data
metadata.raw_headers	string	Response data
metadata.raw_content	string	Response data
metadata.headers_json	string	Response data

Output Example

{"status_code":200,"headers":null,"reason":"Ok","metadata":{"result":"success","attachments_sha1":"28a0ab5e6b6eb3d00a686a6a6c509a02feb506b8","attachments_md5":"d223b0dbacbddfa3c37047f2573c3b11","attach_info":[{}],"headers":"Received: from IA0PR14MB6188.namprd14.prod.outlook.com (2603:10b6:208:440::14) b...","recipients":"[email protected]","subject":"sample 1","text_body":"Here is an attachment and some links\r\n\r\nhttps://www.exoduspoint.com\r\n\r\nhttps://w...","html_bo...

Get Email Metadata Attachments in List

Retrieve metadata for email attachments, including names, types, and sizes, based on the specified email_attachment input.

Endpoint

Method: GET

Input

Argument Name	Type	Required	Description
email_attachment	array	Required	File to be attached
rfc882	boolean	Optional	Check if emails adhere to rfc882 format
remove_raw_content	boolean	Optional	Remove the RAW_CONTENT key of the email from the outputs. Defaults to False.
remove_raw_headers	boolean	Optional	Remove the RAW_HEADERS key of the email from the response. Defaults to False.
exclude_extensions	string	Optional	A csv of extensions you would like to ignore. Useful if image files are being parsed out of email footer as attachments. Default is .jp(e)g, .png, .gif. Filling this value will OVERWRITE existing default
include_only_extensions	string	Optional	Only include these extension types from the attachments of the parsed email. Overrides excluded extensions. Defaults to None.
remove_embedded_images	boolean	Optional	If True, removes all image elements from text and HTML bodies. Defaults to False.
ignore_errors	boolean	Optional	Ignore errors parsing an email. Defaults to False
use_cid_names	boolean	Optional	Use CIDs as filenames in eml files.

Input Example

{"email_attachment":["string"],"rfc882":true,"remove_raw_content":true,"remove_raw_headers":true,"exclude_extensions":"string","include_only_extensions":"string","remove_embedded_images":true,"ignore_errors":true,"use_cid_names":true}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
headers	object	HTTP headers for the request
reason	string	Response reason phrase
metadata	object	Response data
metadata.result	string	Response data
metadata.attachments_sha1	string	Response data
metadata.attachments_md5	string	Response data
metadata.attach_info	array	Response data
metadata.attach_info.content-type	string	Response data
metadata.attach_info.content-disposition	string	Response data
metadata.attach_info.content-transfer-encoding	string	Response data
metadata.attach_info.content-id	string	Response data
metadata.attach_info.x-attachment-id	string	Response data
metadata.headers	string	Response data
metadata.recipients	string	Response data
metadata.subject	string	Response data
metadata.text_body	string	Response data
metadata.html_body	string	Response data
metadata.type	string	Response data
metadata.attachments_sha256	string	Response data
metadata.cc	string	Response data
metadata.bcc	string	Response data
metadata.raw_headers	string	Response data
metadata.raw_content	string	Response data
metadata.headers_json	string	Response data

Output Example

Ingest Email

Automatically processes and analyzes incoming emails for response in Swimlane, supporting IMAP4 (with mailbox and filter) and POP3 protocols.

Endpoint

Method: GET

Input

Argument Name	Type	Required	Description
mailbox	string	Optional	Mailbox to ingest emails from (IMAP4 only; ignored for POP3).
filter	string	Optional	Filter to apply when ingesting emails (IMAP4 only; ignored for POP3).
mark_as_read	boolean	Optional	Mark ingested emails as read (IMAP4 only; not supported for POP3).

Input Example

{"mailbox":"Inbox","filter":"ALL","mark_as_read":true}

Send Email

Initiates the sending of an email from a specified address to one or more recipients, requiring 'from' and 'to' fields.

Endpoint

Method: GET

Input

Argument Name	Type	Required	Description
subject	string	Optional	Parameter for Send Email
from	string	Required	Parameter for Send Email
to	array	Required	Parameter for Send Email
cc	array	Optional	Parameter for Send Email
bcc	array	Optional	Parameter for Send Email
in_reply_to	string	Optional	Parameter for Send Email
reply_to	string	Optional	Parameter for Send Email
references	array	Optional	Parameter for Send Email
text_msg	string	Optional	Parameter for Send Email
html_msg	string	Optional	Parameter for Send Email
headers_override	string	Optional	HTTP headers for the request
attachments	array	Optional	Files to be attached
attachments.file	string	Optional	Parameter for Send Email
attachments.file_name	string	Optional	Name of the resource

Input Example

{"subject":"Hello World!","from":"[email protected]","to":["[email protected]","[email protected]"],"cc":["[email protected]"],"bcc":["[email protected]"],"in_reply_to":"<[email protected]>","reply_to":"[email protected]","references":["[email protected]","[email protected]"],"text_msg":"This is the plain text version of the message.","html_msg":"<p>This is the <b>HTML</b> version of the message.</p>","headers_override":"{'X-My-Header': 'value'}"}

Output

Parameter	Type	Description
success	boolean	Whether the operation was successful

Output Example

{"success":true}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT