Forcepoint and Microsoft Graph API

Table of contents

Forcepoint and Microsoft Graph API
Summary
Setup Azure Registration App
Implementation – Docker
1. Setup Forcepoint Microsoft Graph API Exporter Service
Appendixes
Troubleshooting
1. Docker Implementation

License

These contents are licensed under Apache License, Version 2.0. http://www.apache.org/licenses/LICENSE-2.0

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SITE AND ITS CONTENT IS PROVIDED TO YOU ON AN “AS IS,” “AS AVAILABLE” AND “WHERE-IS” BASIS. ALL CONDITIONS, REPRESENTATIONS AND WARRANTIES WITH RESPECT TO THE SITE OR ITS CONTENT, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT OF THIRD PARTY RIGHTS, ARE HEREBY DISCLAIMED

Document Revision

Version	Date	Author	Notes
0.1	11 June 2021	Rabih Abou Fakher	First draft

Summary

This guide provides step by step instructions to configure an integration between Forcepoint and Microsoft Graph API so that insights and data contained into Microsoft products are automatically exported and saved into managed files in order to perform further analytics and visualization

A description of the workflow between the components involved in this POC is depicted in the diagram below:

Source Code

fp-bd-graphapi-integration

Caveats

These implementation instructions are tested with the following product versions:

Microsoft Graph REST API v1.0

Implementation

Docker – leverages a docker image where the integration component is already installed with all necessary dependencies: the user only has to edit one configuration file and run the container on an existing docker setup

The docker image has been tested working with the following requirements

Docker 19.03.5
The docker-host machine should meet the minimum hardware requirements of 50GB of free storage, 2 GB of RAM and a 64-bit system

Setup Azure Registration App

To submit logs into AWS Security Hub, retrieve and configure AWS settings as described in this process. If AWS Security Hub is not already active, it will be activated automatically by the installation script.

In order to communicate with MS Graph API

Login to the Azure portal where Office 365 subscription resides
Search for App registrations and click on it
Click on New registration
Fill the name field with Forcepoint Graph API Integration and select the third option for the supported account types then click Register
Once the new application is created, keep a note of the client ID and the tenant ID
Click on Certificates & secrets, under Client secrets, click New client secret, fill the description, choose the expiry option and click Add
Once the client secret is created keep a note of the secret value in a safe location: once the page is refreshed the secret value won’t be retrievable anymore.
Click on API permissions, then click on Add a permission
Click on Microsoft Graph
Click on Application permissions
Check all the below permissions and then click on Add permissions:
- Directory.Read.All
- Files.Read.All
- Mail.Read
- Reports.Read.All
- Sites.Read.All
- ThreatAssessment.Read.All
- User.Read.All
Click on Grant admin consent
Confirm by clicking on the Yes button
Finally, you should see the list of permissions listed as below

Implementation – Docker

Setup Forcepoint Microsoft Graph API Exporter Service

Forcepoint Microsoft Graph API exporter service is used to exports the Office 365 data.

docker login docker.frcpnt.com

  $ Username: fp-integrations
  $ Password: t1knmAkn19s

Run the container with either one of the following commands, depending on your scenario

Run the container with the command below, replacing the <Azure-Graph-Client-Id> <Azure-Graph-Tenant-Id> <Azure-Graph-Client-Secret>

docker run --detach \
--env "GRAPH_CLIENT_ID=<Azure-Graph-Client-Id>" \
--env "GRAPH_TENANT_ID=<Azure-Graph-Tenant-Id>" \
--env "GRAPH_CLIENT_SECRET=<Azure-Graph-Client-Secret>" \
--name fp-graphapi-exporter \
--restart always \
--volume FpGraphAPIExporterDataVolume:/app/fp-graphapi-exporter/data \
--volume FpGraphAPIExporterLogsVolume:/app/fp-graphapi-exporter/logs \
docker.frcpnt.com/fp-graphapi-exporter

Or run the command below using a config file, replacing the <config-yml-path>, see the appendixes for an example of the configuration file

docker run --detach \
--name fp-graphapi-exporter \
--restart always \
--volume <config-yml-path>:/app/fp-graphapi-exporter/config/config.yml \
--volume FpGraphAPIExporterDataVolume:/app/fp-graphapi-exporter/data \
--volume FpGraphAPIExporterLogsVolume:/app/fp-graphapi-exporter/logs \
docker.frcpnt.com/fp-graphapi-exporter

There should be some directories in the below location after 1 hour

sudo ls /var/lib/docker/volumes/FpGraphAPIExporterDataVolume/_data/

Appendixes

Data Exported

Outlook Mail

Access the mail data of any user in a tenant.

Insights

Relationships calculated using advanced analytics and machine learning techniques. You can, for example, identify OneDrive documents trending around users.

