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: 2.0.0
Authored By: Community
Certified: No
Release Notes for version 2.0.0
Following enhancements have been made to the Mimecast S2 Connector in version 2.0.0:
- Added new parameters
Secret key and Access Key to connector configuration
- Removed existing parameters
User Name, Password, and Auth Type from connector configuration
- Updated the Create Incident action as per the new Mimecast S2 API:
- Removed the following parameters:
- Incident Type
- From
- To
- Unremediate Code
- Restore Code
- Updated the Archive Search action as per the new Mimecast S2 API:
- Removed the parameter Show
- Added a new parameter Page Size
- Updated the output schema for following actions:
- Create Incident
- Archive Search
- Message Search
Installing the connector
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command as a root user to install the connector:
yum install cyops-connector-mimecast-s2
Prerequisites to configuring the connector
- You must have the URL of the Mimecast S2 server to which you will connect and perform automated operations and credentials to access that server.
- The FortiSOAR™ server should have outbound connectivity to port 443 on the Mimecast S2 server.
Minimum Permissions Required
Following table illustrates permissions required for each action in this connector:
| Action |
Application Permissions |
| Create Incident |
Services | Threat Remediation | Edit |
| Archive Search |
Archive | Search | Read |
| Message Search |
Gateway | Tracking | Read |
| Get Archive Search Message Details |
Archive | Search Content View |
| Get Message Info |
Gateway | Tracking | Read |
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. |
| 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 |
| Access Key |
Specify the access key to access the Mimecast S2 API. |
| Secret Key |
Specify the secret key to access the Mimecast S2 API. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified.
By default, this option is set to 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:
| 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. |
archive_search
Investigation |
| Message Search |
Searches or tracks messages across the Mimecast S2 platform, based on the input parameters you have specified. |
message_search
Investigation |
| Get Archive Search Message Details |
Retrieves metadata for a specific message from the Mimecast S2 archives, based on the Mimecast ID you have specified. |
get_archive_search_message_details
Investigation |
| Get Message Info |
Retrieves information for a tracked message from the Mimecast S2 platform, based on the Mimecast ID you have specified. |
get_message_info
Investigation |
operation: Create Incident
Input parameters
| Parameter |
Description |
| Reason |
Specify the reason for creating the incident in the Mimecast S2 platform. |
| Search By |
Select the method to use for searching for a file or attachments in a specific message in the Mimecast S2 platform. You can choose from following options:
- Message ID: Specify the ID of the message, in the Message ID field to use for searching attachments in a specific message.
- FileHash: Specify the file hash, in the FileHash field to use for searching for a specific file in the Mimecast S2 platform.
- URL: Specify the URL present in the email that should be remediated. This field is required when setting
searchBy field to URL. The specified value must be a decoded, non-Mimecast, rewritten URL.
|
| Start |
Specify the start date from when to search for files or attachments in the Mimecast S2 platform.
By default, it is set to the last calendar month. |
| End |
Specify the 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. |
Output
The output contains the following populated JSON schema:
Output schema when you select Search By as FileHash:
{
"meta": {
"status": ""
},
"data": [
{
"code": "",
"type": "",
"reason": "",
"searchCriteria": {
"fileHash": "",
"start": "",
"end": ""
},
"create": "",
"modified": "",
"identified": "",
"successful": "",
"failed": "",
"restored": "",
"id": ""
}
],
"fail": []
}
Output schema when you select Search By as Message ID:
{
"meta": {
"status": ""
},
"data": [
{
"code": "",
"type": "",
"reason": "",
"searchCriteria": {
"messageId": "",
"start": "",
"end": ""
},
"create": "",
"modified": "",
"identified": "",
"successful": "",
"failed": "",
"restored": "",
"id": ""
}
],
"fail": []
}
operation: Archive Search
Input parameters
NOTE: All input parameters are optional. However, if you do not specify any parameter, no filter criteria is applied and an unfiltered list is returned.
| Parameter |
Description |
| Email ID |
Specify the 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 to False, i.e. the search is an end-user search. |
| Search Text |
Specify the text using which you want to search for or filter messages on the Mimecast S2 platform. |
| Time Period |
Specify the time period for which you want to query for messages received in the specified email address. |
| 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 matching the search criteria specified. |
| Page Size |
(Optional) Specify the number of results that are requested by this operation. |
| Page Token |
Specify the value of the Next or Previous fields from an earlier request. |
Output
The output contains the following populated JSON schema:
Output schema when you choose Get More Details as true:
{
"meta": {
"status": ""
},
"data": [
{
"items": [
{
"size": "",
"attachmentcount": "",
"subject": "",
"displayfrom": "",
"id": "",
"smash": "",
"displayto": "",
"receiveddate": "",
"status": "",
"more_details": {
"id": "",
"mimeMessageId": "",
"smash": "",
"subject": "",
"size": "",
"received": "",
"processed": "",
"status": "",
"hasHtmlBody": "",
"hasTextBody": "",
"isPassthrough": "",
"envelopeFrom": {
"emailAddress": "",
"displayableName": ""
},
"from": {
"emailAddress": "",
"displayableName": ""
},
"to": [
{
"emailAddress": ""
}
],
"cc": [],
"headerDate": "",
"headers": [
{
"name": "",
"values": []
}
],
"attachments": [
{
"id": "",
"filename": "",
"size": "",
"extension": "",
"contentType": "",
"contentId": "",
"sha256": "",
"bodyType": ""
}
],
"messageBodyPreview": "",
"isCcm": ""
}
}
],
"queryDuration": ""
}
],
"fail": []
}
This is the default output schema:
{
"meta": {
"status": ""
},
"data": [
{
"items": [
{
"size": "",
"attachmentcount": "",
"subject": "",
"displayfrom": "",
"id": "",
"displayto": "",
"receiveddate": "",
"status": ""
}
],
"queryDuration": ""
}
],
"fail": []
}
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 |
| Search By |
Select the method based on which to search for or track on the Mimecast S2 platform. You can choose from following options:
The remaining parameters are common to both the Advanced Track and Trace Option and Message ID options.
|
| Search Reason |
Specify the reason for searching for or tracking the messages on the Mimecast S2 platform. |
| Start Time |
Specify the date and time from when to search for or track on the Mimecast S2 platform. |
| End Time |
Specify the date and time till when 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:
Output schema when you choose Get Message Info as true:
{
"meta": {
"status": ""
},
"data": [
{
"trackedEmails": [
{
"info": "",
"id": "",
"status": "",
"fromEnv": {
"displayableName": "",
"emailAddress": ""
},
"fromHdr": {
"displayableName": "",
"emailAddress": ""
},
"to": [
{
"displayableName": "",
"emailAddress": ""
}
],
"received": "",
"subject": "",
"senderIP": "",
"attachments": "",
"route": "",
"sent": "",
"get_message_info": {
"recipientInfo": {
"messageInfo": {
"fromHeader": "",
"fromEnvelope": "",
"to": [],
"cc": [],
"subject": "",
"sent": "",
"processed": "",
"transmissionInfo": ""
},
"recipientMetaInfo": {
"receiptEvent": "",
"spamEvent": "",
"messageExpiresIn": "",
"processingServer": "",
"transmissionSize": "",
"binaryEmailSize": "",
"remoteIp": "",
"remoteHost": "",
"remoteServerGreeting": "",
"receiptAcknowledgement": "",
"transmissionStart": "",
"transmissionEnd": "",
"encryptionInfo": "",
"components": [
{
"type": "",
"name": "",
"extension": "",
"mimeType": "",
"size": "",
"hash": ""
}
]
}
},
"deliveredMessage": {
"devops@cybersponse.in": {
"messageInfo": {
"fromHeader": "",
"fromEnvelope": "",
"to": [],
"cc": [],
"subject": "",
"sent": "",
"processed": "",
"transmissionInfo": "",
"route": ""
},
"policyInfo": [
{
"policyType": "",
"policyName": "",
"inherited": ""
}
],
"deliveryMetaInfo": {
"deliveryEvent": "",
"emailAddress": "",
"messageExpiresIn": "",
"processingServer": "",
"transmissionSize": "",
"remoteIp": "",
"remoteHost": "",
"remoteServerGreeting": "",
"receiptAcknowledgement": "",
"transmissionStart": "",
"transmissionEnd": "",
"encryptionInfo": "",
"components": [
{
"type": "",
"name": "",
"extension": "",
"mimeType": "",
"size": "",
"hash": ""
}
]
}
}
},
"retentionInfo": {
"currentPurgeDate": "",
"purgeBasedOn": "",
"originalPurgeDate": "",
"retentionAdjustmentDays": "",
"litigationHoldInfo": [],
"fbrStamps": [],
"smartTags": [],
"fbrExpireCheck": [],
"audits": []
},
"status": "",
"id": ""
}
}
]
}
],
"fail": []
}
This is the default output schema:
{
"fail": [],
"meta": {
"status": ""
},
"data": [
{
"trackedEmails": [
{
"status": "",
"received": "",
"fromEnv": {
"displayableName": "",
"emailAddress": ""
},
"fromHdr": {
"displayableName": "",
"emailAddress": ""
},
"attachments": "",
"to": [
{
"displayableName": "",
"emailAddress": ""
}
],
"senderIP": "",
"route": "",
"id": "",
"sent": "",
"subject": ""
}
]
}
]
}
operation: Get Archive Search Message Details
Input parameters
| Parameter |
Description |
| Mimecast ID |
Specify the internal 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:
{
"fail": [],
"meta": {
"status": ""
},
"data": [
{
"status": "",
"smash": "",
"mimeMessageId": "",
"hasHtmlBody": "",
"attachments": [
{
"contentType": "",
"extension": "",
"contentId": "",
"filename": "",
"bodyType": "",
"sha256": "",
"id": "",
"size": ""
}
],
"received": "",
"replyTo": {
"displayableName": "",
"emailAddress": ""
},
"cc": [
{
"displayableName": "",
"emailAddress": ""
}
],
"from": {
"displayableName": "",
"emailAddress": ""
},
"isPassthrough": "",
"envelopeFrom": {
"displayableName": "",
"emailAddress": ""
},
"headers": [
{
"values": [],
"name": ""
}
],
"to": [
{
"displayableName": "",
"emailAddress": ""
}
],
"processed": "",
"hasTextBody": "",
"headerDate": "",
"messageBodyPreview": "",
"subject": "",
"id": "",
"size": ""
}
]
}
operation: Get Message Info
Input parameters
| Parameter |
Description |
| Mimecast ID |
Specify the 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:
{
"fail": [],
"meta": {
"status": ""
},
"data": [
{
"status": "",
"retentionInfo": {
"currentPurgeDate": "",
"originalPurgeDate": "",
"retentionAdjustmentDays": "",
"fbrExpireCheck": [],
"fbrStamps": [],
"audits": [],
"litigationHoldInfo": [],
"smartTags": [],
"purgeBasedOn": ""
},
"recipientInfo": {
"messageInfo": {
"attachments": [],
"cc": [],
"htmlBody": "",
"transmissionInfo": "",
"fromHeader": "",
"subject": "",
"textBody": "",
"to": [],
"processed": "",
"fromEnvelope": "",
"sent": ""
},
"recipientMetaInfo": {
"remoteServerGreeting": "",
"encryptionInfo": "",
"receiptAcknowledgement": "",
"receiptEvent": "",
"transmissionEnd": "",
"spamEvent": "",
"messageExpiresIn": "",
"processingServer": "",
"binaryEmailSize": "",
"transmissionSize": "",
"remoteHost": "",
"transmissionStart": "",
"remoteIp": "",
"components": [
{
"mimeType": "",
"type": "",
"name": "",
"extension": "",
"size": ""
}
]
}
},
"deliveredMessage": {
"user@domain.com": {
"messageInfo": {
"attachments": [],
"cc": [],
"htmlBody": "",
"transmissionInfo": "",
"fromHeader": "",
"subject": "",
"route": "",
"textBody": "",
"to": [],
"processed": "",
"fromEnvelope": "",
"sent": ""
},
"policyInfo": [
{
"policyName": "",
"policyType": "",
"inherited": ""
}
],
"deliveryMetaInfo": {
"remoteServerGreeting": "",
"encryptionInfo": "",
"receiptAcknowledgement": "",
"emailAddress": "",
"messageExpiresIn": "",
"processingServer": "",
"transmissionSize": "",
"remoteHost": "",
"transmissionStart": "",
"remoteIp": "",
"components": [
{
"mimeType": "",
"type": "",
"name": "",
"extension": "",
"size": ""
}
],
"transmissionEnd": "",
"deliveryEvent": ""
}
}
},
"id": ""
}
]
}
Included playbooks
The Sample - Mimecast S2 - 2.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.
