Mimecast Plugin for User Risk Exchange

This document explains how to configure the Mimecast plugin with User Risk Exchange in the Netskope Cloud Exchange platform. This plugin supports pulling of User Risk Scores from the Mimecast platform. This plugin supports performing actions on the users such as Add to Group, Remove from Group, and No Action.

Prerequisites

To complete this configuration, you need:

CE Version Compatibility

Netskope CE v4.2.0, v5.0.1

Mimecast Plugin Support

This plugin is used to pull User Risk Scores and perform action on the User.

Type of data pulled	Users
Type of Actions Supported	Add to Group Remove from Group No Action

Mappings

Pull Mapping

Netskope CE Fields	Mimecast Fields
score	risk
uid	emailAddress

Score Mapping

Score mapping for risky users is different from others. Mimecast has scores in form of grade and each grade has been mapped with a defined numeric score in CE which is as follows.

Netskope CE Score	Mimecast Score
800	A
600	B
400	C
200	D
1	F

Permissions

• Administration Console access
• Permission to Create a User
• Permission to add created user to Basic Administrator Role
• Administration Console access

API Details

List of APIs used

API Endpoint	Method	Use Case
/api/account/get-account	GET	To validate the credentials.
/api/awareness-training/company/get-safe-score-details	POST	To fetch the OS SAFE Score user level details and user risk scores.
/api/directory/find-groups	POST	To fetch the all available groups on Mimecast platform.
/api/directory/add-group-member	POST	To add the user into the given group of Mimecast.
/api/directory/remove-group-member	POST	To remove the user from the given group of Mimecast.

Validate Credentials

API Endpoint: <Mimecast Base URL>/api/account/get-account
Method: GET
Request Headers

{
“authorization”: “A signature includes a user specific Access Key and a combination of unique
                        values signed with a user specific Secret Key using HMAC-SHA1 encryption.”
“x-mc-req-id”: “A randomly generated GUID, for example”
“x-mc-app-id”: “The Application ID provided with your Registered API Application.”
“x-mc-date”: “Current date and time in UTC”
}

Request Body:

{
 "data": []
}

API Request Endpoint: <Mimecast Base URL>/api/account/get-account
Sample API Response:

{
 "fail": [], 
 "meta": {
  "status": 200
 }, 
 "data": [
  {
   "maxRetention": 30, 
   "accountCode": "String", 
   "domain": "String", 
   "automatedSegmentPurge": false, 
   "databaseCode": "String", 
   "supportCode": "String", 
   "region": "String", 
   "accountName": "String", 
   "maxRetentionConfirmed": false, 
   "archive": false, 
   "gateway": true, 
   "policyInheritance": false, 
   "passphrase": "String", 
   "type": "String", 
   "mailPlatform": "String", 
   "packages": [
    "String"
   ], 
   "mimecastId": "String", 
   "adminEmail": "String", 
   "userCount": 20
  }
 ]
}

Fetch Users & Scores

API Endpoint: <Mimecast Base URL>/api/awareness-training/company/get-safe-score-details

Method: POST

Request Headers

{
“authorization”: “A signature includes a user specific Access Key and a combination of unique
                        values signed with a user specific Secret Key using HMAC-SHA1 encryption.”
“x-mc-req-id”: “A randomly generated GUID, for example”
“x-mc-app-id”: “The Application ID provided with your Registered API Application.”
“x-mc-date”: “Current date and time in UTC”
}

Request Body:

{
 "data": [
  {
   "filterBy": [
    {
     "fieldName": "String", 
     "value": "String"
    }
   ], 
   "attributeIds": [
    "String"
   ], 
   "searchBy": {
    "fieldName": "String", 
    "value": "String"
   }
  }
 ]
}

Sample API Response:

{
 "fail": [], 
 "meta": {
  "status": 200
 }, 
 "data": [
  {
   "humanError": "String", 
   "emailAddress": "String", 
   "name": "String", 
   "sentiment": "String", 
   "department": "String", 
   "engagement": "A", 
   "knowledge": "A", 
   "risk": "A"
  }
 ]
}

Pull Available Groups

API Endpoint: <Mimecast Base URL>/api/directory/find-groups
Method: POST
Request Headers:

{
“authorization”: “A signature includes a user specific Access Key and a combination of unique
                        values signed with a user specific Secret Key using HMAC-SHA1 encryption.”
“x-mc-req-id”: “A randomly generated GUID, for example”
“x-mc-app-id”: “The Application ID provided with your Registered API Application.”
“x-mc-date”: “Current date and time in UTC”
}

Request Body:

{
 "meta": {
  "pagination": {
   "pageToken": "String", 
   "pageSize": 25
  }
 }, 
 "data": [
  {
   "query": "String", 
   "source": "String"
  }
 ]
}

Sample API Response:

