PowerShell Automation and Reporting at Scale

# Folder layout:
#   IdentityBytes.EntraSec\
#     IdentityBytes.EntraSec.psd1   (manifest)
#     IdentityBytes.EntraSec.psm1   (root: loads and exports functions)
#     Public\   (exported functions, one per file)
#     Private\  (internal helpers)

$root = ".\IdentityBytes.EntraSec"
New-Item -ItemType Directory -Path "$root\Public","$root\Private" -Force | Out-Null

New-ModuleManifest -Path "$root\IdentityBytes.EntraSec.psd1" `
  -RootModule 'IdentityBytes.EntraSec.psm1' `
  -ModuleVersion '1.0.0' `
  -Author 'Identity Bytes' `
  -Description 'Entra ID security assessment and reporting toolkit' `
  -PowerShellVersion '7.4' `
  -RequiredModules @('Microsoft.Graph.Authentication','Microsoft.Graph.Users',
                     'Microsoft.Graph.Reports','Microsoft.Graph.Identity.DirectoryManagement') `
  -FunctionsToExport @('Connect-IBGraph','Get-IBIdentityBaseline','Get-IBDomainRisk',
                       'Get-IBHygieneReport','Get-IBPrivilegedReport','New-IBSecurityReport')

# IdentityBytes.EntraSec.psm1
# Dot-source every function file, then export only the public ones.
$public  = @(Get-ChildItem -Path "$PSScriptRoot\Public\*.ps1"  -ErrorAction SilentlyContinue)
$private = @(Get-ChildItem -Path "$PSScriptRoot\Private\*.ps1" -ErrorAction SilentlyContinue)

foreach ($file in @($public + $private)) {
  try { . $file.FullName }
  catch { Write-Error "Failed to import $($file.FullName): $_" }
}

Export-ModuleMember -Function $public.BaseName

function Connect-IBGraph {
  <#
  .SYNOPSIS Connect to Microsoft Graph with the toolkit's least-privilege read scopes.
  .DESCRIPTION Supports interactive sign-in for ad hoc use and managed identity for runbooks.
  #>
  [CmdletBinding()]
  param(
    [ValidateSet('Interactive','ManagedIdentity')] [string]$Method = 'Interactive'
  )
  $scopes = @('User.Read.All','AuditLog.Read.All','Directory.Read.All',
              'RoleManagement.Read.Directory','Domain.Read.All')
  if ($Method -eq 'ManagedIdentity') { Connect-MgGraph -Identity -NoWelcome }
  else                               { Connect-MgGraph -Scopes $scopes -NoWelcome }
  Get-MgContext | Select-Object Account, TenantId
}

function Invoke-IBWithRetry {
  # Retry a scriptblock on HTTP 429 (throttling), honouring Retry-After.
  # The Graph SDK auto-retries many calls; use this around raw or bulk loops.
  param([scriptblock]$Script, [int]$MaxRetries = 5)
  $attempt = 0
  while ($true) {
    try { return & $Script }
    catch {
      $attempt++
      $status = $_.Exception.Response.StatusCode.value__
      if ($attempt -ge $MaxRetries -or $status -ne 429) { throw }
      $wait = 5
      $ra = $_.Exception.Response.Headers.RetryAfter.Delta
      if ($ra) { $wait = [int]$ra.TotalSeconds }
      Write-Verbose "Throttled. Waiting $wait s (attempt $attempt/$MaxRetries)."
      Start-Sleep -Seconds $wait
    }
  }
}

function Get-IBIdentityBaseline {
  <# .SYNOPSIS Summarise MFA, SSPR, dormancy and guests as one object. #>
  [CmdletBinding()] param([int]$DormantDays = 90)

  $reg   = Get-MgReportAuthenticationMethodUserRegistrationDetail -All
  $users = Get-MgUser -All -Property id,userType,accountEnabled,signInActivity,createdDateTime
  $cutoff = (Get-Date).AddDays(-$DormantDays)

  [pscustomobject]@{
    GeneratedUtc   = (Get-Date).ToUniversalTime().ToString('u')
    TotalUsers     = $users.Count
    MfaCapable     = ($reg | Where-Object IsMfaCapable).Count
    MfaCapablePct  = [math]::Round((($reg | Where-Object IsMfaCapable).Count / [math]::Max($users.Count,1))*100)
    SsprRegistered = ($reg | Where-Object IsSsprRegistered).Count
    Dormant        = ($users | Where-Object { $_.AccountEnabled -and $_.UserType -eq 'Member' -and
                       ($null -eq $_.SignInActivity.LastSignInDateTime -or
                        $_.SignInActivity.LastSignInDateTime -lt $cutoff) }).Count
    Guests         = ($users | Where-Object { $_.UserType -eq 'Guest' }).Count
  }
}

function Get-IBPrivilegedReport {
  <# .SYNOPSIS List active directory-role holders. #>
  [CmdletBinding()] param()
  foreach ($role in (Get-MgDirectoryRole -All)) {
    foreach ($m in (Get-MgDirectoryRoleMember -DirectoryRoleId $role.Id -All)) {
      [pscustomobject]@{
        Role       = $role.DisplayName
        MemberType = ($m.AdditionalProperties['@odata.type'] -replace '#microsoft.graph.','')
        Upn        = $m.AdditionalProperties['userPrincipalName']
      }
    }
  }
}

function New-IBSecurityReport {
  <# .SYNOPSIS Build a branded HTML posture report from all assessments. #>
  [CmdletBinding()]
  param([string]$OutputPath = ".\IB-Entra-Posture-$(Get-Date -f yyyyMMdd).html")

  $base = Get-IBIdentityBaseline
  $priv = @(Get-IBPrivilegedReport)

  $card = {
    param($label,$value) "<div class='c'><div class='v'>$value</div><div class='l'>$label</div></div>"
  }

  $html = @"
<!DOCTYPE html><html><head><meta charset='utf-8'>
<style>
 body{font-family: "Segoe UI", -apple-system, BlinkMacSystemFont, system-ui, Roboto, "Helvetica Neue", Arial, sans-serif;background:#ffffff;color:#1b2125;margin:0}
 header{background:#161616;color:#ffffff;padding:34px 26px;border-bottom:3px solid #0d8ff2}
 header .b{color:#0d8ff2;letter-spacing:.2em;font-size:12px;text-transform:uppercase}
 main{max-width:900px;margin:0 auto;padding:24px}
 .grid{display:grid;grid-template-columns:repeat(4,1fr);gap:14px}
 .c{background:#faf9f8;border:1px solid #e6ebef;border-radius:12px;padding:16px;text-align:center}
 .v{font-size:28px;font-weight:800;color:#2f78b0}.l{font-size:12px;color:#3b3a39;margin-top:4px}
 table{width:100%;border-collapse:collapse;margin-top:20px;font-size:14px}
 th,td{border:1px solid #e6ebef;padding:8px 10px;text-align:left}th{background:#faf9f8}
</style></head><body>
<header><div class='b'>Identity Bytes // Northgate Financial</div>
<h1>Entra ID Posture Report</h1><div>Generated $($base.GeneratedUtc)</div></header>
<main>
 <div class='grid'>
  $(& $card 'Total users' $base.TotalUsers)
  $(& $card 'MFA-capable %' "$($base.MfaCapablePct)%")
  $(& $card 'Dormant (90d)' $base.Dormant)
  $(& $card 'Privileged holders' $priv.Count)
 </div>
 <h2>Privileged role holders</h2>
 <table><tr><th>Role</th><th>Type</th><th>User</th></tr>
 $(($priv | ForEach-Object { "<tr><td>$($_.Role)</td><td>$($_.MemberType)</td><td>$($_.Upn)</td></tr>" }) -join "`n")
 </table>
</main></body></html>
"@

  $html | Out-File -FilePath $OutputPath -Encoding utf8
  # Also emit machine-readable exports alongside the report.
  $base | ConvertTo-Json | Out-File "$($OutputPath -replace '\.html$','.json')" -Encoding utf8
  Write-Host "Report written to $OutputPath"
}

# In an Azure Automation runbook (PowerShell 7.x), with the module imported
# into the Automation account and the managed identity granted the READ
# Graph permissions (User.Read.All, AuditLog.Read.All, Directory.Read.All,
# RoleManagement.Read.Directory, Domain.Read.All):

Import-Module IdentityBytes.EntraSec
Connect-IBGraph -Method ManagedIdentity

$report = "$env:TEMP\IB-Entra-Posture-$(Get-Date -f yyyyMMdd).html"
New-IBSecurityReport -OutputPath $report

# Deliver it: email via Graph sendMail (needs Mail.Send app permission),
# or upload to SharePoint / Azure Blob for the team to collect.
# Link a weekly schedule to this runbook in the Automation account.