schedules/ca-notifications.ps1
|
#Requires -Version 7.4 # Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. <# .SYNOPSIS Notification functions for the scheduling layer: Teams card and email. Dot-sourced by ca-snapshot-cycle.ps1. .DESCRIPTION These are the only outbound sends in the product and they live outside the module on purpose: the module is read-only against the tenant, and sending mail through Graph needs Mail.Send, a write permission the customer opts into. Everything here goes to the customer's own services (their Teams, their mailbox, their SMTP relay). #> function Get-CaChangeNotificationContent { <# .SYNOPSIS Subject and HTML body for a change notification, from a Compare-PostureCaSnapshot result. #> [CmdletBinding()] [OutputType([hashtable])] param( [Parameter(Mandatory)] [object] $Comparison, [Parameter(Mandatory)] [string] $BeforeName, [Parameter(Mandatory)] [string] $AfterName, [string] $TenantLabel ) $ErrorActionPreference = 'Stop' $h = { param($t) [System.Net.WebUtility]::HtmlEncode([string]$t) } $count = [int]$Comparison.RiskRelevantCount $label = if ($TenantLabel) { " ($TenantLabel)" } else { '' } $subject = if ($count -gt 0) { "Conditional Access: $count risk-relevant change(s)$label" } else { "Conditional Access: no risk-relevant changes$label" } $rows = foreach ($r in @($Comparison.Diff.risk)) { "<tr><td style=`"padding:4px 8px;color:#cf222e;font-weight:600`">$(& $h $r.rule)</td><td style=`"padding:4px 8px`">$(& $h $r.subject)</td><td style=`"padding:4px 8px`">$(& $h $r.detail)</td></tr>" } $c = $Comparison.Counts $body = @" <html><body style="font-family:Helvetica,Arial,sans-serif;font-size:14px;color:#1b1f23"> <h2 style="color:#1F3A5F">$(& $h $subject)</h2> <p>Between <strong>$(& $h $BeforeName)</strong> and <strong>$(& $h $AfterName)</strong>. Policies added $($c.added), removed $($c.removed), renamed $($c.renamed), state changed $($c.stateChanged), modified $($c.modified); locations $($c.locations), strengths $($c.strengths), groups drifted $($c.scope).</p> $(if ($count -gt 0) { "<table style=`"border-collapse:collapse;border:1px solid #d9dee3`"><thead><tr><th style=`"text-align:left;padding:4px 8px`">Rule</th><th style=`"text-align:left;padding:4px 8px`">Subject</th><th style=`"text-align:left;padding:4px 8px`">Detail</th></tr></thead><tbody>$($rows -join '')</tbody></table>" } else { '<p>No risk-relevant changes.</p>' }) <p>The full change report is attached (ca-changes.html) and in the snapshot folder.</p> <p style="color:#5c6670;font-size:12px">Sent by the TenantKeep Posture schedule in your environment. Nothing was sent anywhere else.</p> </body></html> "@ return @{ Subject = $subject; Body = $body } } function Send-CaTeamsCard { <# .SYNOPSIS Posts the risk-relevant changes to a Teams Workflows webhook as an Adaptive Card. #> [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory)] [string] $WebhookUrl, [Parameter(Mandatory)] [object] $Comparison, [Parameter(Mandatory)] [string] $BeforeName, [Parameter(Mandatory)] [string] $AfterName ) $ErrorActionPreference = 'Stop' $facts = @($Comparison.Diff.risk | Select-Object -First 15 | ForEach-Object { @{ title = $_.rule; value = "$($_.subject): $($_.detail)" } }) $card = @{ type = 'message' attachments = @(@{ contentType = 'application/vnd.microsoft.card.adaptive' content = @{ '$schema' = 'http://adaptivecards.io/schemas/adaptive-card.json' type = 'AdaptiveCard' version = '1.4' body = @( @{ type = 'TextBlock'; size = 'Large'; weight = 'Bolder'; text = "Conditional Access: $($Comparison.RiskRelevantCount) risk-relevant change(s)" } @{ type = 'TextBlock'; wrap = $true; text = "Between $BeforeName and $AfterName. Report: ca-changes.html in the snapshot folder." } @{ type = 'FactSet'; facts = $facts } ) } }) } if ($PSCmdlet.ShouldProcess($WebhookUrl, 'Post Teams card')) { # (verify) Workflows webhook accepts this shape; the older Office 365 connector webhooks are retired. $null = Invoke-RestMethod -Method Post -Uri $WebhookUrl -ContentType 'application/json' -Body ($card | ConvertTo-Json -Depth 12) } } function Send-CaChangeEmail { <# .SYNOPSIS Emails the change notification with ca-changes.html attached, through Graph sendMail or an SMTP relay. .DESCRIPTION Graph: POST /users/{From}/sendMail as the signed-in identity. Needs Mail.Send, which the customer grants knowingly; scope it to the sender mailbox with an Exchange application access policy. saveToSentItems is false so the sender mailbox does not fill up. Smtp: System.Net.Mail over STARTTLS with the given credential. No Graph permission involved. -PassThru returns the built message without sending (used by tests and for a dry run). #> [CmdletBinding(SupportsShouldProcess)] [OutputType([hashtable])] param( [Parameter(Mandatory)] [string[]] $To, [Parameter(Mandatory)] [string] $From, [Parameter(Mandatory)] [string] $Subject, [Parameter(Mandatory)] [string] $HtmlBody, [string[]] $AttachmentPath = @(), [ValidateSet('Graph', 'Smtp')] [string] $Method = 'Graph', [string] $SmtpServer, [int] $SmtpPort = 587, [pscredential] $SmtpCredential, [bool] $SmtpUseTls = $true, [switch] $PassThru ) $ErrorActionPreference = 'Stop' $attachments = foreach ($p in $AttachmentPath) { if (-not (Test-Path -LiteralPath $p)) { throw "Attachment not found: $p" } @{ name = (Split-Path $p -Leaf); contentType = $(if ($p -like '*.html') { 'text/html' } else { 'application/octet-stream' }); bytes = [System.IO.File]::ReadAllBytes($p) } } $message = @{ To = @($To); From = $From; Subject = $Subject; HtmlBody = $HtmlBody; Attachments = @($attachments); Method = $Method } if ($PassThru) { return $message } switch ($Method) { 'Graph' { $ctx = Get-MgContext if (-not $ctx) { throw 'No Graph session; connect before sending mail.' } if (@($ctx.Scopes) -notcontains 'Mail.Send' -and @($ctx.Scopes) -notcontains 'Mail.Send.Shared') { throw "Email through Graph needs the Mail.Send permission on the identity (current scopes: $(@($ctx.Scopes) -join ', ')). Grant it with admin consent, restrict it to the sender mailbox with an Exchange application access policy, or use -EmailMethod Smtp." } $payload = @{ message = @{ subject = $Subject body = @{ contentType = 'HTML'; content = $HtmlBody } toRecipients = @($To | ForEach-Object { @{ emailAddress = @{ address = $_ } } }) attachments = @($attachments | ForEach-Object { @{ '@odata.type' = '#microsoft.graph.fileAttachment'; name = $_.name; contentType = $_.contentType; contentBytes = [Convert]::ToBase64String($_.bytes) } }) } saveToSentItems = $false } if ($PSCmdlet.ShouldProcess("$From -> $($To -join ', ')", 'Send mail through Graph')) { # The one Graph write in the product, outside the module, opt-in by granting Mail.Send. $null = Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users/$([uri]::EscapeDataString($From))/sendMail" -Body ($payload | ConvertTo-Json -Depth 10 -Compress) -ContentType 'application/json' } } 'Smtp' { if (-not $SmtpServer) { throw '-SmtpServer is required for -EmailMethod Smtp.' } $mail = [System.Net.Mail.MailMessage]::new() $mail.From = [System.Net.Mail.MailAddress]::new($From) foreach ($t in $To) { $mail.To.Add($t) } $mail.Subject = $Subject $mail.Body = $HtmlBody $mail.IsBodyHtml = $true foreach ($a in $attachments) { $stream = [System.IO.MemoryStream]::new($a.bytes) $mail.Attachments.Add([System.Net.Mail.Attachment]::new($stream, $a.name, $a.contentType)) } $client = [System.Net.Mail.SmtpClient]::new($SmtpServer, $SmtpPort) $client.EnableSsl = $SmtpUseTls if ($SmtpCredential) { $client.Credentials = $SmtpCredential.GetNetworkCredential() } try { if ($PSCmdlet.ShouldProcess("$SmtpServer`:$SmtpPort", "Send mail from $From to $($To -join ', ')")) { $client.Send($mail) } } finally { $mail.Dispose(); $client.Dispose() } } } } |