Mimecast Plugin for Risk Exchange

This document explains how to configure the Mimecast v2.0.0 plugin with the Risk Exchange module in the Netskope Cloud Exchange platform. This plugin is used to fetch users from Awareness Training > Reporting and Insights > Risk Center > View Details page of the Mimecast platform. This plugin supports performing actions such as Add to Group, Remove from Group, and No Action on Mimecast users.

Netskope normalization score calculation for users:

• Grade A: 800
• Grade B: 600
• Grade C: 400
• Grade D: 200
• Grade F: 1.

Prerequisites

To complete this integration, you need:

• A Netskope tenant (or multiple, for example, production and development/test instances).
• A Netskope Cloud Exchange tenant with the Tenant plugin and Risk Exchange plugin already configured.
• Mimecast platform credentials.
• Mimecast administrator with at least the Awareness Training | Dashboard | Read permission.
• Mimecast administrator with at least the Directories | Groups | Edit permission.
• Mimecast administrator with at least the Accounts | Dashboard | Read permission.
• Mimecast platform that has access administrator and awareness training console access. Refer to the documents for more details:
  • Mimecast Knowledge Hub
  • Awareness Training
• Connectivity to the following host: https://login.mimecast.com/.

Mimecast Plugin Support

This plugin is used to fetch users from Mimecast platform > Awareness Training > Reporting and Insights > Risk Center > View Details page. This plugin supports performing actions such as Add to Group, Remove from Group, and No Action.

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

Mappings

Pull Mapping

Plugin Field Label	Expected Data Type	Suggested Field Label	Aggregate Strategy
User Email	String	Mimecast User Email	Unique
User Name	String	Mimecast User Name	Overwrite
User Risk	String	Mimecast User Risk	Overwrite
Netskope Risk Category	String	Netskope Risk Category	Overwrite
Netskope Normalized Score	Number	Netskope Normalized Score	Overwrite

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 Cloud Exchange as follows.

Note that the minimum value for the defined score will be mapped in the Cloud Exchange based on the Score grade of Mimecast. For example, if the grade on Mimecast is A, the score in Cloud Exchange will be 800. The score normalization will be stored in the Netskope Normalized Score field.

Netskope Normalized 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 a created user to the Basic Administrator Role.

API Details

List of APIs used

API Endpoint	Method	Use Case
/oauth/token	Post	To obtain an Access Token call the /oauth/token endpoint. The TTL for the token is 15 minutes, and the same endpoint should be called on expiry.
/api/account/get-account	Post	This endpoint returns the summary details for an account in Mimecast.
/api/directory/find-groups	Post	This endpoint can be used to find groups that exist on a mimecast tenant.
/api/directory/create-group	Post	This API endpoint can be used to create new Profile Groups.
/api/directory/add-group-member	Post	This endpoint can be used to add user email addresses or domains to a profile group.
api/directory/remove-group-member	Post	This endpoint can be used to remove group members from Mimecast Profile groups.
/api/awareness-training/company/get-safe-score-details	Post	This API endpoint can be used to get Awareness Training Mime|OS SAFE Score user level details and grades, including User Risk,

Get a Bearer Token

API Endpoint: https://api.services.mimecast.com/oauth/token
Method: POST
Request Headers

Key	Value
client_id	Mimecast Client ID
client_secret	Mimecast Client Secret
grant_type	client_credentials
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Sample API Response

{
    "access_token": "V9RteK0pwTxPscMCCd6xs20f05Ob",
    "token_type": "Bearer",
    "expires_in": 1799,
    "scope": ""
}

Validate Credentials

API Endpoint: https://api.services.mimecast.com/api/account/get-account
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Sample API Response

{
    "meta": {
        "status": 200
    },
    "data": [
        {
            "region": "us",
            "archive": false,
            "gateway": true,
            "passphrase": "",
            "supportCode": "5656",
            "maxRetention": 30,
            "maxRetentionConfirmed": true,
            "minRetentionEnabled": false,
            "automatedSegmentPurge": true,
            "type": "full",
            "policyInheritance": false,
            "databaseCode": "test",
            "searchReason": false,
            "contentAdministratorDefaultView": "",
            "adminSessionTimeout": 720,
            "exportApi": false,
            "exgestAllowQuery": false,
            "exgestAllowExtraction": true,
            "expressAccount": false,
            "cybergraphV2Enabled": true,
            "accountCode": "",
            "accountName": "",
            "adminEmail": "",
            "contactEmail": "testuser@gmail.com",
            "domain": "",
            "userCount": 10,
            "umbrellaAccounts": [
                "CU2A110,CUSA131A2,CUSA133A2,CUSA42A10,CUS"
            ],
            "mimecastId": "01-1234-123",
            "contactName": "test user",
            "telephone": "123-123-123",
            "packages": [
                "Auto Responders (Site) [1005]",
                "Impersonation Protection [1060]",
            ]
        }
    ],
    "fail": []
}

