Mimecast
Mimecast is a cloud-based email management system that detects threats hidden in your email. If you have Mimecast licensed, you can send specific types of events to InsightIDR, where they will generate Virus Infection and Web Proxy detections.
There are two ways to send data from your Mimecast account to InsightIDR; event collection through the Cloud or through an on-premises Rapid7 Collector.
Cloud event sources are being phased in from December 2023
InsightIDR is adding cloud event collection capabilities to a select number of supported event sources; this one is included. This will be a phased release, so if your environment is not yet displaying the Run on Cloud option, please be patient–your environment will update shortly.
To set up the Mimecast event source, complete these steps:
- Read the requirements and complete the prerequisite steps.
- Configure Mimecast to send data to InsightIDR.
- Configure InsightIDR to receive data from the event source.
- Test the configuration.
You can also:
Requirements
Before you start the configuration:
- Create a service account with the Administrator role and ensure that it is in the Basic Administrators group. View the instructions at: https://community.mimecast.com/s/article/email-security-cloud-gateway-managing-api-1-0-applications#Prerequisites
- Ensure that the Administrator service account has Gateway, Tracking, and Read permissions enabled.
- Ensure enhanced logging for email is enabled. View the instructions at: https://integrations.mimecast.com/documentation/endpoint-reference/logs-and-statistics/get-siem-logs/
Configure Mimecast to send data to InsightIDR
To allow InsightIDR to receive data from Mimecast, you must create an API application and configure specific settings in your Mimecast account.
- Create an API 1.0 application in Mimecast. View the instructions at: https://community.mimecast.com/s/article/email-security-cloud-gateway-managing-api-1-0-applications#Adding-an-API-Application. Note: InsightIDR does not support the API 2.0 application for Mimecast.
- Generate an access key and secret key. View the instructions at: https://community.mimecast.com/s/article/email-security-cloud-gateway-managing-api-1-0-applications#To-create-the-user-association-keys
- Ensure the Authentication Cache TTL setting in your profile is set to never expire. View the Mimecast documentation at: https://integrations.mimecast.com/documentation/api-overview/authentication-and-authorization/
Select Enable Extended Session when configuring in Mimecast
When you’re adding an API application in Mimecast, select Enable Extended Session. Rapid7 does not refresh expired access keys, so the API access keys will never expire.
Configure InsightIDR to receive data from the event source
After you create your API application in Mimecast and obtain the necessary keys, you can set up your Mimecast event source in InsightIDR.
Task 1: Select Mimecast
- From the left menu, go to Data Collection and click Setup Event Source > Add Event Source.
- Do one of the following:
- Search for Mimecast in the event sources search bar.
- In the Product Type filter, select Cloud Service.
- Select the Mimecast event source tile.
Task 2: Set up your collection method
There are two methods of collecting data from Mimecast: through a cloud connection or through a collector.
New credentials are required for cloud event sources
You cannot reuse existing on-premise credentials to create a cloud connection with this event source. You must create new credentials.
Use the Cloud Connection method
- In the Add Event Source panel, select Run On Cloud.
- Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Mimecast.
- Optionally, select the option to send unparsed data.
- Select your Account Attribution preference:
- Use short name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by short name, for example,jsmith
. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. - Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. This option is best if your environment has collisions with short names.
- Use short name attribution: The system first attempts to attribute data by email address, for example,
- Optionally, specify the Active Directory Domain for Multi-domain Environments.
- Select an attribution source.
- Click Add a New Connection.
- In the Create a Cloud Connection screen, enter a name for the new connection.
- In the Server Region field, select the region of the Mimecast Server.
- In the Application ID field, enter your Mimecast Application ID.
- In the Application Access Key field, add a new credential:
- Name your credential.
- Describe your credential.
- Select the credential type.
- Enter the Mimecast Application Access Key you obtained in Configure Mimecast to send data to InsightIDR.
- Specify the product access for this credential.
- In the Application Key field, add a new credential:
- Name your credential.
- Describe your credential.
- Select the credential type.
- Enter the Mimecast Application Key you obtained in Configure Mimecast to send data to InsightIDR.
- Specify the product access for this credential.
- In the Application Secret Key field, add a new credential:
- Name your credential.
- Describe your credential.
- Select the credential type.
- Enter the Mimecast Application Secret Key you obtained in Configure Mimecast to send data to InsightIDR.
- Specify the product access for this credential.
- Click Save Connection.
- Click Save.
Use the Collector method
- In the Add Event Source panel, select Run On Collector.
- Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Mimecast.
- Optionally choose to send unparsed logs.
- Select an attribution source.
- Select your Account Attribution preference:
- Use short name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by short name, for example,jsmith
. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. - Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example,
jsmith@myorg.example.com
. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example,John Smith
. This option is best if your environment has collisions with short names.
- Use short name attribution: The system first attempts to attribute data by email address, for example,
- Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
- Select your Mimecast credentials or optionally create a new credential. You can find the values for the new credential fields by logging in to your Mimecast environment, navigating to Services > API Applications, and selecting the application that you created.
- Application ID
- Application Key
- Access Key
- Secret Key
- Enter the Application ID.
- Enter the Application Key
- In the “Region” field, enter the region identifier for the relevant host based on the table below. For example, if your host is
eu-api.mimecast.com
then enterEU
.
Region Identifier | Host |
---|---|
EU | eu-api.mimecast.com |
DE | de-api.mimecast.com |
US | us-api.mimecast.com |
USB | usb-api.mimecast.com |
CA | ca-api.mimecast.com |
ZA | za-api.mimecast.com |
AU | au-api.mimecast.com |
USPCOM | uspcom-api.mimecast-pscom-us.com |
Offshore | jer-api.mimecast.com |
- Click Save.
Test the configuration
InsightIDR currently ingests Mimecast data sent via API, and parses only these Mimecast event types:
- Receipt - These events show the actions taken on an email, including whether the email successfully made it to the recipient’s inbox, or if the email was rejected due to an invalid address
- Targeted Threat Protection URL - These events are generated when there are malicious or phishing links in emails.
- Targeted Threat Protection Attachment - These events show the results of attachment scanning from Mimecast.
To test that event data is flowing into InsightIDR through the Cloud Connection:
- View the raw logs.
- From the Data Collection Management page, click the Event Sources tab.
- Find the event source you created and click View raw log. If the Raw Logs modal displays raw log entries, logs are successfully flowing to InsightIDR.
- Use Log Search to find the log entries. After approximately seven minutes, you can verify that log entries are appearing in Log Search.
- From the left menu, go to Log Search.
- In the Log Search filter, search for the new event source you created.
- Select the log sets and the log names under each log set. Mimecast logs flow into these log sets:
- Virus Infection
- Web Proxy
- Set the time range to Last 10 minutes and click Run.
The Results table displays all log entries that flowed into InsightIDR in the last 10 minutes. The keys and values that are displayed are helpful when you want to build a query and search your logs.
Sample logs
In Log Search, the log that is generated uses the name of your event source by default. The log appears under the log sets:
- Virus Infection
- Web Proxy
To help you visualize the event logs that this event source generates, here are some sample logs:
Sample Receipt log
json
1{"datetime": "2019-09-09T10:12:59-0400", "aCode": "l_HDhK8OM2avmWQksxFovQ", "acc": "CUSA123", "IP": "123.123.123.123", "RejType": "Virus Signature Detection", "Error": "Malware detected by AV Scan policy: [clam.[Doc.Malware.00536d-6923173-0], clam.[Doc.Malware.00536d-6923173-0], sole.[Remote_Object, Macro, Malicious_Macro]]", "RejCode": "554", "Dir": "Inbound", "MsgId": "<499184835@rapid7.com>", "Subject": "Outstanding balance requiring attention", "headerFrom": "user@rapid7.com", "Sender": "rapid7.user@rapid7.com", "Virus": "[clam.[Doc.Malware.00536d-6923173-0], clam.[Doc.Malware.00536d-6923173-0], sole.[Remote_Object, Macro, Malicious_Macro]]", "Rcpt": "r7user@rapid7", "Act": "Rej", "RejInfo": "[clam.[Doc.Malware.00536d-6923173-0], clam.[Doc.Malware.00536d-6923173-0], sole.[Remote_Object, Macro, Malicious_Macro]]", "TlsVer": "TLSv1.2", "Cphr": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"}
Sample Targeted threat protection URL protect log
json
1{"datetime": "2019-09-09T13:36:17-0400", "acc": "CUSA107A62", "reason": "malicious", "url": "http://www.malicious.com", "route": "inbound", "sourceIp": "123.123.123.123", "sender": "evildude@evil.com", "recipient": "user@rapid7.co.uk", "urlCategory": "Phishing & Fraud", "senderDomain": "gmail.com"}
Sample Targeted threat protection Attachment protect log
json
1{"datetime": "2017-05-23T21:45:21+0100", "acc": "C1A1", "fileName": "1XCOLUMN.PVC", "sha256": "8746bb4b31ab6f03eb0a3b2c62ab7497658f0f85c8e7e82f042f9af0bb876d83", "Size": "378368", "IP": "123.123.123.123", "Recipient": "auser@mimecast.com", "SenderDomain": "domain.com", "fileExt":"doc", "sha1":"a27850da9e7adfc8e1a94dabf2509fc9d65ee7e2", "Sender":"from@domain.com", "fileMime": "application/vnd.ms-office", "Route": "Inbound", "md5": "7b52770644da336a9a59141c80807f37"}
Troubleshoot common issues
If you experience issues with the Mimecast event source, try the solutions provided in this section.
If InsightIDR displays Mimecast error codes that you cannot interpret, see the Mimecast Response Codes documentation at: https://www.mimecast.com/de/developer/documentation/response-codes/
Mimecast plugin encountered non-retryable error
Two issues can cause this error message:
- The Service Account is not in the Basic Administrators group in Mimecast.
- You don’t have a multi-factor authentication (MFA) bypass for the Service Account IP ranges.
Service Account is not in the Basic Administrators group
You can receive this error message if the Service Account you’re using to login to the API is not in the Basic Administrators group in Mimecast.
To add the Service Account to the group:
- In the Mimecast console, click Administration > Account > Roles.
- Click on the Basic Administrators role name.
- Click Add User to Role.
- When a list of users populates, search for the name of the Service Account that you want to add to the Basic Administrators group.
- Select the check box next to the name of the Service Account.
- Click Add Selected Users.
MFA bypass needed for IP ranges
You can also receive this error message if you have MFA enabled for Mimecast, and you don’t have an MFA bypass for the IP ranges that the Service Account connects from.
To set up an MFA bypass:
- In the Mimecast console, click Administration > Service > Applications.
- Select the profile that applies to administrators on the account. For example, this could be “Account Administrators Authentication Profile”.
- Select the check box next to Disable 2-Step Authentication for Trusted IP Ranges.
- Enter the trusted IP ranges into the box that appears. You must enter the IP range in CIDR format. For example, the format must look like:
92.168.1.1/32
. - Click Save or Save and Exit to save your changes.
Mimecast API response contains error: 401 0004 Invalid Signature
This error is caused by entering incorrect credentials. Regenerate the API key in Mimecast and make sure you are copying and pasting it correctly.