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!