...

Mimecast is a cloud-based, anti-spam, and archive filtering service for securing email accounts and communications for businesses. This collector

Mimecast protects an enterprise’s email infrastructure from viruses, malware, phishing, and the rise of deep-fake attacks. It does this by deploying a layered cyber resilience solution that prevents email-borne infections and reduces data loss by archiving emails. This cloud-based cybersecurity solution also makes it possible to automate the recovery of archived and affected emails for continuous use. It

The Mimecast approach to protecting email structures means it can predict and or anticipate attacks and deal with losses in order to handle real-time threats. It also deals with data loss from ransomware attacks using data archiving. The Devo Mimecast Collector uses the Mimecast API to extract all the relevant information and send it as events to Devo., which eliminates the need to meet ransom demands, as well as struggle with downtime. Mimecast can also be deployed to tackle those annoyingly ‘spammy’ messages that keep cluttering inboxes.

For those who already use any of the popular email management brands such as Microsoft Office 365, Outlook, or Google’s Gsuite, Mimecast’s cloud-based nature makes it compatible with them. It can be deployed to tackle spam, ransomware, or other cybersecurity challenges.

The Devo Mimecast Collector uses the Mimecast API to extract all the relevant information an send it as events to Devo.

Data sources

...

For more information on how the events are parsed, visit our page.

Vendor setup

There are some requirements to configure the Mimecast collector:

• Accessing your API applications.

• Creating user API keys. Refer to the Mimecast official documentation for more information.

Authentication

The Mimecast Collector API 2.0 needs two keys that the API uses:

• Client ID (client_id).

• Client secret (client_secret)

Run the collector

Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).

...

This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.

Structure

The following directory structure should be created for being used when running the collector:

<any_directory>
└── devo-collectors/
    └── <product_name>/
        ├── certs/
        │   ├── chain.crt
        │   ├── <your_domain>.key
        │   └── <your_domain>.crt
        ├── state/
        └── config/ 
            └── config.yaml 

Devo credentials

In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/. Learn more about security credentials in Devo here.

...

Editing the config.yaml file

...

Expand
title Version 2 of the API
Overview Mimecast API 2.0 uses OAuth 2.0 to authenticate with the new Mimecast API Gateway using a dedicated Application (created and configured by the customer). To register and configure an Application: For Email Security Cloud Gateway customers: From Mimecast Administration Console navigate to: Administration | Services | API and Platform Integrations | Available Integrations, locate the Mimecast API 2.0 tile and select Generate Keys. Please see the following KB article for further information on Managing API 2.0 Applications: https://community.mimecast.com/s/article/api-integrations-managing-mimecast-api-2-0-applications To successfully create and manage Mimecast API 2.0 applications, the Security Permissions setting for a logged in administrators' role, must be able to Manage Application Roles. Please see the following KB article for further information on managing roles: Customer Community For Email Security Cloud Integrated customers Navigate to Configuration | API 2.0 Applications Select New Application Authentication After this process, the two keys that the Mimecast Collector API 2.0 needs are created, the keys are: Client ID(client_id). Client Secret ( client_secret)