{
 "fail": [], 
 "meta": {
  "status": 200, 
  "pagination": {
   "pageSize": 1
  }
 }, 
 "data": [
  {
   "folders": [
    {
     "description": "String", 
     "source": "String", 
     "folderCount": 0, 
     "parentId": "String", 
     "id": "String", 
     "userCount": 10
    }
   ], 
   "source": "String", 
   "query": "String"
  }
 ]
}

Add User to Group

API Endpoint: {Mimecast Base URL}/api/directory/add-group-member
Method: POST
Request Headers:

{
“authorization”: “A signature includes a user specific Access Key and a combination of unique
                        values signed with a user specific Secret Key using HMAC-SHA1 encryption.”
“x-mc-req-id”: “A randomly generated GUID, for example”
“x-mc-app-id”: “The Application ID provided with your Registered API Application.”
“x-mc-date”: “Current date and time in UTC”
}

Request Body:

{
 "data": [
  {
   "domain": "String", 
   "emailAddress": "String", 
   "id": "String"
  }
 ]
}

Sample API Response:

{
 "fail": [], 
 "meta": {
  "status": 200
 }, 
 "data": [
  {
   "folderId": "String", 
   "emailAddress": "String", 
   "id": "String", 
   "internal": true
  }]}

Remove User from Group

API Endpoint: <Mimecast Base URL>/api/directory/remove-group-member
Method: POST
Request Headers:

{
“authorization”: “A signature includes a user specific Access Key and a combination of unique values signed with a user specific Secret Key using HMAC-SHA1 encryption.”
“x-mc-req-id”: “A randomly generated GUID, for example”
“x-mc-app-id”: “The Application ID provided with your Registered API Application.”
“x-mc-date”: “Current date and time in UTC”
}

Request Body:

{
 "data": [
  {
   "domain": "String", 
   "emailAddress": "String", 
   "id": "String"
  }]}

Sample API Response:

{
 "fail": [], 
 "meta": {
  "status": 200
 }, 
 "data": [
  {
   "folderId": "String", 
   "emailAddress": "String", 
   "id": "String", 
   "internal": true
  }
 ]
}

Performance Matrix

The readings are conducted by pulling 500K user and their risk scores on a large CE Stack with these mentioned specifications.

Stack details	Size: Large RAM: 32 GB CPU: 16 Cores
Users fetched from Mimecast	500K
Time Taken to pull and store user risk scores	~60 minutes

User Agent

netskope-ce-5.0.1-ure-mimecast-v1.0.3

Workflow

Click play to watch a video.

Creating a New User

1. Log in to Mimecast and go to Directories > Internal Directories.
   
2. Select the internal directories where you would like to create your new user.
   
3. Click New Address on the menu bar.
   
4. Complete the new address form by entering a new email address, the user’s password and phone number (required for 2FA). Click Save and then Exit to create the new user with provided details.

   Note

   Keep a copy of the password;  you will use this to get your Authentication Tokens later.

   

Add the Newly Created User to an Administrative Role

1. Go to the Account > Roles to display the Roles page.
   
2. Right-click the Basic Administrator role, and select Add users to the role.
   
3. Browse or search to find the new user created previously.
4. Select the checkbox to the left of the user.
5. Click Add Selected Users to add the user to the role.
   

Create a New Group and Add Your User

1. Go to the Directories > Profile Groups to display the Profile groups page.
2. Create a new group by selecting the plus icon on the parent folder where you would like to create the group. This creates a new group with the name New Folder.
3. To rename the group, select the newly created New Folder group. Then from the Edit group text box type the name you want to give the folder, and press the Enter key to apply the change.
4. With the selected group, click on the Build dropdown menu and select Add Email Addresses.
   
5. Enter the name of the new user created previously.
6. Click Save and Exit to add the new user to the group.
   

Create a New Authentication Profile

1. Go to the Services > Applications to display the Application Settings page.
2. Click Authentication Profiles.
3. Click New Authentication Profile.
   
4. Type a Description for the new profile.
5. Set the Authentication TTL setting to Never Expires. This will make sure that when you create your Authentication Token, it will not expire and impact the data collection of the app.
6. Leave all other settings as their default, and then click Save and Exit to create the profile.

Create a New Application Setting

1. Go to the Services > Applications to display the Application Settings page.
2. Click New Application Settings.
   
3. Enter a Description, and use the Group Lookup button to select the Group that you created previously.
4. Use the Authentication Profile Lookup button to select the Authentication Profile created previously.
5. Leave all other settings as their default.
6. Click Save and then Exit to create and apply the Application Settings to your new group and user.

Create a New API Application

1. Go to the Services > API and Platform Integrations menu item to display the available API Application.
   
2. Click Mimecast API 1.0 > Generate Keys.
3. Enter the appropriate information. Check Enable Extended Session, which will ensure your API token will never expire. Select Other for Category, and then click Next.
   
