Documenting with PowerShell: Office 365 Secure Score PowerShell module

A while back I wrote a blog about the Secure Score and how to increase it. After that blog I got a lot more questions about documenting Secure Score with the Secure Application model.

To make handling the Secure Score easier, I’ve decided to make a PowerShell Module for this. The main reason for the module is to ease the complexity of changing the Secure Score settings over a lot of tenants. It’s a lot of small tweaks and settings. The module also tells you exactly what it’s going to do if you do not use the -confirmed switch, so you can check if you really wanna go on or not.

To keep in line with my other blogs, I’ll give some cool examples. First off we’ll document the Secure score both in HTML files and IT-Glue. I’ll blog about the remediation part later in the week, so I don’t overload everyone with information. 🙂

I do have to have a little disclaimer; the module is still a little rough around the edges. It’s a beta and I’m actively working on it. 🙂

To use the module, your Secure Application Model needs some extra permissions:

  • Go to the Azure Portal.
  • Click on Azure Active Directory, now click on “App Registrations”.
  • Find your Secure App Model application. You can search based on the ApplicationID.
  • Go to “API Permissions” and click Add a permission.
  • Choose “Microsoft Graph” and “Application permission”.
  • Search for “Security” and click on “SecurityEvents.Read.All”. Click on add permission.
  • Search for “Security” and click on “and SecurityEvents.ReadWrite.All”. Click on add permission.
  • Do the same for “Delegate Permissions”.
  • Finally, click on “Grant Admin Consent for Company Name.

HTML version

######### Secrets #########
$ApplicationId = 'AppID'
$ApplicationSecret = 'AppSecret'
$TenantID = 'TenantID'
$RefreshToken = 'LongRefreshToken'
$ExchangeRefreshToken = 'LongExchangeToken'
$UPN = "UPN-Used-To-Generate-Tokens"
######### Secrets #########
install-module SecureScore
install-module PsWriteHTML
$Scores = get-securescore -AllTenants -upn $upn -ApplicationSecret $ApplicationSecret -ApplicationId $ApplicationId -RefreshToken $RefreshToken

foreach ($Score in $scores) {
    New-HTML {
        New-HTMLSection -HeaderText 'Scores compared'{
            New-HTMLTable -DataTable $Score.scores.averageComparativeScores
        }
        New-HTMLSection -HeaderText "Score: $($score.Scores.currentScore) of $($score.Scores.maxScore)"  {
            New-HTMLTable -DataTable $Score.Scores.controlScores
        }
    } -FilePath "C:\temp\$($Score.TenantName) .html" -Online 
} 

And that’s it for the HTML version, lets move on to IT-Glue next.

IT-Glue version

The IT-Glue version creates the flexible asset for you, uploads the Secure Score for each client. It also looks-up all domains for the client so it can find the right client ID within IT-Glue.

######### Secrets #########
$ApplicationId = 'AppID'
$ApplicationSecret = 'AppSecret'
$TenantID = 'TenantID'
$RefreshToken = 'LongRefreshToken'
$ExchangeRefreshToken = 'LongExchangeToken'
$UPN = "UPN-Used-To-Generate-Tokens"
######### Secrets #########

########################## IT-Glue ############################
$APIKEy = "ITGAPIKEY"
$APIEndpoint = "https://api.eu.itglue.com"
$FlexAssetName = "O365 SecureScore v1"
$Description = "Secure Score v1."
########################## IT-Glue ############################
  
#Grabbing ITGlue Module and installing.
If (Get-Module -ListAvailable -Name "ITGlueAPI") { 
    Import-module ITGlueAPI 
}
Else { 
    Install-Module ITGlueAPI -Force
    Import-Module ITGlueAPI
}
#Settings IT-Glue logon information
Add-ITGlueBaseURI -base_uri $APIEndpoint
Add-ITGlueAPIKey $APIKEy
 

install-module SecureScore
install-module PsWriteHTML


write-host "Checking if Flexible Asset exists in IT-Glue." -foregroundColor green
$FilterID = (Get-ITGlueFlexibleAssetTypes -filter_name $FlexAssetName).data
if (!$FilterID) { 
    write-host "Does not exist, creating new." -foregroundColor green
    $NewFlexAssetData = 
    @{
        type          = 'flexible-asset-types'
        attributes    = @{
            name        = $FlexAssetName
            icon        = 'sitemap'
            description = $description
        }
        relationships = @{
            "flexible-asset-fields" = @{
                data = @(
                    @{
                        type       = "flexible_asset_fields"
                        attributes = @{
                            order           = 1
                            name            = "Default Domain Name"
                            kind            = "Text"
                            required        = $true
                            "show-in-list"  = $true
                            "use-for-title" = $true
                        }
                    },
                    @{
                        type       = "flexible_asset_fields"
                        attributes = @{
                            order          = 2
                            name           = "TenantID"
                            kind           = "Text"
                            required       = $false
                            "show-in-list" = $false
                        }
                    },
                    @{
                        type       = "flexible_asset_fields"
                        attributes = @{
                            order          = 3
                            name           = "Current Score"
                            kind           = "Text"
                            required       = $false
                            "show-in-list" = $false
                        }
                    },
                    @{
                        type       = "flexible_asset_fields"
                        attributes = @{
                            order          = 4
                            name           = "Secure Score Comparetives"
                            kind           = "Textbox"
                            required       = $false
                            "show-in-list" = $false
                        }
                    },
                    @{
                        type       = "flexible_asset_fields"
                        attributes = @{
                            order          = 5
                            name           = "Secure Score Settings"
                            kind           = "Textbox"
                            required       = $false
                            "show-in-list" = $false
                        }
                    }
                )
            }
        }
    }
    New-ITGlueFlexibleAssetTypes -Data $NewFlexAssetData
    $FilterID = (Get-ITGlueFlexibleAssetTypes -filter_name $FlexAssetName).data
}
 
