About the connector
Mimecast S2 protects the organization against advanced cyberattacks on all devices, from anywhere.
This document provides information about the Mimecast S2 connector, which integrates with Mimecast S2 endpoints and provides cloud-based email management for Microsoft Exchange and Microsoft Office 365, and offers threat monitoring and remediation service for internally generated emails. Use the Mimecast S2 connector that facilitates automated interactions, with a Mimecast S2 server and API application using FortiSOAR™ playbooks. Add the Mimecast S2 connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating incidents on the Mimecast S2 platform and retrieving a list of messages from the Mimecast S2 platform.
Version information
Connector Version: 1.0.0
Authored By: Community
Certified: No
Installing the connector
From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™repository and run the yum command as a root user to install connectors:
yum install cyops-connector-mimecast-s2
Prerequisites to configuring the connector
- You must have the URL of Mimecast S2 server to which you will connect and perform automated operations and credentials to access that server.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, click the Mimecast S2 connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:
| Parameter |
Description |
| Server URL |
URL of the Mimecast S2 server to which you will connect and perform the automated operations. |
| Auth Type |
Type of authentication you will use to connect to the Mimecast S2 API application. The Mimecast S2 API application supports two types of authentication: Basic-Cloud and Basic-AD. This version of the Mimecast S2 connector supports only Basic-Cloud authentication. |
| User Name |
Username used to access the Mimecast S2 administration console. |
| Password |
Password used to access the Mimecast S2 administration console. |
| Application ID |
Unique API application ID of the Mimecast S2 API application that is used to create an authentication token that you can use to access the application |
| Application Key |
Unique Application Key of the Mimecast S2 API application that is used to create an authentication token that you can use to access the application |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 and onwards:
| Function |
Description |
Annotation and Category |
| Create Incident |
Creates a remediation or restore incident in the Mimecast S2 platform, based on the input parameters you have specified. |
create_incident
Investigation |
| Archive Search |
Retrieves a list of messages from the Mimecast S2 platform that match the search criteria that you have specified.
Important: In order to use this operation the logged in user must be a Mimecast administrator with at least the Gateway | Tracking | Read permission. |
archive_search
Investigation |
| Message Search |
Searches or tracks messages across the Mimecast S2 platform, based on the input parameters you have specified.
Important: In order to use this operation the logged in user must be a Mimecast administrator with at least the Gateway | Tracking | Read permission. |
message_search
Investigation |
| Get Archive Search Message Details |
Retrieves metadata for a specific message from the Mimecast S2 archives, based on the message ID you have specified.
Important: In order to use this operation the logged in user must be a Mimecast administrator with at least the Archive | Search Content View permission. Also, to allow this operation to loads messages sent or received by the logged in user or from an address of the logged in user, the user must have delegate permission, no administrator permissions are required. |
get_archive_search_message_details
Investigation |
| Get Message Info |
Retrieves information for a tracked message from the Mimecast S2 platform, based on the message ID you have specified.
Important: In order to use this operation the logged in user must be a Mimecast administrator with at least the Gateway | Tracking | Read permission. |
get_message_info
Investigation |
operation: Create Incident
Input parameters
| Parameter |
Description |
| Reason |
Reason due to which you are creating the incident in the Mimecast S2 platform. |
| Search By |
Method that you want to use for searching for a file or attachments in a specific message in the Mimecast S2 platform. You can choose between FileHash or Message ID.
- If you select Message ID, then provide the ID of the message that you want to use for searching all attachments for the specific message.
- If you select FileHash, then provide the SHA-256 filehash that you want to search for a specific file in the Mimecast S2 platform.
|
| Incident Type |
Type of incident that you want to create in the Mimecast S2 platform.
You can choose between Remediate or Restore. |
| From |
(Optional) Address or domain name of the sender. |
| To |
(Optional) Email address or domain name of the recipients. |
| Start |
Start date from when you want to search for files or attachments in the Mimecast S2 platform.
By default, it is set to the last calendar month. |
| End |
End date till when you want to search for files or attachments in the Mimecast S2 platform.
By default, it is set to the end of today. |
| Unremediate code |
Code that will be used for unremediating the message. |
| Restore Code |
Code that will be used for restoring the message. |
Output
The output contains the following populated JSON schema:
{
"meta": {
"status": ""
},
"fail": [],
"data": [
{
"successful": "",
"modified": "",
"type": "",
"reason": "",
"create": "",
"code": "",
"restored": "",
"searchCriteria": {
"to": "",
"from": "",
"unremediateCode": "",
"end": "",
"fileHash": "",
"restoreCode": "",
"messageId": "",
"start": ""
},
"id": "",
"failed": ""
}
]
}
operation: Archive Search
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.
| Parameter |
Description |
| Email ID |
Email address that is configured in Mimecast S2 whose messages you want to search on the Mimecast S2 platform. |
| Admin |
Select this option, i.e., set it to True, if this search is an administrative search. By default, this is set as False, i.e. the search is an end-user search. |
| Search Text |
Text using which you want to search for or filter messages on the Mimecast S2 platform. |
| Time Period |
Time period for which you want to query for messages received in the specified email address. |
| Show |
Define the time period for which you want to query for messages received in the specified email address on the Mimecast S2 platform. |
| Document Type |
Select the type of document (attachment) based on which you want to search for messages received in the specified email address on the Mimecast S2 platform. Some of the options you can choose from are Spreadsheets, Documents, Text, Presentations, etc |
| Get More Details |
Select this option, i.e., set it to True, to retrieve metadata of the message, which matches the search criteria that you have specified. |
| Page Token |
Value of the Next or Previous fields from an earlier request. |
Output
The output contains the following populated JSON schema:
{
"meta": {
"status": "",
"pagination": {
"next": "",
"pageSize": "",
"recordStart": ""
}
},
"fail": [],
"data": [
{
"status": "",
"subject": "",
"size": "",
"id": "",
"smash": "",
"displayto": "",
"receiveddate": "",
"attachmentcount": "",
"displayfrom": ""
}
]
}
operation: Message Search
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied and an unfiltered list is returned.
| Parameter |
Description |
| |
Method based on which you want to search for or track on the Mimecast S2 platform. You can choose between Advanced Track and Trace Option or Message ID.
If you select the Advanced Track and Trace Option option, then you must specify the following parameters:
- Sender Email ID: Email address or domain of the sender of the messages that you want to search for or track on the Mimecast S2 platform.
- Recipient Email ID: Email address or domain of the recipient of the messages that you want to search for or track on the Mimecast S2 platform.
- Subject: Subject of the messages that you want to search for or track on the Mimecast S2 platform.
- Sender IP: Source IP address of the messages that you want to search for or track on the Mimecast S2 platform.
If you select the Message ID option, then you must specify the following parameters:
- Message ID: Internet message ID of the message that you want to search for or track on the Mimecast S2 platform.
Note: In this field, you should provide the mimeMessageId values that you can retrieve using the Get Archive Search Message Details operation.
The remaining parameters are common to both the Advanced Track and Trace Option and Message ID options.
|
| Search Reason |
Reason for searching for or tracking the messages on the Mimecast S2 platform. |
| Start Time |
Date and time from when you want to search for or track on the Mimecast S2 platform. |
| End Time |
Date and time till when you want to search for or track on the Mimecast S2 platform. |
| Get Message Info |
Select this option, i.e., set it to True, to retrieve detailed information for searched messages retrieved from the Mimecast S2 platform, based on the filter criteria you have specified. |
Output
The output contains the following populated JSON schema:
{
"conditional_output_schema": [
{
"output_schema": {
"trackedEmails": [
{
"attachments": "",
"senderIP": "",
"get_message_info": {
"retentionInfo": {
"fbrStamps": [],
"smartTags": [],
"currentPurgeDate": "",
"purgeBasedOn": "",
"fbrExpireCheck": [],
"retentionAdjustmentDays": "",
"originalPurgeDate": "",
"litigationHoldInfo": [],
"audits": [
{
"date": "",
"type": "",
"info": ""
}
]
},
"status": "",
"deliveredMessage": {
"devops@cybersponse.in": {
"messageInfo": {
"cc": [],
"subject": "",
"to": [],
"fromHeader": "",
"sent": "",
"transmissionInfo": "",
"fromEnvelope": "",
"processed": "",
"route": ""
},
"deliveryMetaInfo": {
"emailAddress": "",
"messageExpiresIn": "",
"remoteHost": "",
"transmissionStart": "",
"deliveryEvent": "",
"transmissionEnd": "",
"components": [
{
"extension": "",
"size": "",
"type": "",
"name": "",
"hash": "",
"mimeType": ""
}
],
"processingServer": "",
"receiptAcknowledgement": "",
"transmissionSize": "",
"remoteIp": "",
"remoteServerGreeting": "",
"encryptionInfo": ""
},
"policyInfo": [
{
"inherited": "",
"policyName": "",
"policyType": ""
}
]
}
},
"id": "",
"recipientInfo": {
"messageInfo": {
"cc": [],
"subject": "",
"to": [],
"fromHeader": "",
"sent": "",
"transmissionInfo": "",
"fromEnvelope": "",
"processed": ""
},
"recipientMetaInfo": {
"messageExpiresIn": "",
"remoteHost": "",
"transmissionStart": "",
"transmissionEnd": "",
"components": [
{
"extension": "",
"size": "",
"type": "",
"name": "",
"hash": "",
"mimeType": ""
}
],
"processingServer": "",
"receiptAcknowledgement": "",
"transmissionSize": "",
"receiptEvent": "",
"remoteIp": "",
"spamEvent": "",
"remoteServerGreeting": "",
"encryptionInfo": "",
"binaryEmailSize": ""
}
}
},
"to": [
{
"emailAddress": "",
"displayableName": ""
}
],
"fromHdr": {
"emailAddress": "",
"displayableName": ""
},
"fromEnv": {
"emailAddress": "",
"displayableName": ""
},
"subject": "",
"route": "",
"status": "",
"info": "",
"sent": "",
"received": "",
"id": ""
}
]
},
"condition": "{{get_message_info === true}}"
},
{
"output_schema": {
"meta": {
"status": ""
},
"fail": [],
"data": [
{
"trackedEmails": [
{
"attachments": "",
"status": "",
"subject": "",
"to": [
{
"emailAddress": "",
"displayableName": ""
}
],
"fromHdr": {
"emailAddress": "",
"displayableName": ""
},
"sent": "",
"fromEnv": {
"emailAddress": "",
"displayableName": ""
},
"received": "",
"id": "",
"senderIP": "",
"route": ""
}
]
}
]
},
"condition": "{{true}}"
}
]
}
operation: Get Archive Search Message Details
Input parameters
| Parameter |
Description |
| Message ID |
Mimecast ID of the message whose metadata information you want to retrieve from the Mimecast S2 archives.
Use the Archive Search operation to retrieve the message IDs for existing messages in the Mimecast archives. |
Output
The output contains the following populated JSON schema:
{
"meta": {
"status": ""
},
"fail": [],
"data": [
{
"attachments": [
{
"contentType": "",
"extension": "",
"sha256": "",
"bodyType": "",
"id": "",
"contentId": "",
"filename": "",
"size": ""
}
],
"size": "",
"subject": "",
"to": [
{
"emailAddress": "",
"displayableName": ""
}
],
"isPassthrough": "",
"headerDate": "",
"mimeMessageId": "",
"replyTo": {
"emailAddress": "",
"displayableName": ""
},
"cc": [
{
"emailAddress": "",
"displayableName": ""
}
],
"status": "",
"processed": "",
"from": {
"emailAddress": "",
"displayableName": ""
},
"headers": [
{
"name": "",
"values": []
}
],
"smash": "",
"hasHtmlBody": "",
"received": "",
"id": "",
"envelopeFrom": {
"emailAddress": "",
"displayableName": ""
},
"messageBodyPreview": "",
&nbnbsp; "hasTextBody": ""
}
]
}
operation: Get Message Info
Input parameters
| Parameter |
Description |
| Message ID |
Mimecast ID of the message whose information you want to retrieve from Mimecast S2.
Use the Message Search operation to retrieve the message IDs for tracked messages. |
Output
The output contains the following populated JSON schema:
{
"meta": {
"status": ""
},
"fail": [],
"data": [
{
"retentionInfo": {
"fbrStamps": [],
"currentPurgeDate": "",
"smartTags": [],
"fbrExpireCheck": [],
"retentionAdjustmentDays": "",
"originalPurgeDate": "",
"purgeBasedOn": "",
"audits": [],
"litigationHoldInfo": []
},
"status": "",
"deliveredMessage": {
"user@domain.com": {
"messageInfo": {
"attachments": [],
"subject": "",
"to": [],
"textBody": "",
"processed": "",
"route": "",
"cc": [],
"htmlBody": "",
"fromHeader": "",
"sent": "",
"transmissionInfo": "",
"fromEnvelope": ""
},
"deliveryMetaInfo": {
"emailAddress": "",
"messageExpiresIn": "",
"remoteHost": "",
"transmissionStart": "",
"deliveryEvent": "",
"transmissionEnd": "",
"components": [
{
"name": "",
"extension": "",
"type": "",
"mimeType": "",
"size": ""
}
],
"processingServer": "",
"receiptAcknowledgement": "",
"remoteServerGreeting": "",
"remoteIp": "",
"transmissionSize": "",
"encryptionInfo": ""
},
"policyInfo": [
{
"inherited": "",
"policyName": "",
"policyType": ""
}
]
}
},
"id": "",
"recipientInfo": {
"messageInfo": {
"attachments": [],
"cc": [],
"subject": "",
"htmlBody": "",
"fromHeader": "",
"sent": "",
"transmissionInfo": "",
"fromEnvelope": "",
"textBody": "",
"processed": "",
"to": []
},
"recipientMetaInfo": {
"transmissionStart": "",
"messageExpiresIn": "",
"remoteHost": "",
"receiptEvent": "",
"transmissionEnd": "",
"components": [
{
"name": "",
"extension": "",
"type": "",
"mimeType": "",
"size": ""
}
],
"processingServer": "",
"receiptAcknowledgement": "",
"remoteServerGreeting": "",
"remoteIp": "",
"spamEvent": "",
"transmissionSize": "",
"encryptionInfo": "",
"binaryEmailSize": ""
}
}
}
]
}
Included playbooks
The Sample - Mimecast S2 - 1.0.0 playbook collection comes bundled with the Mimecast S2 connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Mimecast S2 connector.
- Archive Search
- Create Incident
- Get Archive Search Message Details
- Get Message Info
- Message Search
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