Expand
title Version 1 of the API
Overview Following steps are necessary for setup at the Mimecast side. Log in from https://www.mimecast.com/tech-connect/documentation/api-overview/api-concepts/ Accessing your API applications: Log on to the Administration Console. Click on the Administration toolbar button. Select the Services | API and Platform Integrations menu item. With your API applications displayed you can: Add an application Edit an application Delete an application Further information may be found here: https://community.mimecast.com/s/article/Managing-API-Applications-505230018 Creating user API keys: Scroll to middle of: https://www.mimecast.com/tech-connect/documentation/api-overview/api-concepts/ for detailed instructions. Authentication The Mimecast Collector needs four keys that the API uses, the four keys are: API Application ID(app_id). API Key(app_key). Access Key(access_key). Secret Key(secret_key). Credentials API Application ID & API Key Steps 1 Click Add API Application. 2 Fill in the Details section as outlined below: 3 Click Next. 4 Fill in the Settings section as outlined below: 5 Click Next. 6 Review the Summary page to ensure all details are correct. To fix any errors: Click on the Edit link next to the Details or Settings to return to the relevant page. Make your changes and click on the Next button to proceed to the Summary page again. 7 Click on the Add button. The application's details display in a slide-in panel. 8 Copy and paste the Application ID and Application Key to a safe place for use later in the process. 9 Wait 30 minutes and click on the application in your list. A panel opens. While waiting for the application to become live, you may go through the Prerequisites section of Creating User Association Keys.  10 Click on the X to return to the list of API applications. More details https://community.mimecast.com/s/article/Managing-API-Applications-505230018#Creating-an-API-user-Authentication-Profile . Access Key & Secret Key 1 Click on API Application from the application list. 2 Click Create Keys. A "Create Keys" wizard is displayed with the Account tab selected. 3 Enter the Email Address of your service account 4 Click Next.  5 Complete the Authentication dialog: 6 Click Next. The Verification tab is displayed. 7 If you are using a 2-step authentication mechanism, a verification code is sent to you by SMS or email.  8 Enter the Code within 15 minutes. 9 Click Next. The Keys tab is displayed with the generated keys hidden by default. Click on the  icon to display a key. Click on the   icon to copy the key to your clipboard. 10 Click on the Finish button to exit the wizard and return to the application list. More details https://community.mimecast.com/s/article/Managing-API-Applications-505230018#Creating-an-API-user-Authentication-Profile .

Permissions (both API 1 and 2)

Each API call has a prerequisite section that tells you what permissions are needed for the call. Usually, a Basic Administrator role will suffice, which should allow you to use the same API keys generated for multiple API calls under the application.  

If you want to create a custom administrative role for this API service account user: 

1. Navigate to Administration | Account | Roles. 

2. Click New Role.

3. Enter a Role Name and Description.

4. In the Application Permissions section, select the boxes for each required role to be used by the service user account. 

5. Click Save and Exit. 

6. Locate the newly created role and click on the role name. 

7. Click Add User to Role. 

8. Click on the email address of the API service user account. 

If you want to add the service account user to an existing role:

1. Navigate to Administration | Account | Roles. 

2. Click on the administrator role the user will be added to. 

3. Click Add User to Role.

4. Click on the email address of the API service user account.

More details https://community.mimecast.com/s/article/Managing-API-Applications-505230018#Creating-an-API-user-Authentication-Profile .

Run the collector

Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).