write-host "Getting IT-Glue contact list" -ForegroundColor Green
$i = 0
$AllITGlueContacts = do {
    $Contacts = (Get-ITGlueContacts -page_size 1000 -page_number $i).data.attributes
    $i++
    $Contacts
    Write-Host "Retrieved $($Contacts.count) Contacts" -ForegroundColor Yellow
}while ($Contacts.count % 1000 -eq 0 -and $Contacts.count -ne 0) 
  
write-host "Generating unique ID List" -ForegroundColor Green

$DomainList = foreach ($Contact in $AllITGlueContacts) {
    $ITGDomain = ($contact.'contact-emails'.value -split "@")[1]
    [PSCustomObject]@{
        Domain   = $ITGDomain
        OrgID    = $Contact.'organization-id'
        Combined = "$($ITGDomain)$($Contact.'organization-id')"
    }
} 

$Scores = get-securescore -AllTenants -upn $upn -ApplicationSecret $ApplicationSecret -ApplicationId $ApplicationId -RefreshToken $RefreshToken

foreach ($Score in $scores) {
    $FlexAssetBody = 
    @{
        type       = "flexible-assets"
        attributes = @{
            traits = @{
                "default-domain-name"       = $score.TenantName
                "tenantid"                  = $score.TenantID
                "current-score"             = "$($score.Scores.currentScore) of $($score.Scores.maxScore)"
                "secure-score-comparetives" = ($score.Scores.averageComparativeScores | convertto-html -Fragment | out-string) -replace "<th>", "<th style=`"background-color:#4CAF50`">"
                "secure-score-settings"     = ($score.Scores.controlScores | convertto-html -Fragment | out-string) -replace "<th>", "<th style=`"background-color:#4CAF50`">"
            }
        }
    }
      
    write-output "             Finding $($score.TenantName) in IT-Glue"

    $Domains = (Get-MsolDomain -TenantId $Score.TenantID).name
    $ORGId = foreach ($Domain in $Domains) {
        ($domainList | Where-Object { $_.domain -eq $Domain }).'OrgID' | Select-Object -Unique
    }
    write-output "             Uploading Secure Score for $($score.TenantName) into IT-Glue"
    foreach ($org in $orgID) {
        $ExistingFlexAsset = (Get-ITGlueFlexibleAssets -filter_flexible_asset_type_id $FilterID.id -filter_organization_id $org).data | Where-Object { $_.attributes.traits.tenantid -eq $score.TenantID }
        #If the Asset does not exist, we edit the body to be in the form of a new asset, if not, we just upload.
        if (!$ExistingFlexAsset) {
            if ($FlexAssetBody.attributes.'organization-id') {
                $FlexAssetBody.attributes.'organization-id' = $org
            }
            else { 
                $FlexAssetBody.attributes.add('organization-id', $org)
                $FlexAssetBody.attributes.add('flexible-asset-type-id', $FilterID.id)
            }
            write-output "                      Creating new secure score for $($score.TenantName) into IT-Glue organisation $org"
            New-ITGlueFlexibleAssets -data $FlexAssetBody
  
        }
        else {
            write-output "                      Updating secure score $($score.TenantName) into IT-Glue organisation $org"
            $ExistingFlexAsset = $ExistingFlexAsset | select-object -Last 1
            Set-ITGlueFlexibleAssets -id $ExistingFlexAsset.id  -data $FlexAssetBody
        }
  
    }
} 

And that’s it! Somewhere this week I’ll also be talking about using the SecureScore module to apply the suggested remediation. As I said, those are still a little rough around the edges.

As always, Happy PowerShelling!

8 thoughts on “Documenting with PowerShell: Office 365 Secure Score PowerShell module

  1. rwllr

    Thanks Kelvin for another great post!

    A note for others here, you’ll need SecurityEvents.Read.All and SecurityEvents.ReadWrite.All graph permissions to get the Secure Score.
    Also there’s a typo in the ITGlue script. This line should be
    $Domains = (Get-MsolDomain -TenantId $Score.TenantID).name

    Reply
  2. Yisroel Wilner

    Very nice post! Definitly going to be taking advantage of it 🙂 I really appreciate the quantity and quality of your scripts.

    On line 128, I would add the line -ErrorAction Continue, otherwise, if there is an old customer in there who have removed the Delegated Access Permissions, they will cause the command will fail for all the tenants.

    Reply
  3. Pingback: Automating with PowerShell: Increasing the O365 Secure Score - CyberDrain

  4. Noah

    Hey Kelvin, thanks for another quality post! Struggling here for some reason; keep getting the following error when I try to run the line with ‘get-securescore’ in it:

    New-PartnerAccessToken : A configuration issue is preventing authentication – check the error message from the server
    for details.You can modify the configuration in the application registration portal. See
    https://aka.ms/msal-net-invalid-client for details. Original exception: AADSTS7000215: Invalid client secret is
    provided.

    I made sure to grant the extra API permissions for my SAM in Azure AD. And I’ve used this same SAM app for other things that work properly (i.e. connecting to a customer’s Exchange Online PowerShell). Any thoughts?

    Reply
    1. Kelvin Tegelaar Post author

      Thanks Noah! You most likely are copy and pasting the information from previous blogs; there’s a tiny change. In this version you do not pass the Application Secret as a secure string. so you’ll need to remove the ” | ConvertTo-SecureString -Force -AsPlainText” part. 🙂

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

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