API & Integrations - Mimecast For Splunk Administration

Mimecast for Splunk allows a Splunk Enterprise administrator to ingest events derived from data generated by the Mimecast platform, i.e., audit, email, Targeted Threat Protection, and a service health overview using pre-built dashboards. Data is mapped to the Common Information Model, where relevant, to allow users to correlate Mimecast events with other data sources.

Mimecast for Splunk can be used for many reasons. For example, to ingest:

• Secure Email Gateway events into Splunk to feed the Splunk Enterprise Security or User Behavior Analytics products.
• Mimecast events to create custom reports on email traffic, security, and usage.

Support & Resources

Mimecast for Splunk has been tested on Splunk Enterprise version 8.0 hosted on Windows, Linux, and macOS X. Other host operating systems and Splunk versions later than 8.0 should also work but may not have been explicitly tested. The supported versions of Splunk Enterprise are listed along with the app on Splunkbase.

You can ask questions specific to Mimecast for Splunk, by using one of the following methods:

• Mimecast for Splunk - Release Notes
• Mimecaster Community Forums
• Raising a Mimecast Support Case

System Requirements

The following System Requirements must be met:

• The app requires no software other than a working Splunk installation.
• This integration is designed to run on both Splunk Enterprise and Splunk Cloud.
• When running on Splunk Enterprise, ensure your environment meets Splunk's system requirements. For full details, see the Splunk Enterprise System Requirements page in the Splunk Enterprise documentation.
• An index named 'mimecast' needs to be created. See the Create Custom Indexes page in the Splunk Enterprise documentation for full details.

Usage Considerations

Version 3.x cannot be upgraded to 4.x.

• Data ingested by previous versions will remain in place and will not be migrated to a new index.
• When upgrading from any version below v5.0.0 to any version above v5, new API 2.0 keys will need to be generated, as the API gateway used in the new version has changed.
• When upgrading from any version below v5.0.0 to any version above v5, there may be a small amount of duplicate data re-ingested due to the collection mechanism being updated and invalidating the previously stored token.
• Some MTA logs will show a new structure, as the data has been optimized in our API 2.0 Gateway.
• The Admin IP Ranges specified in the Mimecast Administration Console are respected when retrieving SIEM logs. Admin IP Ranges are entered in your Account Settings 'User Access and Permissions' section. See the Mimecast Account Settings page for further details.
• Advanced Account Administration customers must use a dedicated administrative user for each Mail Processing account. To collect additional data from the Master account and any Grouping accounts configured in the Advanced Account Administration structure:
  • Federated Administration must be enabled throughout the structure as described in Federated Roles and Account Settings.
• The access and Secret key process should be repeated for an administrator from the Master account using the Federated Administration domain.
• The Mimecast for Splunk app requires an authentication token for the dedicated Mimecast administrative user to be entered during the app's configuration.
  • A dedicated user and Authentication Profile that defines a long-lived authentication token should be created to prevent the authentication token from expiring.
  • By default, authentication tokens expire. The expiration of the authentication token will prevent the app from collecting data and events.
  • To obtain an authentication token for the dedicated Administrative user, see Managing API Applications. Specify the application name as 'Mimecast for Splunk,' and at the end of this process, you will obtain the following pieces of information:
    • Application Id.
    • Application Key.
    • Access key.
    • Secret Key.

Mimecast for Splunk versions 4.2.0 and earlier

Installation & Configuration

Configuring Your Network

The Mimecast for Splunk app uses the API to collect data and events. Ensure that the server hosting the Mimecast for Splunk app can communicate with the URL for the region where your Mimecast account is hosted.

Region	URLs
Europe (excluding Germany)	https://eu-api.mimecast.com
Germany	https://de-api.mimecast.com
United States of America	https://us-api.mimecast.com
United States of America (B Grid)	https://usb-api.mimecast.com
Canada	https://ca-api.mimecast.com
South Africa	https://za-api.mimecast.com
Australia	https://au-api.mimecast.com
Offshore	https://je-api.mimecast.com

Configuring Mimecast Role Permissions

The Mimecast for Splunk app requires access to various endpoints. See the table below for the endpoints used and the Mimecast administrator permissions associated with the endpoint. For convenience, all permissions are included in the Basic Administrator role.

