Today I’d like to show you in action my repo related to AAD Security Health Check,

Overall Repo description

The idea behind the AADSecurity repository is to have a master file that triggers all other scripts related to a specific configuration area. It allows us to be flexible and add/remove scripts as needed orupdate the list at any time.

AADSEcurity Repository structure

As you can see in the figure above in the root level of the repo it has 2 folders and 2 run scripts.\

  • PowerBI – this is a folder that has the PowerBI file used to visualize the results from the checks.
    There will be a dedicated article about how to run the PowerBI for visualization.
  • Scripts – here we are having scripts related to specific checks.
  • Get-AADAudit.ps1 – our master file that we are going to use in order to get reports.
  • GET-AADRawData.ps1 – file which is in use when Get-AADAudit.ps1 script is run with IncludeRAW switch it will generate JSON files as an output.

Before we start

In this article, we will use scripts available under this repo.

Scripts are run in the context of Azure AD Application to avoid user account usage and make it cleaver and secure.

Before the script run we have to register Azure AD Application by following this link: Register an application

After registering the application please follow the Readme file in the script repo to know what exact permissions should be granted to the application and how to upload the certificate.

Repo usage

Okay, so we are almost ready to run the Get-AADAudit.ps1 script.

Script with parameters

Let’s stop for a moment and describe the parameters:

  • AuditPath – path to the catalog where all output should be saved.
  • CliXMLPath – Path to XML file that stores Certificate Thumbprint used during the Azure AD Application setup. Here I’m using the Import-CLIXML / Export-CLIXML cmdlets to store critical data in a secure way.
  • SecretCLIXMLPath – Path to XML file that stores Application Secret
  • ApplicationID – ID of the application that we have created to run the repo
  • TenantID – self-explanatory
  • IncludeRAW – using this parameter allows us to get raw JSON output for areas that we are searching within the scripts.
  • Verbose – built-in the parameter into the PowerShell that allows us to troubleshoot the script.
Get-AADAudit script run

After a successful script run (without any red errors) you should get an output similar to the one above.

All CSV files generated by the scripts in my case are stored under the X:\Temp\AAD_Audit\TenantName catalog.

Each script will generate a separate catalog similar to the script name and save its CSV file with output. The CSV file structure is aligned with the PowerBI file so if you want to use this visualization please do not modify the output of the files. Also, a full transcript (*.log file) is in use so you can see what happened and when during the script run.

Output catalog structure


So this is all that I got for you today.

We have managed to register the application, assign permissions import the certificate, create two XML files and run the script.

Next on the list is to visualize it using all CSV files from the output catalog.

Stay safe and tuned for more.

Comments are closed.