Documents shared with a user. Documents can be shared as email attachments or as OneDrive for Business links sent in emails.
Documents from OneDrive and from SharePoint sites trending around a user.
Documents viewed and modified by a user. Includes documents the user used in OneDrive for Business, SharePoint, opened as email attachments, and as link attachments from sources like Box, DropBox and Google Drive.

Threat Assessment

Assess the threat received by any user in a tenant. This empowers customers to report spam emails, phishing URLs or malware attachments they receive to Microsoft.

Reports

With Microsoft Graph, you can access Office 365 usage reports resources to get the information about how people in your business are using Office 365 services.

Get details about Microsoft Teams device usage by user.
Use the Microsoft Teams activity reports to get insights into the Microsoft Teams user activity in your organization.
Get details about email activity users have performed.
Get details about which activities users performed on the various email apps
Get details about mailbox usage.
Get details about Office 365 active users.
Get details about OneDrive activity by user.
Get details about OneDrive usage by account.
Get details about SharePoint activity by user.
Get details about Skype for Business activity by user.
Get details about Skype for Business device usage by user.
Get details about Yammer activity by user.
Get details about Yammer device usage by user.

Configurations Table

Environment Variable	Config Variable	Required	Default Value
GRAPH_TENANT_ID	tenantId	YES
GRAPH_CLIENT_SECRET	clientSecret	YES
GRAPH_ENABLE_REPORTS	enableReports	No	true
GRAPH_REPORTS_CRON_SCHEDULER	reportsCronScheduler	No	0 0 * * *
GRAPH_ENABLE_THREAT_ASSESSMENT_REQUESTS	enableThreatAssessmentRequests	No	true
GRAPH_THREAT_ASSESSMENT_REQUESTS_CRON_SCHEDULER	threatAssessmentRequestsCronScheduler	No	0 * * * *
GRAPH_ENABLE_INSIGHTS	enableInsights	No	true
GRAPH_INSIGHTS_CRON_SCHEDULER	insightsCronScheduler	No	0 * * * *
GRAPH_ENABLE_MAIL	enableMail	No	true
GRAPH_MAIL_CRON_SCHEDULER	mailCronScheduler	No	0 * * * *
APP_ENABLE_DELETE_FILES	enableDeleteFiles	No	true
APP_DELETE_FILES_CRON_SCHEDULER	deleteFilesCronScheduler	No	0 0 1 * *
APP_DELETE_FILES_DAYS_OLD	deleteFilesDaysOld	No	30
APP_DATA_DIRECTORY_PATH	dataDirectoryPath	No	\<fp-graphapi-exporter-home-path\>/data

Example of a configuration file

services:
  graph:
    clientId: ""
    tenantId: ""
    clientSecret: ""
    enableReports: false
    reportsCronScheduler: "0 0 * * *'" # run everyday at midnight
    enableThreatAssessmentRequests: false
    threatAssessmentRequestsCronScheduler: "*0 * * * *" # run every hour
    enableInsights: false
    insightsCronScheduler: "*0 * * * *"
    enableMail: false
    mailCronScheduler: "*0 * * * *"
  app:
    name: "fp-graph-api"
    enableDeleteFiles: false
    deleteFilesCronScheduler: "0 0 1 * *" # run every 00:00 on day-of-month 1
    deleteFilesDaysOld: 1
    dataDirectoryPath: /opt/fp-graph-api/data

Troubleshooting

Follow these steps to identify issues impacting the normal operation of the integration described in this document.

Docker Implementation

Validate the prerequisites

Make sure the prerequisites described in the Summary chapter are all satisfied:

Docker images for this integration have been tested with Docker 19.03.5
The docker implementation has been tested on a 64-bit system Linux machine with docker engine installed, minimum of 2GB RAM and a free space of at least 50GB
Make sure your Azure account has Office 365 subscription
User needs sudo permissions in the docker host machine

Check dependencies are installed

Make sure the software dependencies needed by the components involved in this integration are installed:

Check the host machine has docker installed: Execute the following command on the host machine:

docker info

Check the first few lines of the output are similar to below:

Client:
Debug Mode: false

Server:
Containers: 3
Running: 2
Paused: 0
Stopped: 1
Images: 3
**Server Version: 19.03.5**

Check all components are configured and running properly

Make sure the products and services involved into this integration are configured as expected and they are running:

Make sure the products and services involved in this integration are configured as expected and they are running:

Check the logfile: Run the following command on docker host machine:
```
sudo cat /var/lib/docker/volumes/FpGraphAPIExporterLogsVolume/_data/trace.log
```
There should be no errors in the trace.log file
Check there is data after the integration is run: Run the following command in the docker host machine:
```
sudo ls /var/lib/docker/volumes/FpGraphAPIExporterDataVolume/_data/
```
There should be some directories in the above location after 1 hour