Endpoint	Permission Required
/api/email/get-email-queues	Dashboard | Read
/api/directory/get-connections	Services | Directory Sync | Read
/api/journaling/get-service	Services | Journaling | Read
/api/audit/get-audit-events	Account | Logs | Read
/api/audit/get-siem-logs	Gateway | Tracking | Read
/api/ttp/url/get-logs	Monitoring | URL Protection | Read
/api/ttp/attachment/get-logs	Monitoring | Attachment Protection | Read
/api/ttp/impersonation/get-logs	Monitoring | Impersonation Protection | Read
/api/dlp/get-logs	Monitoring | Data Leak Prevention | Read
/api/ttp/threat-intel/get-feed	Gateway | Tracking | Read

Configuration via the Mimecast Administration Console

Enabling Enhanced Logging

You can enable Enhanced Logging, by using the following steps:

1. Log in to the Mimecast Administration Console.
2. Navigate to Account | Account Settings.
3. Expand the Enhanced Logging section.
4. Select the Log Types you want to enable:

• • Inbound: logs for messages from external senders to internal recipients.
  • Outbound: logs for messages from internal senders to external recipients.
  • Internal: logs for messages between internal domains.

4. Click on the Save button.

Once settings are saved, the Mimecast MTA starts logging data for your account. Logs are available to Mimecast for Splunk 30 minutes later.

Creating a Dedicated User

1. Create a dedicated User. See the "Creating a User" section of the Creating / Editing Mimecast Users. Note the password set; you'll need this to obtain an Authentication Token.
2. Add the user to the Basic Administrator Role. See the "Adding Users to a Role" section of Managing Administrator Roles.
3. Create a Profile Group. See the "Creating a Group" section of Managing Groups.
4. Add the User to the Profile Group.
5. Select the Add Email Addresses button.
6. Add the dedicated user created in Step 1.

Creating Authentication Profile & Application Settings

1. Create an Authentication Profile. See Configuring an Authentication Profile.

• • Set the Authentication TTL option to "Never Expires" to ensure the Authentication Token won't expire.

2. Create an Application Setting. See Configuring Application Settings.

• • Select the Profile Group created above in the Group option.
  • Select the Authentication Profile created above by clicking on the Lookup button.

Mimecast for Splunk versions 5.0.0 and later

As of version 5.0.0, Mimecast for Splunk has been updated to use the 2.0 version of Mimecast's API, which uses the following domains:

• https://api.services.mimecast.com
• https://s3.amazonaws.com

In order to download logs successfully, please ensure that your Splunk instance is able to access both.

Identify Administration Role (Cloud Gateway Only)

Create a custom Administrator Role with the permissions noted below, or select an existing role with these permissions applied.

Endpoint	Permission Required
/api/email/get-email-queues	Dashboard | Read
/api/directory/get-connections	Services | Directory Sync | Read
/api/journaling/get-service	Services | Journaling | Read
/api/audit/get-audit-events	Account | Logs | Read
/siem/v1/batch/events/cg	Security Events and Data Retrieval | Threat and Security Events (SIEM)| Read permission.
/api/ttp/url/get-logs	Monitoring | URL Protection | Read
/api/ttp/attachment/get-logs	Monitoring | Attachment Protection | Read
/api/ttp/impersonation/get-logs	Monitoring | Impersonation Protection | Read
/api/dlp/get-logs	Monitoring | Data Leak Prevention | Read
/api/ttp/threat-intel/get-feed	Gateway | Tracking | Read
/api/awareness-training/company/get-safe-score-details	Awareness Training | Dashboard | Read
/api/awareness-training/company/get-performance-details	Awareness Training | Dashboard | Read
/api/awareness-training/company/get-watchlist-details	Awareness Training | Dashboard | Read
/api/awareness-training/phishing/campaign/get-user-data	Awareness Training | Dashboard | Read

Generate API 2.0 Keys

For Email Security Cloud Gateway

You can generate API 2.0 keys, by using the following steps:

1. Log in to the Mimecast Administration Console.
2. Navigate to Integrations| API and Platform Integrations.
3. Select Generate Keys under Your API 2.0 Applications.
4. Review and accept the legal terms
5. Follow the steps to create a new API 2.0 application, with the following values:

• • Application Name: “Splunk”.
  • Category: “SIEM Integration”.
  • Products:
    • Threats, Security Events and Data for CG.
    • Threat Management.
    • Audit Events.
    • Security Events.
    • Awareness Training.
    • Email Security Cloud Gateway.
  • Application Role: Select the role created or identified in the “Identify Administration Role” step.
  • Description: Anything needed to help you identify this API application in the future.
  • Technical Contact: The name and email address of the person(s) responsible for this integration (used by Mimecast if we identify an issue with this application, can be a distribution list).