{
  "global_overrides": {
    "debug": false
  },
  "inputs": {
    "mimecast_input": {
      "id": "<short_unique_identifier>",
      "enabled": true,
      "base_url": "your_base_url",
      "auth_url": "your_auth_url",
      "pageSize": "<page_size_value>",
      "autoconfig": {
        "refresh_interval_in_seconds": "refresh_interval_value",
        "creation_timeout_in_second": "creation_timeout_value"
      },
      "credentials": {
        "client_id": "your_client_id",
        "client_secret": "your_client_secret",
        "app_id": "your_app_id",
        "app_key": "your_app_key",
        "access_key": "your_access_key",
        "secret_key": "your_secret_key"
      },
      "services": {
        "service_mimecast_client_api": {
          "last_configuration_timestamp": "last_configuration_timestamp_value",
          "endpoints": [
            {
              "endpoints_1": {
                "name": "audit",
                "initial_lookback_period": "1d"
              }
            },
            {
              "endpoints_2": {
                "name": "attachments",
                "initial_lookback_period": "1d"
              }
            },
            {
              "endpoints_3": {
                "name": "impersonation",
                "initial_lookback_period": "1d"
              }
            },
            {
              "endpoints_4": {
                "name": "url",
                "initial_lookback_period": "1d"
              }
            },
            {
              "endpoints_5": {
                "name": "search",
                "initial_lookback_period": "1d"
          - endpoints_1:   }
           name: audit},
            {
 initial_lookback_period: 1d           - "endpoints_2:6": {
                "name": "view",
 attachments               "initial_lookback_period": "1d"
          - endpoints_3:   }
           name: impersonation},
            {
 initial_lookback_period: 1d           - "endpoints_4:7": {
                "name": "threatfeed",
url                "initial_lookback_period": "1d"
          - endpoints_5:   }
           name: search},
            {
 initial_lookback_period: 1d           - "endpoints_68": {
                "name": "messageholdlist",
 view               "initial_lookback_period": "1d"
          - endpoints_7:   }
           name: threatfeed},
            {
 initial_lookback_period: 1d           - "endpoints_8:9": {
                "name": "messageholdsummary",
 messageholdlist               "initial_lookback_period": "1d"
          - endpoints_9:   }
           name: messageholdsummary},
            {
 initial_lookback_period: 1d           - "endpoints_10": {
                "name": "dashboard",
                "initial_lookback_period": "1d"
   mimecast_siem_input:     id: 2     enabled:}
false     requests_per_second: 5     base_url: your_base_url }
    auth_url: your_auth_url     pageSize:]
10     autoconfig:   }
   refresh_interval_in_seconds: 60  }
   # Runs},
the setup every x seconds (default 600) "mimecast_siem_input": {
       creation_timeout_in_second: 60"id": "<short_unique_identifier>",
      "enabled": true,
  # Set up the setup timeout (default 60) "requests_per_second": "requests_per_second_value",
      credentials"base_url": "your_base_url",
       client_id"auth_url": <client"your_idauth_value>url",
        client_secret"pageSize": <client"page_secret_value>
    services:size_value",
      "autoconfig": {
        service_mimecast_siem_client_api:"refresh_interval_in_seconds": "refresh_interval_value",
        last_configuration_timestamp: 2021-12-02T13:10:00Z # change this if you want to get your state changed!
        endpoints:
"creation_timeout_in_second": "creation_timeout_value"
      },
      "credentials": {
         siem"client_id": "your_client_id",
           initial_lookback_period: 1d

"client_secret": "your_client_secret",
        "app_id": "your_app_id",
        "app_key": "your_app_key",
        "access_key": "your_access_key",
        "secret_key": "your_secret_key"
      },
      "services": {
        "service_mimecast_siem_client_api": {
          "last_configuration_timestamp": "last_configuration_timestamp_value",
          "endpoints": {
            "siem": {
              

"initial_lookback_period": "0d",
              

"page_

token": 

Credentials to use the API.

endpoints

list

Mandatory

Minimum length: 1

Posible values:

"<page_token>"
        

   }
 

}
    

 }
   

  }
  

}

An array with at least one endpoint, the collector will pull from the selected endpoints.

last_configuration_timestamp

str

Mandatory

Date following the next format:

yyyy-mm-ddThh:mm:ss.000Z

Change this value to a date after the initial configuration to reset the state of the collector.

initial_lookback_period

str

Mandatory

Number of days, Example:

• 1d

This value will be subtracted from the current date to execute all queries in that range if no state is detected (Initial execution for example).

 This value only has an effect for mimecast_input, mimecast_siem_input always pull from the last 7 days.

Download the Docker image

The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:

Use the following command to add the Docker image to the system:

gunzip -c <image_file>-<version>.tgz | docker load

Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace <image_file> and <version> with a proper value.

The Docker image can be deployed on the following services:

Docker

Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/

docker run \
--name <YOUR_COLLECTOR_NAME>\
--volume $PWD/certs:/devo-collector/certs \
--volume $PWD/config:/devo-collector/config \
--volume $PWD/state:/devo-collector/state \
--env CONFIG_FILE=<YOUR-CONFIG-FILE>.yaml \
--rm -it <YOUR_DEVO_IMAGE_NAME>:<version>

Docker Compose

The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.

version: '3'
services:
  <YOUR_COLLECTOR_NAME>:
    image: <YOUR_DEVO_IMAGE_NAME>:${IMAGE_VERSION:-latest}
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-<YOUR-CONFIG-FILE>.yaml}

To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:

IMAGE_VERSION=<version> docker-compose up -d

We use a piece of software called Collector Server to host and manage all our available collectors.

To enable the collector for a customer:

1. In the Collector Server GUI, access to the domain in which you want this instance to be created in, click on Add Collector and search for “Mimecast Collector - Integrations Factory”, then click on the result.

2. In the Version field, select the latest value.

3. In the Collector Name field, set the value you prefer (this name must be unique inside the same Collector Server domain).

4. In the Parameters section, establish the Collector Parameters as follows below:

Editing the JSON configuration

{
"mimecast_input": {
      "id": "<short_unique_identifier>}
}

Please replace the placeholders with real world values following the description table below:

"credentials": {
        "client_id": "your_client_id",
        "client_secret": "your_client_secret"
},

"credentials": {
  "app_id": "your_app_id",
  "app_key": "your_app_key",
  "access_key": "your_access_key",
  "secret_key": "your_secret_key"
}

[
          {
            "endpoints_1": {
              "name": "audit",
              "initial_lookback_period": "1d"
            }
          },
          {
            "endpoints_2": {
              "name": "attachments",
              "initial_lookback_period": "1d"
            }
          },
          {
            "endpoints_3": {
              "name": "impersonation",
              "initial_lookback_period": "1d"
            }
          },
          {
            "endpoints_4": {
              "name": "url",
      

       "

initial_lookback_

period": "

1d"
            }
          },
       

  {
    

       "

endpoints_5": {
     

         "

name": "

search",
              "

initial_

lookback_

period": "

1d"
      

      }

},
        

 {
     

       "

endpoints_6": {
              "name": "

view",
              "

initial_

lookback_

period": "

1d"
            }
     

    },
        

  {
            "endpoints_

7": {

"name": "

threatfeed",

              "initial_lookback_period": "1d"

}

          },

          {

"endpoints_

8": {

              "name": "

messageholdlist",

              "initial_lookback_period": "1d"

            }

},

          {

            "endpoints_

9": {

              "name": "

messageholdsummary",

"initial_lookback_period": "1d"

            }

          },

