How to Get Azure Security Center Secure Score Via REST APIs

During Microsoft Ignite in November 2021, Azure Security Center and Azure Defender are now called Microsoft Defender for Cloud. They’ve also renamed Azure Defender plans to Microsoft Defender plans. For example, Azure Defender for Storage is now Microsoft Defender for Storage.

In this article, we will show you how to get access to the Azure Security Center (Defender for Cloud) Secure Score via the REST APIs so you can automate and build upon it.

Introduction

Microsoft Defender for Cloud has two main goals: the first one is to help you understand your current security situation, and the second one is to help you efficiently and effectively improve your security posture. The central aspect of Azure Security Center that enables you to achieve those goals is the Secure Score.

As part of the enhanced secure score model, recommendations have been grouped into security controls, which are logical groups of security recommendations. The security controls allow you to focus on all recommendations that are relevant to a specific scenario, for example, Secure management ports.

Each security control shown in the figure below represents a security risk you should mitigate. You need to start by addressing each control’s recommendations, focusing on the controls worth the most points. To get the max score, you need to fix all recommendations for all resources in each control. To understand each security control in more detail, please refer to the following guide from Microsoft.

One of the most frequent questions that were asked by the security team is, how can I track over time the improvement of Secure Score? can we extract that number via REST API for example?

During the Microsoft Build 2020 event, the Microsoft Security Team announced that Azure Secure Score API is now available to customers. You can bring even more innovation to using Azure Secure Score programmatically instead of relying only on the Secure Score UI dashboard. Kudos to the team behind this great innovation.

Prerequisites

To follow this article, you need to have the following:

1) Azure subscription. If you don’t have an Azure subscription, you can create a free one here.

2) Azure Security Center Free tier or Azure Defender enabled (Standard tier). The free tier is enough to get a Secure Score via the REST API. So why not use the free tier for all your Azure resources to get continuous assessment and security recommendations, as well as Azure Secure Score, to strengthen your security posture?

3) Calling Azure REST APIs with Postman. Please follow the step-by-step guide here to get started with Azure REST APIs and Postman. You need to create an Azure Active Directory Service Principal and use it in Postman to generate a Bearer Token and then call the Azure REST APIs. You can also use curl to call Azure Secure Score REST API.

4) To use the Azure Secure Score API, you must provide a valid “Authorization Header” otherwise the call will fail. Since I will use Postman as described in this guide, I will set the Authorization Type as “Bearer Token“, and the Token value as {{bearerToken}} as shown in the figure below. But before doing this, you need first to run the Get AAD Token as part of Azure REST in Postman to get the “Bearer Token“. Please note that the “Authorization Header” must be set for every API call you want to execute. The good news is, that you can Save those values and create different Add Request for each call in “Postman”.

To get your Azure Secure Score, you need to do this individually at the subscription {{subscriptionId}} level, if you have multiple Azure subscriptions, you can add them all in “Postman”. To do so, please update the MANAGE ENVIRONMENTS variable by adding “subscriptionId01“, “subscriptionId02“, etc. with their corresponding values as shown in the below figure:

At the time of this writing, Management Groups are NOT supported yet for the Azure Secure Score API, I hope this will come in the future. Please also make sure that the Azure AD Service Principal that you created in your Tenant to perform REST APIs requests, has a Contributor role on each subscription that you want to get Azure Secure Score for.

In the following example, we will perform the API call requests on the subscription level.

Security Center – Secure Score API

Assuming all the prerequisites are in place, let us get started.

In this section, I will query different Security Center | Secure Score APIs. At the time of this writing, Azure Security Center APIs are still in public preview and things might change in the future, however, the logic will remain the same.

Secure Scores per subscription

Now before I get started, I want to get the Secure Score for all my subscriptions from Security Center | Secure Score dashboard, so I can compare it when I perform the API calls.

In this call, you get all secure scores per individual subscription. The syntax is the following:

#GET
https://management.azure.com/subscriptions/{{subscriptionId01}}/providers/Microsoft.Security/secureScores?api-version=2020-01-01-preview

Please make sure to replace {{subscriptionId01}} with your subscription Id value. As mentioned previously, if you are using Postman to query the API, then you can add and save all your subscription Ids under the Management Environments.

Here is the output of my first subscription “N01” | (Max = 55 / Current = 12). This exactly reflects the Secure Score number in the Security Center dashboard.

Here is the output of my second subscription “N02” | (Max = 46 and Current = 20). The API results and the Azure Portal information are identical.

Secure Score for each control

In this call, you get a secure score for all (built-in) security Controls per individual subscription. Here is my secure score for each security control in the Azure Portal.

The syntax is the following:

#GET
https://management.azure.com/subscriptions/{{subscriptionId01}}/providers/Microsoft.Security/secureScores/ascScore/securescorecontrols?api-version=2020-01-01-preview

Here is the output of my first subscription. You will see the “max” and “current” scores, as well as the Healthy resource and the Unhealthy resource count. The responses are in JSON format, I truncated the body here because it is too long.

The Enable MFA and Encrypt data in transit security control shown in the screenshot below are identical to the Azure Portal information.

Secure Score security controls and recommendations

In this call, you get a secure score for each security control data and mapping to recommendations per individual subscription.

The syntax is the following:

#GET
https://management.azure.com/subscriptions/{{subscriptionId01}}/providers/Microsoft.Security/secureScores/ascScore/securescorecontrols?api-version=2020-01-01-preview&$expand=definition

The output will be a list of all calculated controls for each security control and assessment Definition as shown in the screenshot below. The list will also include the “max” and “current” scores, as well as the Healthy resource and the Unhealthy resource count.

Security Controls definitions

In this call, you get all Security Center (built-in) Security Control definitions by calling this API:

#GET
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Security/secureScoreControlDefinitions?api-version=2020-01-01-preview

The output will show you a list of all control definitions without any calculations (you can see only the max score).

You can also get the full security assessments details by calling the following API:

#Get
https://management.azure.com//subscriptions/{{subscriptionId}}/providers/Microsoft.Security/assessments?api-version=2020-01-01

That’s it there you have it!

Summary

This article described different ways how to get Microsoft Defender for Cloud (formerly Azure Security Center) Secure Score using the Azure REST APIs. Leveraging the Azure Secure Score API is a great way to get your Azure security posture programmatically so you can automate and build custom dashboards using PowerBi for example, and then tailor them based on your organization’s needs. This could be very useful to share these dashboards with your security officer (CISO), top management, or your security team without giving them access to the Azure Portal.

Another useful scenario of using Secure Score API is, you could leverage Logic App and schedule it to run every day to extract Secure Score number via then REST API, and then store that number in Log Analytics, for example, then by the end of the month, you have all days collected so you can create your chart to see how you are progressing, etc.

How are you going to use Azure Secure Score API in your environment? You are welcome to share your thoughts in the comment section below.

I hope that the security team will also add management group support to secure score API, so it would be more efficient to query at the management group level to get the secure score instead of an individual subscription.

Additional resources I highly encourage you to check:

• Learn more about the enhanced Secure Score in Azure Security Center.
• Learn more about how to integrate Azure Security Center with Azure Monitor Alerts.
• Learn more about how to integrate Azure Security Center with Azure Sentinel cloud-native (SIEM).
• Learn more about Azure Security Center, check the official documentation from Microsoft.
• Learn how to export Azure Security Center Alerts and Recommendations.
• Workflow automation in Azure Security Center to automate your security operations.

__
Thank you for reading my blog.

If you have any questions or feedback, please leave a comment.

-Charbel Nemnom-