6. Once you generate keys, store them securely, as they will not be provided again.

For Email Security Cloud Integrated

You can generate API 2.0 keys, by using the following steps:

1. Log in to the Cloud Integrated platform.
2. Navigate to Integrations | API 2.0 Applications.
3. Select the New Application button.
4. Provide the following required values (other fields are optional):

• • Application Name: Splunk.
  • Integration Partner: Splunk.
  • Products:
    • Cloud Integrated.
    • Threats, Security Events, and Data for CI.
  • Roles: Full Admin.
  • Contact: The name and email address of the person(s) responsible for this integration (used by Mimecast if we identify an issue with this application, can be a distribution list).

5. Click Save & Generate Keys, to retrieve your API keys.
6. Store these keys securely, as they will not be provided again.

Installing Mimecast for Splunk

You can install Mimecast for Splunk, by using the following steps:

1. Log in to the Splunk Web Console.
2. Select Manage Apps from the top left-hand menu.
3. Click on the Browse More Apps button.
4. Search for Mimecast for Splunk.
5. Follow the wizard steps to install the app.

Alternatively, the add-on can be downloaded from Splunkbase and installed via CLI or the Splunk Web Console.

Configuring Mimecast for Splunk

You can configure authentication tokens for the Mimecast for Splunk app, by using the following steps:

1. Log in to the Splunk Web Console.
2. Select the Mimecast for Splunk app.
3. Click on the Configuration menu item.

4. Click on the Account tab.

5. Click on the Add button.

6. Enter a unique Account Name.
7. Paste in the following obtained values:

• • A descriptive name for the account.
  • The Mimecast Account Code for this account.
  • If using any version prior to v5.0.0:
    • Global Base URL.
    • Application Key.
    • Access Key.
    • Secret Key.
  • If using version 5.0.0 or later:
    • Client ID.
    • Client Secret.
    • The Global Base URL should be https://api.services.mimecast.com regardless of your hosted region.

8. Click on the Add button.
9. Click on the Inputs menu.

 ​​

10. For upgrades from earlier versions of v4.x:

• • Edit each input.
  • Select the Account (created in step 8 using the Credentials dropdown).

11. Review the correct application ID, Account Code, and Base URL values, and click Update.
12. For new installations, configure all Data Inputs to collect all available log data from Mimecast:

• • Click on the Create New Input button.
  • Select an Input Type.
  • Add a Name to identify the input.
  • Set the Interval to 300.
  • Set Index to mimecast.
  • Set Credentials to the Account created in Steps 6-8
  • Enter the obtained Application Id value.
  • Enter the Account Code for the Mimecast account. (This can be found on the dashboard of the Mimecast Administration Console.)
  • Set the Base URL to the URL for your account's region (e.g., https://us-api.mimecast.com for an account hosted in the US region). See the "Configuring Your Network" section in this article.
  • Click on the Add button to save the new input.

Advanced Account Administration Customers can use this process to configure a data input for each mail processing account, using an administrator from the mail processing account itself. To collect events from master and/or grouping accounts, contact our Support Team. They will be able to guide you through enabling federated administration in your Mimecast hierarchy and configuring a data input for these account types.

Using Mimecast for Splunk

The Mimecast for Splunk app is comprises several dashboards, displaying the available data. See the table below for a description of the dashboards and the expected update frequencies.

