General context

Nowdays it is really important to being able to monitor and control the IT infrastructure of a company against security threats, identity risks, data breaches, etc. From a general viewpoint, it is clearly fundamental to have full control of the security of your infrastructure, but also from a EU GDPR perspective you have to adhere to some requirements and you have to accomplish some tasks, which require you to have a full and proactive monitoring of your data and services.

When thinking about the cloud – generally speaking – you can consume a safer and more reliable set of services, which in the case of Microsoft 365 can help you become GDPR compliant, but at the same time you still have on-premises services and devices, which need to be monitored, controlled, and managed.

Microsoft offers a set of services on top of Microsoft Office 365 or included in Microsoft 365 that help you achieve that level of proactive control that you need, which allow you to monitor and govern both the on-premises infrastructure, and the cloud services. Thinking about services like Microsoft Cloud App Security, the Data Loss Prevention capability of Microsoft Office 365, the Windows Advanced Threat Protection (ATP) service, the Identity Protection of Azure AD Premium, etc. there is a huge amount of data and information that Microsoft can use to protect you and your data. This wide set of data, events, information, and alerts that Microsoft uses to keep you safe, are also called the Microsoft Intelligent Security Graph (ISG), which uses rich insights from vast security intelligence, machine learning, and behavioral analytics to help you improve investigations and speed up response.

Moreover, from a developer’s perspective, the ISG can be consumed through REST API provided by the services involved. For example, the Cloud App Security service has its own REST API, Windows ATP has its own REST APIs, Azure Active Directory Premium provides the Microsoft Graph Identity Protection APIs available within the Microsoft Graph, etc.

Reading this article, you can learn how to consume some of those APIs from any client capable of managing REST requests. In fact, being able to leverage those security services from a custom developed solution allows you to create smart monitoring tools that can help you or your customers to better manage and control the security of their business, and the compliancy with the EU GDPR requirements.

Consuming the Cloud App Security service

In order to consume the Cloud App Security service, you need to register your client application and retrieve an Authorization token, which will allow you to consume the service within a secure context. Thus, once you have activated the Cloud App Security service in your tenant, browse to its web-based management UI (see Fig. 1), which is available at the URL https://[tenant-name].portal.cloudappsecurity.com/ and select the “gear menu” in the upper right side of the page, then choose the “Security Extensions” menu item.

Figure 1 – Cloud App Security Dashboard

This will open a new page (see Fig. 2), where you can register a client application simply by providing the application name. You will get back a token, which you will use in any further request to the REST API of the service.

Figure 2 – The Security Extensions page of Cloud App Security

In order to understand what the services available through the API are, you can click on the question mark button, in the upper right corner of the screen and select “API documentation”, which will bring you to the URL https://[tenant-name].[region].portal.cloudappsecurity.com/api-docs/ . There you can find detailed documentation about the available actions. At the time of this writing, you can find APIs to:

• Manage IP address ranges: to define “familiar” ranges of IP addresses.
• Read users’ accounts: to browse the monitored users’ accounts.
• Read users’ activities: to read the activities related to the users.
• Read and manage alerts: to inspect alerts and insights about security events.
• Manage log files: to upload and manage log files, related to on-premises appliances, that can then be analyzed by the Cloud App Security service.

To consume these services, you will simply need to make an HTTP request using the proper verb (GET, POST, PUT, etc.) and providing an Authorization header of type Token and with the value of the token you got back from the “Security Extensions” page. Just for the sake of making an example, here follows the trace of a request for the first 100 activities related to a specific user.

HTTP POST https://[tenant-name].[region].portal.cloudappsecurity.com/api/v1/activities/
Authorization: Token [security-token-value]
Content-Length: 120
Content-Type: application/json
Accept: application/json
{
  "filters": {
    "user.username": {
      "eq":"john@contoso.com"
    }
  },
  "skip": 0,
  "limit": 100
}

