How to create a Microsoft 365 security report in Word

# Install once, if the modules are not already installed.
$modules = 'Microsoft.Graph.Authentication', 'Microsoft.Graph.Security',
    'Microsoft.Graph.Reports', 'Microsoft.Graph.Identity.DirectoryManagement'
Install-Module $modules -Scope CurrentUser

$ErrorActionPreference = 'Stop'

# Word's built-in styles are numbers: -63 is Title, -2 is Heading 1 and -1 is Normal.
$styleTitle = -63
$styleHeading = -2
$styleNormal = -1

function Add-Paragraph($Selection, [string]$Text, [int]$Style) {
    $Selection.Style = $Style
    $Selection.TypeText($Text)
    $Selection.TypeParagraph()
}

# Writes objects as a table with a bold header row, then moves to the end of the document.
function Add-Table($Doc, $Selection, $Objects, [string[]]$Columns) {
    $table = $Doc.Tables.Add($Selection.Range, $Objects.Count + 1, $Columns.Count)
    $table.Borders.Enable = $true
    for ($c = 0; $c -lt $Columns.Count; $c++) {
        $table.Cell(1, $c + 1).Range.Text = $Columns[$c]
    }
    for ($r = 0; $r -lt $Objects.Count; $r++) {
        for ($c = 0; $c -lt $Columns.Count; $c++) {
            $table.Cell($r + 2, $c + 1).Range.Text = [string]$Objects[$r].($Columns[$c])
        }
    }
    $table.Rows.Item(1).Range.Font.Bold = 1
    $null = $Selection.EndKey(6)
}

$scopes = 'SecurityEvents.Read.All', 'AuditLog.Read.All', 'LicenseAssignment.Read.All'
Connect-MgGraph -Scopes $scopes -NoWelcome
$word = $null
$doc = $null
try {
    # Read the figures from Microsoft Graph.
    $score = Get-MgSecuritySecureScore -Top 1
    $members = @(Get-MgReportAuthenticationMethodUserRegistrationDetail -All |
        Where-Object { $_.UserType -eq 'member' })
    $skus = @(Get-MgSubscribedSku -All | Where-Object { $_.AppliesTo -eq 'User' } |
        Sort-Object SkuPartNumber)

    $scoreText = 'Microsoft has not worked out a Secure Score for this tenant yet.'
    $worked = 'not available'
    if ($score -and $score.MaxScore -gt 0) {
        $percent = [math]::Round(100 * $score.CurrentScore / $score.MaxScore, 1)
        $scoreText = "$($score.CurrentScore) of $($score.MaxScore) ($percent%)"
        $worked = $score.CreatedDateTime.ToUniversalTime().ToString('d MMM yyyy') + ' UTC'
    }

    $mfaText = 'No registration details were returned.'
    $adminsWithout = 0
    if ($members.Count -gt 0) {
        $registered = @($members | Where-Object { $_.IsMfaRegistered }).Count
        $share = [math]::Round(100 * $registered / $members.Count, 1)
        $mfaText = "$registered of $($members.Count) enabled members ($share%)"
        $open = @($members | Where-Object { $_.IsAdmin -and -not $_.IsMfaRegistered })
        $adminsWithout = $open.Count
    }

    $facts = @(
        [pscustomobject]@{ Figure = 'Secure Score'; Value = $scoreText },
        [pscustomobject]@{ Figure = 'Registered for MFA'; Value = $mfaText },
        [pscustomobject]@{ Figure = 'Administrators with no MFA method'; Value = $adminsWithout }
    )
    $licences = @(foreach ($sku in $skus) {
        $bought = $sku.PrepaidUnits.Enabled
        [pscustomobject]@{
            Subscription = $sku.SkuPartNumber
            Bought       = $bought
            Assigned     = $sku.ConsumedUnits
            Unassigned   = $bought - $sku.ConsumedUnits
        }
    })

    # Write them into a new Word document and save it.
    $today = Get-Date -Format 'd MMMM yyyy'
    $path = Join-Path $PWD.Path 'security-report.docx'
    $word = New-Object -ComObject Word.Application
    $doc = $word.Documents.Add()
    $selection = $word.Selection
    Add-Paragraph $selection 'Microsoft 365 security report' $styleTitle
    Add-Paragraph $selection "Figures read from Microsoft Graph on $today." $styleNormal
    Add-Paragraph $selection 'Headline figures' $styleHeading
    Add-Table $doc $selection $facts 'Figure', 'Value'
    Add-Paragraph $selection "Secure Score was worked out on $worked." $styleNormal
    if ($licences.Count -gt 0) {
        Add-Paragraph $selection 'Licences' $styleHeading
        Add-Table $doc $selection $licences 'Subscription', 'Bought', 'Assigned', 'Unassigned'
    }
    $doc.SaveAs2($path, 12)   # 12 is wdFormatXMLDocument, the .docx format.
    Write-Output "Saved $path"
} finally {
    Disconnect-MgGraph | Out-Null
    if ($doc) { $doc.Close(0) }
    if ($word) { $word.Quit() }
}