Dashboard	Description	Data Update Frequency	Available Data	Data Retention
Email Activity | Email Activity Summary	Displays messages received over time by the route and sparklines for Rejections, Bounces, and Held Messages.	Every 15 minutes	From when you enabled Enhanced Logging.	7 days
Email Activity | Email Delivery	Displays visualizations for messages delivered by the Mimecast MTA.	Every 15 minutes	From when you enabled Enhanced Logging.	7 days
Email Activity | Email Receipt	Displays visualizations for messages received by the Mimecast MTA.	Every 15 minutes	From when you enabled Enhanced Logging.	7 days
Email Activity | TLS	Displays visualizations detailing the secure delivery and receipt of messages processed by the Mimecast MTA.	Every 15 minutes	From when you enabled Enhanced Logging.	7 days
Email Activity | AV / AS	Displays visualizations for messages detected as Spam or carrying a virus.	Every 15minutes	From when you enabled Enhanced Logging.	7 days
Targeted Threat Protection | Attachment Protect	Displays visualizations for data logged when the Mimecast sandbox identifies a potentially malicious attachment.	Real-time	From when you enabled Enhanced Logging.	7 days
Targeted Threat Protection | Impersonation Protect	Displays visualizations for Targeted Threat Protection Impersonation Protect message characteristics detected in a message.	Real-time	From when you enabled Enhanced Logging.	7 days
Targeted Threat Protection | URL- Protect	Displays visualizations for data logged when a user clicks on a potentially malicious link in an email.	Real-time	From when you enabled Enhanced Logging.	7 days
Audit and Access | Audit Log	Displays a feed of administrator and authentication activity.	Real-time	From ten minutes before you configured the Splunk Data Input.	30 days
Audit and Access | Access Attempts	Displays visualizations for access attempts made to the Mimecast account.	Real-time	From ten minutes before you configured the Splunk Data Input.	30 days
Data Leak Prevention	Displays visualizations for data logged when a DLP event has been logged.	Real-time	From when you enabled Enhanced Logging.	7 days
Threat Intel Feed | Targeted	Displays visualizations for events from customer Threat Intelligence feed.	Every 30 minutes	From when you enabled Enhanced Logging and the Threat Intelligence package has been enabled.	30 days
Threat Intel Feed | Regional	Displays visualizations for events from the Mimecast Regional Threat Intelligence feed.	Every 30 minutes	From when you enabled Enhanced Logging and the Threat Intelligence package has been enabled.	30 days
Service Health	A dashboard displaying inbound and outbound message queue totals and the status of Directory and Journal integrations if configured.	Real-time	One hour before, you configured the Splunk Data Input.	n/a
Awareness Training	A dashboard displaying information about Awareness Training, including watchlist and phishing campaign statistics	Every 12 hours	From the point of adding the Awareness Training input going forward	n/a
Troubleshoot	Mimecast-specific events from the splunkd.log.file.	Real-time	n/a	n/a

Troubleshooting

Interactions between the Mimecast for Splunk app and Splunk Enterprise are logged within the splunkd.log file. The Troubleshoot dashboard is the first place to check if you're experiencing any problems or errors. From the Troubleshoot page, you can view and export Mimecast for Splunk-related events contained within the splunkd.log file and the distinct logs generated by each active input type to provide an overview of the interactions between the Mimecast for Splunk app, Splunk Enterprise, and the Mimecast API. To achieve this, you must enable the Include platform logs option on the Troubleshoot page. Additionally, the Log level can be set for Mimecast for Splunk, by clicking on the Configuration menu and the Logging tab.
The below table outlines the input activity log for each input type.

Input Type	Activity Log
Mimecast SIEM	ta_mimecast_for_splunk_mimecast_siem.log
Mimecast Audit	ta_mimecast_for_splunk_mimecast_audit.log
Mimecast TTP URL Protect	ta_mimecast_for_splunk_mimecast_ttp_url.log
Mimecast TTP Attachment Protect	ta_mimecast_for_splunk_mimecast_ttp_attachment_protect.log
Mimecast TTP Impersonation Protect	ta_mimecast_for_splunk_mimecast_ttp_impersonation_protect.log
Mimecast TTP Data Leak Prevention	ta_mimecast_for_splunk_mimecast_data_leak_prevention.log
Mimecast Threat Intel Feed Regional	ta_mimecast_for_splunk_mimecast_threat_intel_feed_regional.log
Mimecast Threat Intel Feed Targeted	ta_mimecast_for_splunk_mimecast_threat_intel_feed_targeted.log
Mimecast Service Health	ta_mimecast_for_splunk_mimecast_service_health.log

Dashboard Not Updating

If your dashboards aren't updating correctly:

• Check you have configured the appropriate input.
• Check that the date filters are set to when you expect to see the data. Check the log file to confirm events are being added to Splunk.
• Check the log file for the input on the Troubleshoot page to confirm whether events are being collected or written to Splunk Enterprise.

Request Returned with Status Code 418 ()

If you see "Request returned with status code 418 ()" in the apps logs, the Access and Secret keys used for the account assigned to an Input have expired. Ensure you have followed the configuration steps to create a user with an Authentication Token that doesn't expire.