As you can see, the HTTP verb is POST, because the request provides a JSON body with the filter to apply. In fact, most of the operations accept a JSON filter to query and partition results. In the documentation page of the APIs you can find detailed information and examples about the available filters.

Consuming the Microsoft Graph Identity Protection APIs

Another interesting set of services that you can query are the Identity Protection APIs of Azure Active Directory Premium. Those services are available through the beta endpoint of the Microsoft Graph, and you can find detailed information and documentation about them at the following URL: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/identityprotection_root.

The APIs provide actions to retrieve a rich set of events like: “Identity Risks”, “Anonymous IP Risks”, “Impossible Travel Risks”, “Leaked Credentials Risks”, “Malware Risks”, “Suspicious IP Risks”, “Unfamiliar Location Risks”. As you can argue from the events’ names, they are related to potential identity risks. Just to make an example, the events of type “Impossible Travel Risks” will inform you of any login happened from a location impossible to be reached within a reasonable amount of time, if compared with the previous login location. Thus, the options are that the user is in VPN with a remote location, or that her/his identity was compromised and used by an unauthorized subject somewhere else in the world. By querying such event, you will get back the current login location, IP, and date time, as well as the previous login location, IP, and date time.

In order to consume the Identity Protection APIs, you will need to register an application in Azure AD, and assign it proper permissions. The permissions to consume the Identity Protection APIs is IdentityRiskEvent.Read.All (defined “Read all identity risk event information” in the Azure AD management UI) either using a delegated token, or an application token. To query the APIs you will have to retrieve an OAuth 2.0 Access Token through Azure AD, and once you’ll have the token, you will simply need to make HTTP requests as like as you would do for any other Microsoft Graph endpoint. Here follows a sample trace of a request for an “Impossible Travel Risk” event, selected by ID.

HTTP GET https://graph.microsoft.com/beta/impossibleTravelRiskEvents/{id} 
Authorization: Bearer [access-token]
Accept: application/json

And the response will look like the following excerpt.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 260

{
  "@odata.type": "#microsoft.graph.impossibleTravelRiskEvent",
  "closedDateTime": "2016-01-29T20:03:57.7872426Z",
  "createdDateTime": "2016-01-29T00:01:49.126468Z",
  "id": "22e65c1f-909a-42b5-c0d2-075f30e27887-0bfdc7a8-6a16-c33e-7de9-a60a28ae533b-15475553-dbc1-8879-5079-23b1edd25bab",
  "ipAddress": "176.10.104.240",
  "isAtypicalLocation": true,
  "location": "Bern, CH",
  "previousIPAddress": "95.31.18.119",
  "previousLocation": "Moskva, Russia, RU",
  "previousSigninDateTime": "2016-01-29T00:00:55.3859274Z",
  "riskEventDateTime": "2016-01-29T00:00:56.2255665Z",
  "riskEventStatus": "remediated",
  "riskLevel": "medium",
  "riskType": "ImpossibleTravelRiskEvent",
  "userAgent": "Firefox 42.0.0.1",
  "userDisplayName": "Jon Doe",
  "userId": "0bfdc7a8-6a16-c33e-7de9-a60a28ae533b",
  "userPrincipalName": "john@contoso.com"
}

One more time, being able to write a monitoring tool that can poll these APIs and provide active monitoring can be really helpful to prevent identity risks and security threats.

Wrap up

In this article you saw how you can consume – from a developer perspective – some of the REST APIs provided by Microsoft 365 and Microsoft Office 365 in order to leverage the insights and signals from the Microsoft Intelligent Security Graph. There are many more APIs available, but the goal of this article was to give you a light preview of the potentials that you can realize using the cloud offering of Microsoft and the potentials of the Microsoft Intelligent Security Graph, in particular thinking about how to develop solutions that can help you manage and prevent the security risks from a GDPR requirements perspective.

Author:
Paolo Pialorsi – @PaoloPia – Senior Consultant – PiaSys.com