4. Enter an appropriate Developer Name and enter the Email address created previously, which will link the user’s application/profile settings to the API application. Click Next.
   
5. Review the entered configuration parameters, and edit them if required. Click Add.
6. Your API application will be created, and its details will be displayed. Click on the small eye icon beside the Application Key in order to view it. Copy the Application ID and Application Key; you will use these when configuring the plugin.
   

Get your Access Key and Secret Key

1. Go to the Services > API and Platform Integrations to display the available API Applications.
2. Click on the newly created API application, and then click Create Keys from the top menu.
3. Enter the email address of the user created previously, and then click Next.
   
4. Select Cloud for the Type,and enter the password of the user created previously. Click Next.
   
5. Copy both of the keys by pressing the small eye buttons, and then click Close. These will be used to configure the plugin.
   

Configure a User Risk Exchange Business Rule for the Mimecast Plugin

Use a Business Rule to filter out the users on which you want to perform actions. Follow these steps to configure a business rule.

1. Go to User Risk Exchange > Business Rules and click Create New Rule.
2. Add the filter based on your requirements, and then click Save.

Configure User Risk Exchange Actions for the Mimecast Plugin

Mimecast supports Add to Group, Remove from Group and No Action. To add and perform any of the actions, follow the below steps.

Add to a Group

Whenever an action triggers, this action adds users to the group that was defined while creating the action configuration.

1. Go to User Risk Exchange > Actions and click Add Action Configuration.
2. Select a Business Rule, a Configuration (Mimecast plugin), and select Add to Group for the Action.
3. Select an existing group in the Group dropdown to add the user to an existing group, or select Create new group and enter a Group Name (if you have selected the Create New Group option in the Group parameter).
4. Click Save.

   Note

   Creating a new group from Cloud Exchange doesn’t support creating a Sub-Group on Mimecast.

Remove from a Group

Whenever an action triggers, this action removes users from the group that has been defined while creating the action configuration.

1. Go to User Risk Exchange > Actions and click Add Action Configuration.
2. Select a Business Rule, a Configuration (Mimecast plugin) and select Remove from group for the Action.
3. Select a group from the Group dropdown to remove the user from an existing group.
4. Click Save.

No Action

This action is used to generate alerts in the Ticket Orchestrator module of Cloud Exchange. Follow these steps to configure and perform this action.

1. Go to User Risk Exchange > Actions and click Add Action Configuration.
2. Select a Business Rule, a Configuration (Mimecast plugin), and select No Action for the Action.
3. Click Save.
   Your Action configurations are shown on the Actions page.
   

Validate the Mimecast Plugin

Validation on CE

To validate the pulling of Users and their Risky scores, go to Logging and filter the logs from the Mimecast plugin.

Go to Users and check the users and their scores pulled from the Mimecast platform.

To validate the action is performed successfully, go to Logging, and filter logs as: message contains Mimecast and message contains Successfully performed action.

You can also go to Action Logs in User Risk Exchange and check the logs for the recently performed actions.

Validate on Mimecast

You can pull Users and their Risky scores from the Risk Center on Mimecast. To validate the same, go to Awareness Training > Reporting and Insights > Risk Center. Click View Details in the bottom right corner and check the users and their scores available.

Go to Directories > Profile Groups and the list of groups will be available. You add and remove users from the groups available on this page.

Troubleshooting

Unable to configure the Mimecast plugin

If the plugin is not configured, the credentials might be incorrect/deleted or the user role is insufficient.
What to do:
Check the credentials generated, and check if sufficient Roles are added.

Unable to pull the users or their Risk Scores

If you are unable to pull Users or scores in CE, check these possible scenarios.

• The users are available on the platform to pull
• The user scores are not pulled in CE.

What to do:
If the users are not fetched from the plugin, check if you have any users and their scores to pull from Mimecast.

Unable to perform the Action on User

If you are not able to perform any action and receiving error while performing the action, check the root cause it might be one of the below issue:

• The user on which action is performed is already added/removed from the group.
• The user in which action is being performed is not present on Mimecast.
• The Group using which a user is added/removed does not exist on the platform.

What to do:

• Find the root cause of the issue by confirming firstly if the User and group exists on Mimecast.
• If both exist, check if the user is already present in the group, in case of Add to Group action. If a user is already present in the group, and the action Add to Group is performed for the same user, the plugin will throw an error since the user is already present in the group. The same goes for removal from the group.

Receiving error: Proxy server or Mimecast server is not reachable

If you are receiving the above error while configuring the plugin or at any point of time after the plugin is configured. It means the plugin is not able to connect to either the Mimecast platform or, if CE is using proxy, the proxy server is not reachable.
What to do: If the Mimecast is not reachable, all you could do is wait or contact your Mimecast support team, if the proxy server is not reachable try and find the root cause by contacting your IT team.