{

            "endpoints_

10": {

"name": "

dashboard",

              "initial_lookback_period": "1d"

}

          }

]

We recommend to leave parameters not in the list with their default values.

Keep in mind that the Mimecast collector has two different inputs:

• mimecast_input

• mimecast_siem_input

The collector can use both inputs or just one. Each input uses different endpoints and feeds different tables in Devo. Make sure to check the credentials given to determine the inputs and endpoints to use.

This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.

Structure

The following directory structure should be created for being used when running the collector:

<any_directory>
└── devo-collectors/
    └── <product_name>/
        ├── certs/
     }   │   ├── chain.crt
     },   │          {
├── <your_domain>.key
        │   └──  "endpoints_8": {<your_domain>.crt
        ├── state/
       "name": "messageholdlist",
 └── config/ 
            └──  "initial_lookback_period": "1d"
              }
            },
            {
              "endpoints_9": {
                "name": "messageholdsummary",config.yaml 

Devo credentials

In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/. Learn more about security credentials in Devo here.

Image Added

Editing the config.yaml file

globals:
  debug: false
  id: not_used
  name: mimecast_collector
  persistence:
    type: filesystem
    config:
      directory_name: state
  queue_max_size_in_messages: 1000
     "initial_lookback_period": "1d"
    queue_wrap_max_size_in_messages: 100
outputs:
#  devo_1:
#    type: devo_platform
#    }config:
#      address: collector-us.devo.io
#    },  port: 443
#      type: SSL
# {     chain:  chain.crt
#      cert: "endpoints_10": {<devo_domain>.crt
#      key: <devo_domain>.key
inputs:
  mimecast_input:
     "name": "dashboard",id: 1
    enabled: true
    requests_per_second: 5
     "initial_lookback_period": "1d"base_url: your_base_url
    auth_url: your_auth_url
    pageSize: 1000
    }autoconfig:
      refresh_interval_in_seconds: 60     } # Runs the setup every x seconds (default 600)
 ]     creation_timeout_in_second: 60   }     # Set }up the setup timeout (default },60)
    "mimecast_siem_input": {credentials:
      "client_id": "<short<client_uniqueid_identifier>",value>
      "enabled": true,
      "requests_per_second": "requests_per_second_value",client_secret: <client_secret_value>
      "baseapp_url"id: "your<app_baseid_url",value>
      "authapp_url"key: "your<app_authkey_url",value>
      "pageSize"access_key: "page<access_sizekey_value",value>
      "autoconfig": {
 secret_key: <secret_key_value>
    services:
      "refreshservice_intervalmimecast_inclient_seconds": "refresh_interval_value",api:
        "creationlast_timeout_in_second": "creation_timeout_value"
      },
      "credentials": {configuration_timestamp: 2021-12-02T13:10:00Z # change this if you want to get your state changed!
        endpoints:
 "client_id": "your_client_id",        - "clientendpoints_secret"1:
"your_client_secret"       },       "services"name: {
     audit
  "service_mimecast_siem_client_api": {           "lastinitial_configurationlookback_timestamp"period: "last_configuration_timestamp_value",1d
          - "endpoints"_2:
 {             "siem"name: {attachments
              "initial_lookback_period": "1d"
          - endpoints_3:
}           }   name: impersonation
    }       }     }
}

