The Security Graph API was released into GA yesterday at Microsoft Ignite, and is a subset of the Graph API which is collecting information from many different security products in the Microsoft Cloud (and now part of EMS package) Now if you are unfamliar with the Graph API you can take a closer look at what kind of data set it exposes here –> https://developer.microsoft.com/en-us/graph/graph-explorer there you can see it exposes information such as Azure AD, Intune, Office365 and such.
Now the Security Graph API collects information from the following source:
Azure Security Center
Azure Active Directory Identity Protection
Azure Information Protection
Microsoft Cloud Application Security
Windows Defender Advanced Threat Protection
Microsoft Intune (private preview)
Office 365 (coming soon)
Azure Advanced Threat Protection (coming soon)
Partner solutions
But it should be noted that the Security Graph API is limited as of now to ONLY getting aggregated alerts and updating alerts across the different services and also getting Security Score information as well.
(I’m not going to show how you create an Azure AD application that you use for that, or how to generate an token for your application, you can read more about that here –> https://lazyadmin.nl/it/using-microsoft-graph-api-with-powershell/
But just quering the API for alerts is pretty simple using REST API: (You can view the schema here –>: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/alert_list ) so an example would be just viewing the alerts.
Sending an HTTP GET to –> https://graph.microsoft.com/beta/security/alerts?$top=1 (Only the beta URL worked for me) You are going to get this payload back. This is basically an alert which I triggered from Cloud App Security, which you can see in the provider name.
{
“@odata.context”: “https://graph.microsoft.com/beta/$metadata#Security/alerts”,
“@odata.nextLink”: “https://graph.microsoft.com/beta/security/alerts?$top=1&$skip=1”,
“value”: [
{
“azureSubscriptionId”: “”,
“riskScore”: “”,
“tags”: [],
“id”: “992431C8-A8CC-3B88-A5A2-37F3A1930BC1”,
“azureTenantId”: “62099e6a-9982-44e9-9ab8-7ca4e88cd71f”,
“activityGroupName”: null,
“assignedTo”: “”,
“category”: “MCAS_ALERT_CABINET_EVENT_MATCH_AUDIT”,
“closedDateTime”: null,
“comments”: [],
“confidence”: 0,
“createdDateTime”: “2018-09-27T16:24:58.363Z”,
“description”: “Activity policy ‘WARNING’ was triggered by ‘[email protected] ([email protected])'”,
“detectionIds”: [],
“eventDateTime”: “2018-09-27T16:24:58.021Z”,
“feedback”: null,
“lastModifiedDateTime”: “2018-09-27T16:24:59.3930894Z”,
“recommendedActions”: [],
“severity”: “low”,
“sourceMaterials”: [],
“status”: “newAlert”,
“title”: “WARNING”,
“vendorInformation”: {
“provider”: “MCAS”,
“providerVersion”: “3.0”,
“subProvider”: null,
“vendor”: “Microsoft”
},
You will notice that the provider is based upon what kind of service that is actually reporting the alert. Now an issue is that we would need to monitor these alerts and because of that we would need to pull the API quite often to detect changes. Now we can also integrate Security Graph API into different SIEM tools such as Splunk and QRadar, which you can read more about here –> https://developer.microsoft.com/en-us/graph/docs/concepts/security_siemintegration
NOTE: IF you are not getting any alert information from REST I suggest yo take a look here –> https://techcommunity.microsoft.com/t5/Using-Microsoft-Graph-Security/https-graph-microsoft-com-beta-security-alerts-Not-returning-any/m-p/191898#M5
Now the interesting thing is that you can integrate with the Graph API to get updates using WebHooks on any type of activity or you can. It is not that documented as part of the docs.microsoft.com but to setup a webhook integration with the security graph API you need to build it up like this.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
“changeType”: “created,updated”,
“notificationUrl”: “http://httpresponder.com/test”,
“resource”: “security/alerts”,
“expirationDateTime”:”2018-11-20T18:23:45.9356913Z”,
“clientState”: “secretClientValue”
}
This will trigger the Graph API to send a request to the webhook that you have configured and the endpoint will need to respond with
- A 200 (OK) status code.
- The content type must be
text/plain. - The body must include the validation token provided by Microsoft Graph.
This to ensure validation of the endpoint.
Now as an added bonus, Microsoft has also open sourced an web UI which interacts with all the data from Graph API and shows it in a neat UI, you can find a link to the source on github here –> https://github.com/microsoftgraph/aspnet-security-api-sample
It should be noted however that the Graph API includes also includes policy settings for Intune and also Azure AD, so there we can configure and automatic deploy policies to Azure AD and intune, but not the other security tools in the EMS suite. In order to interact with the other security tools such as WDATP or other tools we need to work with other API interfaces, but that is coming later down in the roadmap. Just exposing the security score and the alerts was just the first part of the plan.