API & Integrations - Event Push Integration

Overview

The Event Push integration allows you to automatically send events from Mimecast to external platforms in various formats. The use cases can include pushing logs into a SIEM or sending an alert for a specific type of event to trigger an event-driven action or automation to a SOAR or similar tool. Event Push also supports the use of S3 buckets as a destination, allowing the long-term storage of events or enabling other tools to read those events from S3.

Prerequisites

The following requirements must be met to use the Event Push integration:

• Access to a Mimecast Cloud Gateway environment.
• Access to edit on the Integrations Hub.
• All events must be sent over HTTPS port 443 to a destination with a publicly valid certificate. Self-signed certificates will result in the integration going into an error and paused state.

Event Push Types

HTTP Event Collector (HEC) Type

The HEC structure is a Splunk-designed, widely supported, standard meant to ingest high volumes of events. When sending events, the API call request payload structure will be:

[

    {

        "event": {

            "name": "Event 1",

            "id": 1

        }

    },

    {

        "event": {

            "name": "Event 1",

            "id": 2

        }

    }

]

When sending events, the "application/json" content type is used in the request headers.

HEC has been tested to work natively with:

• Splunk SIEM: While it is supported, the payload can exceed Splunk's maximum supported payload size. In cases where this is a concern, we recommend using the NDJSON type for Splunk SIEM.
• CrowdStrike NextGen SIEM.

Newline Delimited JSON (NDJSON)

The NDJSON structure is designed to send multiple events in a single API call, with a single event per line of the payload. When sending events, the API call request payload structure will be:

{“event”: {"name":"Event 1","id":1}}

{“event”: {"name":"Event 2","id":2}}

When sending events, the "application/x-www-form-urlencoded" content type is used in the request headers.

Webhook

The Webhook push type will send a JSON payload of a single event. When sending an event, the API call request payload structure will be:

{

    "name": "Event 1",

    "id": 1

}

When sending events, the "application/json" content type is used in the request headers.

Using this push type with large event volumes can increase the risk of encountering rate limiting by the recipient platform. 
As a preventative measure, the MTA event type is disabled when selecting the webhook event push type.

AWS S3 File

The S3 push type will upload an event as a single JSON file to a specified AWS S3 Bucket.

Using this push type with large event volumes can increase the risk of hitting AWS's file PUT rate limits. 

Event Type Structures

Events pushed to an external platform follow our public API endpoints' data structures, with an added field to explain the event type that is being sent. The field added to each event is named "mimecastEventType". The links below reference the associated API 2.0 endpoint for each event type.

The available formats are:

• Attachment Protection events
• Impersonation Protection events
• URL Protection events
• Data Leak Prevention or Content Examination events
• Audit events
• Message Release events
• Archive view events
• Message Rejection events
• Email Queue status
• MTA events (receipt, process, delivery, journal, etc.)
• Threat events
• Remediation incident event
• Account Threat Feed events
• Regional Threat Feed events

Other Configuration Information

Authentication

The Event Push integration supports three ways to authenticate with most external platforms:

1. OAuth 2.0 can be used by providing a token endpoint, client ID, client secret, and scope.
2. Static Headers can be set to use for authentication or for informational purposes.
3. While not recommended, IP-based authentication can also be used with the ranges in the Source IP section of this article.

If sending events to AWS S3, authentication is performed by providing:

• IAM Access Key
• IAM Secret Key
• AWS region

Headers

The headers section of the configuration screen allows you to specify headers that can be used for authentication purposes, or informational fields to aid in your parsing of events.

When using headers for authentication, an option exists to mark the value as Secret, meaning the value will be treated as a credential. When marking values as Secret, they will not be shown when editing the configuration.

If replacing one header marked as Secret, OAuth 2.0 information, or AWS credentials all these protected fields will need to be provided as well, regardless if they were modified or not. This is done to ensure all credentials are stored securely together.

When specifying headers, some values may be overridden at the time an API call is made. This includes:

• Content-Type
• Content-Length

Fetch from Duration and Token Reset

When initially creating an Event Push configuration, the Fetch from Duration will be used to determine how far in the past events should be gathered and sent over. Going forward, only new events will be sent.
If you need to replay events due to a technical issue or when troubleshooting the recipient platform, you can use the Reset Token button at the top of the configuration screen to have events resent. Tokens are timestamps per event type to ensure that an event is not sent twice, and that events are not missed.

When resetting tokens, the current Fetch from Duration value will be used to determine how far back in the past events should be replayed.

Note on MTA events: These events are only available going back 24 hours in the past, regardless of the Fetch from Duration configuration.

Source IPs

The recipient platform must accept connections from the IP addresses listed below:

IP Address	CIDR
52.44.135.122	52.44.135.122/32
34.239.14.59	34.239.14.59/32
52.3.199.226	52.3.199.226/32
52.32.254.214	52.32.254.214/32
44.240.129.190	44.240.129.190/32
44.226.233.235	44.226.233.235/32
13.245.119.109	13.245.119.109/32
13.246.73.66	13.246.73.66/32
13.244.196.243	13.244.196.243/32
13.211.192.162	13.211.192.162/32
3.24.186.125	3.24.186.125/32
3.104.144.120	3.104.144.120/32
15.222.48.122	15.222.48.122/32
3.98.245.2	3.98.245.2/32
15.222.74.84	15.222.74.84/32
18.193.26.15	18.193.26.15/32
3.64.152.67	3.64.152.67/32
3.73.217.174	3.73.217.174/32
185.58.87.1	185.58.87.1/32
195.130.217.126	195.130.217.126/32
193.7.207.6	193.7.207.6/32
193.7.206.6	193.7.206.6/32

If needed, you can restrict API traffic to the destination to only these IP addresses.

Rate Limiting and High-Volume Event Types

When selecting a push type and events to be sent, be careful to ensure that the recipient platform can handle the expected volume. For example, selecting Webhook as the push type and selecting all event types, it is likely that you can encounter rate limiting. When sending many events, we recommend using HEC or NDJSON which are designed to send multiple events per API call. To judge your expected number of events, look at the associated page in the Administration Console for that event type.

When encountering rate limiting, the Event Push configuration will attempt to retry sending failed events. However, if rate limits are regularly hit, you risk a delay in events being sent. In extended rate limiting cases, this can cause a gap in events at the recipient platform.

Setting up Event Push

Configuring for HEC, NDJSON, or Webhook

1. Go to Administration Console | Integrations | Integration Hub | Event Push | Select Configure New.
2. Below Details, set the following fields:

•  
  • Application Name: This is the name to uniquely identify the specific Event Push configuration. Once the integration has been created, the name cannot be modified.
  • Description: This is a short explanation of the specific Event Push configuration.

3. Below Activate, provide the destination information where events should be sent:

•  
  • Select Event Push Type: This allows you to specify the format in which events will be sent. For more information about the different types, see the Event Push Types section of this article.
  • Provide the event collector endpoint, where Mimecast will make an HTTP POST call with events.
  • If using OAuth 2.0 for authentication, configure the following fields:
    • OAuth 2.0 Provider token endpoint: The URL that Mimecast should use to obtain an authorization token.
    • OAuth 2.0 Client ID: The client ID provided by the recipient platform.
    • OAuth 2.0 Client Secret: The client secret provided by the recipient platform.
    • OAuth 2.0 Scope: If using scopes, the scope provided by the recipient platform. This filed is optional.
  • Specify the Fetch from Duration. For more information about Fetch from Duration, see the Fetch from Duration and Token Reset section of this article.

4. If you need to specify specific request Headers, add them under the Request Headers section:

•  
  • Key: The request header name.
  • Value: The request header value.
  • Mark Header as Secret: If the header contains sensitive information, like an API key, check the box to ensure the field is stored as a credential.

If a field is marked as Secret, then the value of the field will not be returned when editing the integration in the future. However, you can override its value in future.

5. Below Send from Mimecast, select the events that you want to be sent to the recipient platform. For more information on the event types, see the Event Type Structures section of this article.
6. Below Notification Configuration, add up to 5 recipients to receive an email if the Event Push configuration encounters a permanent error.

Configuring for AWS S3 Files

Follow the steps for HEC, NDJSON, and Webhook apart from providing the following fields in place of an event collector endpoint and OAuth 2.0 information:

1. AWS Access Key obtained from AWS IAM.
2. AWS Secret Key obtained from AWS IAM.
3. AWS Bucket name of the destination bucket that has already been created in AWS. Ensure that the Access Key and Secret Key mentioned above have ListBucket and PutObject permissions for this bucket.
4. AWS Region of the existing S3 bucket.

Troubleshooting and Error Status

In the event an Event Push configuration has an issue, the most recent run attempt information is available under the Status and Status Details tabs, which you can find under the Administration Console | Integrations | Integrations Hub | Event Push | View.

If an Event Push configuration encounters a temporary error, it will attempt to recover in a few minutes, and event tokens will not advance until the recipient platform has successfully acknowledged receipt of an event with a 200-based API response.

When encountering a permanent error, such as failed authentication, the integration will go into an error and paused state until the configuration is edited and saved. If this happens, the contacts specified under the Notification Configuration section of the configuration screen will receive an email alert.