Please replace the placeholders with real world values following the description table below:

Parameter

Data Type

Type

Value Range/ Format

Details

id

str

Mandatory

Minimum length: 1
Maximum length: 5

Alphanumeric identifier.

enabled

bool

Mandatory

true/false

Enables or disables the input.

base_url

str

Mandatory

• https://eu-api.mimecast.com

• https://de-api.mimecast.com

• https://us-api.mimecast.com

• https://usb-api.mimecast.com

• https://uspcom-api.mimecast-pscom-us.com

• https://ca-api.mimecast.com

• https://za-api.mimecast.com

• https://au-api.mimecast.com

• https://je-api.mimecast.com

The region related to the API credentials, the string value has to be one of the valid URL’s in https://integrations.mimecast.com/documentation/api-overview/global-base-urls/.

credentials

dictionary

Mandatory

initial_lookback_period: 1d
          - endpoints_4:
              name: url
              initial_lookback_period: 1d
          - endpoints_5:
              name: search
              initial_lookback_period: 1d
          - endpoints_6:
              name: view
              initial_lookback_period: 1d
          - endpoints_7:
              name: threatfeed
              initial_lookback_period: 1d
          - endpoints_8:
              name: messageholdlist
              initial_lookback_period: 1d
          - 

endpoints_9:
              name: messageholdsummary
              initial_lookback_period: 1d
          - endpoints_10:
              name: dashboard
         

Credentials to use the API.

endpoints

list

Mandatory

Minimum length: 1

Posible values:

   initial_lookback_period: 1d
  mimecast_siem_input:
   

 id: 2
    enabled: false
    

requests_per_second: 

5
    base_url: your_base_url
    

auth_url: your_auth_url
    pageSize: 10
    autoconfig:
      

refresh_interval_in_seconds: 60      # Runs the setup every x seconds 

(default 600)
      creation_timeout_in_second: 60  

      # Set up the setup 

timeout (default 60)
    credentials:
     

  client_id: <client_id_value>
        

client_secret: <client_secret_value>
        

app_id: <app_id_value>
        app_key: <app_key_value>
     

   access_key: <access_key_value>
      

  secret_key: <secret_key_value>
    services:
  

    service_mimecast_siem_client_api:
        