Fetch Users and Scores

API Endpoint: https://api.services.mimecast.com/api/awareness-training/company/get-safe-score-details
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Request Body

{
    "meta": 
    {
        "pagination": {
            "pageSize": 100,
            "pageToken": ""
        }
    }
}

Sample API Response

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

Pull Available Groups

API Endpoint: https://api.services.mimecast.com/api/directory/find-groups
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Request Body

{
    "meta": 
    {
        "pagination": {
            "pageSize": 100,
            "pageToken": ""
        }
    }
}

Sample API Response

{
    "meta": {
        "pagination": {
            "pageSize": 100,
            "totalCount": 120,
            "next": ""
        },
        "status": 200
    },
"data": [
        {
            "source": "cloud",
            "folders": [
                {
                    "id": "string",
                    "description": "demo",
                    "source": "cloud",
                    "parentId": "string",
                    "userCount": 2,
                    "folderCount": 0
                },
],
    "fail": []
}

Add a User to a Group

API Endpoint: https://api.services.mimecast.com/api/directory/add-group-member
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Request Body

{
    "data":[
        {
            "id": "string",
            "emailAddress":"abc@test.com"
        },
        {
            "id": "string",
            "emailAddress":"test@gmail.com"
        }
    ]
}

Sample API Response

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

Remove a User from a Group

API Endpoint: https://api.services.mimecast.com/api/directory/remove-group-member
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Request Body

{
    "data":[
        {
            "id": "string",
            "emailAddress":"abc@test.com"
        },
        {
            "id": "string",
            "emailAddress":"test@gmail.com"
        }
    ]
}

Sample API Response

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

Create a Group

API Endpoint: https://api.services.mimecast.com/api/directory/create-group
Method: POST
Request Headers

Key	Value
Authorization	Bearer <Bearer Token>
User-Agent	netskope-ce-5.1.0-cre-mimecast-v2.0.0

Request Body

{
    "data": [
        {
        "description": "Created Group"
        }
    ]
}

Sample API Response

{
    "meta": {
        "status": 200
    },
    "data": [
        {
            "id": "string",
            "description": "Created Group",
            "source": "cloud",
            "parentId": "string",
            "userCount": 0,
            "folderCount": 0
        }
    ],
    "fail": []
}

Performance Matrix

Here is the performance matrix conducted on a Large CE Stack with these specifications by pulling 500K users.

Stack Size	Large RAM: 32 GB Core: 16
Time taken to store the pulled and updated Users records	~17 mins

User Agent

netskope-ce-5.1.0-cre-mimecast-v2.0.0

Workflow

1. Create a new user and add the user to an Administrative Role.
2. Create a new group and add the user to the group.
3. Create an Authentication Role.
4. Create an Application Setting.
5. Create an API Application.
6. Get your Access Key and Secret Key.
7. Configure the Mimecast plugin.
8. Add a Business Rule for Mimecast.
9. Add Actions for Mimecast.
10. Validate the Mimecast plugin.

Click play to watch a video.

Create 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 setting a new email address, user’s password, and phone number (required for 2FA).
   Keep a copy of the password because you will use this to get your Authentication Tokens at a later stage.
   Click Save and Exit to create the new user with provided details.

   

Add the newly created User to an Administrative Role

1. Go to the Account > Roles to open 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 you 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 open 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, and from the Edit group text box, enter the name you want to give the folder, and then press Enter to apply the change.
4. With the selected group, click on the Build dropdown button, and select Add Email Addresses.
   
5. Enter the email 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 open the Application Settings page.
2. Select Authentication Profiles.
3. Select 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. On the Application Settings page, select the New Application Settings.
   
2. Type a Description, and use Group Lookup to select the Group that you created previously.
3. Use Authentication Profile Lookup to select the Authentication Profile created previously.
4. Leave all other settings as their default.
5. Click Save and 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 to display the available API Application.
   
2. Click Mimecast API 2.0 > Generate Keys.
3. Accept the Disclaimer and then click Next.
4. Enter the appropriate information. Select Other for Category, and Basic Administrator for Application Role. Click Next in the bottom right.
   
5. Enter appropriate Developer Name and enter the Email address created for the New User previously, which will link the user’s application/profile settings to the API application. Click Next.
   
6. Review the entered configuration parameters; edit them if required, and then click Add.
7. Your API application will be created, and its details will be displayed. Click on the small eye icon beside the Application Key in in order to view the Client ID and Secret. Copy the Client ID and Client Secret.
   
8. Click Close.

Configure the Mimecast Plugin

1. In Cloud Exchange, go to Settings > Plugins. Search for and select the Mimecast v2.0.0 (CRE) plugin box.
   
2. Enter a Configuration Name, and change the sync interval per your requirement. 
   
3. Click Next. Enter your Mimecast Client ID and Client Secret.
   
4. Click Next. Select the Entity from the Entity dropdown. The Entity fields can be created from the Schema editor page, or using the + Add Field option on the field dropdown. Provide the field mapping. For the suggested mappings, refer to the Mappings section.
   The User Email field will be required to pull the Users, and to perform action on the pulled Users.
   
5. Click Save.
   

Add a Risk Exchange Business Rule for Mimecast

1. In Risk Exchange, go to Business Rules.
2. Click Create New Rule.
3. Enter a Rule Name. Select the Entity in which Fields have been configured for the mimecast plugin, and configure the query based on your requirements. The below example fetches users containing @crestdatasys.com in User Email.
   
4. Click Save.
   

Add Risk Exchange Actions for Mimecast

Mimecast supports the following 3 actions types:

• Add to Group: Add to Group action adds users to the group that has been mentioned while creating the action configuration.
• Remove from Group: Remove from Group action removes users from the group that has been mentioned while creating the action configuration.
• No Action: No action will be performed for this action. Users can generate alerts in CTO by using this action and enabling the generate alerts toggle button.

NOTE: You can perform the actions on the users pulled from Mimecast on the Netskope Tenant, for performing the user related actions on Netskope refer to the Netskope’s plugin guide.

Add to Group

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

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select s Business Rule, plugin Configuration (Mimecast), and for Action, select Add to group.
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, then add User Email as static or from Source. The Group field should be selected as static in the dropdown.
   
   Click Save.
   
   Note: Creating a new group from CE, won’t support creating Sub-Group on Mimecast.

Remove from Group

Whenever an action triggers, this action removes users from the group that was selectd while creating the Action configuration.

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select s Business Rule, plugin Configuration (Mimecast), and for Action, select Remove from group.
3. Select a group from the Group dropdown to remove the user from an existing group. Group field should be selected as static in the dropdown.
   
4. Click Save.
   

No Action

This action is used to generate alerts in the Ticket Orchestrator module of Cloud Exchange. 

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select s Business Rule, plugin Configuration (Mimecast), and for Action, select No action.
   
3. Click Save.
   

Validate the Mimecast Plugin

Validate on Cloud Exchange

To validate the pull:

1. In Risk Exchange, go to Records. Select the Entity that is selected while configuring the field mapping for the user to view the pulled users.
   
2. Go to Logging and search for the logs of the plugin.
   
3. Look here to verify the action was performed for a user.
   
4. You can also go to Action Logs and check the Action logs for the recently performed action.
   

Validate on Mimecast

Mimecast pulls Users and their Risk scores from the Risk Center. To validate these, go to Awareness Training > Reporting and Insights > Risk Center. Click View Details to check the users and their available scores.

Validate a Performed Action on Mimecast

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

Troubleshooting the Mimecast Plugin

Plugin configuration not working after the plugin upgrade

If the plugin configuration stops working, like you do not see any logs related to the configured plugin after the plugin upgrade to version 2.0.0.

What to do:

Disable the plugin configuration, and then enable the plugin configuration.

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 were added.

Unable to pull the users or their Risk Scores

If you are unable to pull Users or scores in CE, it may be due to one of these reasons:

• The users are available on the platform to pull.
• The user scores are not pulled in CE.
• Mapping is not added while configuring the plugin in the entity source page.

What to do:

1. If the users are not fetched from the plugin, check if you have any users and their scores to pull from Mimecast.
2. Make sure that the mapping is added and the User Email field is mapped while configuring the plugin.

Unable to perform the Action on User

If you are not able to perform any action and receiving an error while performing the action, it may be due to one of these reasons:

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

What to do:

1. Find the root cause of the issue by confirming firstly if the User and group exists on Mimecast.
2. If both exist, check if the user is already present in the group in case of the 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.

Unable to View users details on the Record

If you are unable to view users’ details on the record table, it may be due to one of these reasons:

• Mapping for all the Mimecast fields was not provided while configuring the Mimecast plugin.
• Pulled users are displayed in a row with comma-separated values.

What to do:

1. Make sure to provide the needed mapping while configuring the plugin.
2. Make sure that the fields created in an entity are according to the Mapping section.

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 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.