How To Get Azure Security Center Secure Score Via REST APIs

7 min read

Introduction

Azure Security Center 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 first by addressing the recommendations in each control, 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?

Until last week and during the Microsoft Build 2020 event, the Microsoft Security Team announced that Azure Secure Score API is now available to customers, so you can bring even more innovation to use Azure Secure Score programmatically instead of relying only on Secure Score UI dashboard. Kudos to the team behind this great innovation.

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

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 Standard tier enabled. The free tier is enough to get Secure Score via the REST API. So why not using 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, 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, I will perform the API call requests on the subscription level.

Security Center – Secure Score API

Assuming all the prerequisites are in the 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 subscriptions 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:

GEThttps://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” score, 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” score, 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:

GEThttps://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).

That’s it there you have it!

Summary

This article described different ways on how to get 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 in a programmatic way so you can automate and build custom dashboards using PowerBI for example, and then tailor it 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:

__
Thank you for reading my blog.

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

-Charbel Nemnom-

About Charbel Nemnom 552 Articles
Charbel Nemnom is a Cloud Architect, ICT Security Expert, Microsoft Most Valuable Professional (MVP), and Microsoft Certified Trainer (MCT), totally fan of the latest's IT platform solutions, accomplished hands-on technical professional with over 17 years of broad IT Infrastructure experience serving on and guiding technical teams to optimize the performance of mission-critical enterprise systems. Excellent communicator is adept at identifying business needs and bridging the gap between functional groups and technology to foster targeted and innovative IT project development. Well respected by peers through demonstrating passion for technology and performance improvement. Extensive practical knowledge of complex systems builds, network design, business continuity, and cloud security.

Be the first to comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.