last_configuration_timestamp: 2021-12-02T13:10:00Z # change this if you want to get your state changed!
        endpoints:
   

      siem:
      

      initial_lookback_period: 0d
   

page_token: <page_token>

Replace the placeholders with your required values following the description table below:

        client_id: <client_id_value>
        

client_secret: <client_secret_value>

- endpoints_1:
    name: audit
    initial_lookback_period: 1d

- endpoints_2:
    name: attachments
   

 initial_lookback_period: 1d
- endpoints_3:
    name: 

impersonation
    

initial_lookback_period: 1d
- endpoints_4:
    name: url
    initial_lookback_period: 1d

- endpoints_5:
    name: 

search
    

initial_lookback_period

: 

1d

- endpoints_6:
    name: view
    

initial_lookback_period: 1d
- endpoints_7:
    name: threatfeed
  

  initial_lookback_period: 1d
- endpoints_8:
    name: 

messageholdlist
    initial_lookback_period: 1d
- endpoints_9:
    

name: 

messageholdsummary
    initial_lookback_period: 1d
- endpoints_10:
    name: dashboard

   initial_lookback_period: 

1d

We recommend to leave parameters not in the list with their default values.

Keep in mind that the Mimecast collector has two different inputs:

• mimecast_input

• mimecast_siem_input

The collector can use both inputs or just one. Each input uses different endpoints and feeds different tables in Devo. Make sure to check the credentials given to determine the inputs and endpoints to use. Using Postman is a great way to check the credentials to each input. Read more here.

Input

Endpoint

Tables

mimecast_input

• /api/audit/get-audit-events

• /api/ttp/attachment/get-logs

• /api/ttp/impersonation/get-logs

• /api/ttp/url/get-logs

• /api/archive/get-search-logs

• /api/archive/get-view-logs

• /api/ttp/threat-intel/get-feed

• /api/gateway/get-hold-message-list

• /api/gateway/get-hold-summary-list

• /api/account/get-dashboard-notifications

• mail.mimecast.audit.events

• mail.mimecast.ttp.attachment

• mail.mimecast.ttp.impersonation

• mail.mimecast.ttp.url

• mail.mimecast.archive.search

• mail.mimecast.archive.messageview

• mail.mimecast.threat.feed

• mail.mimecast.message.list

• mail.mimecast.message.summary

• mail.mimecast.account.dashboard

mimecast_siem_input

• /api/audit/get-siem-logs

• mail.mimecast.siem.receipt

• mail.mimecast.siem.process

• mail.mimecast.siem.delivery

• mail.mimecast.siem.jrnl

• mail.mimecast.siem.av

• mail.mimecast.siem.iep

• mail.mimecast.siem.impersonation

• mail.mimecast.siem.spameventthread

• mail.mimecast.siem.ttp

Change log

...

Release

...

Released on

...

Release type

...

Details

...

Recommendations

...

 v2.0.1

...

05 Aug 2024

...

gunzip -c <image_file>-<version>.tgz | docker load

docker run \
--name <YOUR_COLLECTOR_NAME>\
--volume $PWD/certs:/devo-collector/certs \
--volume $PWD/config:/devo-collector/config \
--volume $PWD/state:/devo-collector/state \
--env CONFIG_FILE=<YOUR-CONFIG-FILE>.yaml \
--rm -it <YOUR_DEVO_IMAGE_NAME>:<version>

version: '3'
services:
  <YOUR_COLLECTOR_NAME>:
    image: <YOUR_DEVO_IMAGE_NAME>:${IMAGE_VERSION:-latest}
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-<YOUR-CONFIG-FILE>.yaml}

IMAGE_VERSION=<version> docker-compose up -d

API limits and duplicates

The Mimecast API has some call rate limits. When a limit is reached, the collector shows a 429 error. More details about MImecast limits can be found here and here

The Mimecast API sometimes sends duplicate events (it is not common). The collector tries to filter out the duplicates, but it is not possible to guarantee that all duplicates are deleted.

Change log