Set-SIMail
Set up how SecurityInsight sends mail
Purpose
Sets up how SecurityInsight sends mail: an Office 365 shared mailbox (created if asked; Mail.Send scoped to that mailbox only through Exchange RBAC for Applications, then verified) or your own SMTP relay. Plan by default; -Apply changes.
When to run it
When mail is set up, or the sender / relay changes. For your Exchange administrator.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| exchange | Exchange Administrator (narrowest: Mail Recipient Creation + Role Management) | Exchange Online | to create the mailbox, the scope and the role assignment |
| entraRole | Privileged Role Administrator or Cloud Application Administrator | the tenant | to remove a tenant-wide Microsoft Graph Mail.Send (needs AppRoleAssignment.ReadWrite.All) |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Exchange Online | create | the shared mailbox (-CreateMailbox, on by default) | Exchange Online | SecurityInsight sends as one mailbox | remove the mailbox | |
| Exchange Online | create | service principals for SecurityInsight's identities (New-ServicePrincipal) | Exchange Online | Exchange RBAC for Applications needs them | Remove-ServicePrincipal | |
| Exchange Online | create | management scope SecurityInsight-Sender (only that mailbox) | Exchange Online | limit the send right to one mailbox | Remove-ManagementScope | |
| Exchange Online | grant | per identity: Application Mail.Send on that scope | Application Mail.Send | the scope (one mailbox) | SecurityInsight sends its mail | Remove-ManagementRoleAssignment |
| Entra application permissions | remove | a tenant-wide Microsoft Graph Mail.Send on those identities | Mail.Send | the tenant | a tenant-wide right would let them send as every mailbox | grant it again (not recommended) |
| Key Vault secret (smtp mode) | update | SI-Smtp-Password | the SecurityInsight Key Vault | the relay password never goes into configuration | restore the previous version |
What it only reads
- identities and their Graph permissions (Application.Read.All)
- mailboxes, scopes and role assignments
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -Mode | no | 'sharedMailbox' | |
| -TenantId | no | ||
| -SharedMailbox | no | sharedMailbox: the address SecurityInsight sends as. Empty = <MailboxName>@<MailDomain>, and without -MailDomain <MailboxName>@<the tenant's initial domain>. The company names the mailbox (its own naming): -MailboxName, -MailDomain and -DisplayName; the defaults are only defaults. | |
| -MailboxName | no | 'SecurityInsight' | |
| -MailDomain | no | ||
| -DisplayName | no | 'SecurityInsight' | |
| -CreateMailbox | no | $true | |
| -ScopeName | no | '' | The Exchange management scope. Empty = a scope that already filters exactly this mailbox is ADOPTED, else '<MailboxName>-Sender'. The role assignments are named '<MailboxName>-MailSend-<app id>'. |
| -IdentityObjectId | no | @() | SecurityInsight's sending identities: service principal OBJECT ids. Or resolved from -SubscriptionId + -ResourceGroup: every user-assigned identity there, and the system-assigned identity of every container app, container apps job and web app there. |
| -SubscriptionId | no | ||
| -ResourceGroup | no | ||
| -ExcludeIdentityPattern | no | '(?i)tagging|mcp' | identities in -ResourceGroup that never send mail (asset tagging, the MCP server) are left out |
| -ProbeMailbox | no | A mailbox OUTSIDE the scope, to prove the restriction. Empty = the signed-in person (when it has a mailbox). | |
| -SmtpServer | no | smtp | |
| -SmtpPort | no | 587 | |
| -SmtpUseSsl | no | ||
| -SmtpUser | no | ||
| -SmtpPassword | no | ||
| -From | no | ||
| -KeyVaultName | no | ||
| -SmtpPasswordSecretName | no | 'SI-Smtp-Password' | |
| -TestTo | no | @() | |
| -UseSignedInAccount | no | sign-in: setup's own REST sign-in (a person in Cloud Shell / the browser, or the Invardia support session) -- no az CLI | |
| -ActivateExchangeAdmin | no | an app sign-in (the Invardia Support app): activate its own Exchange Administrator role through Entra PIM, time-bound | |
| -ExchangeAdminHours | no | 2 | |
| -Apply | no | ||
| -OutFile | no | ||
| -TimeoutSeconds | no | 900 | #564: how long one Exchange action (and the scope check) may wait for Exchange; 0 = no waiting at all (the guided install passes a short value and defers the rest to Get Started -- a slow Exchange never holds an install) |
| -LoadFunctionsOnly | no | tests: define the functions and stop |
Preview with -WhatIf
The plan: what would be created, granted and removed, with the commands; nothing is changed (same as without -Apply).
Undo
Remove the role assignments, the scope and the service principals in Exchange; remove the mailbox if it was created.
Network
It connects to: *.blob.core.windows.net, *.queue.core.windows.net, *.table.core.windows.net, *.vault.azure.net, 169.254.169.254, api.loganalytics, api.loganalytics.io, api.msrc.microsoft.com, api.security.microsoft.com, api.securitycenter.microsoft.com, api.securityplatform.microsoft.com, database.windows.net, entra.microsoft.com, graph.microsoft.com, invardia.com, licenses.nuget.org, login.microsoftonline.com, management.azure.com, monitor.azure.com, nvd.nist.gov, outlook.office.com, outlook.office365.com, portal.invardia.com, storage.azure.com, vault.azure.net, www.powershellgallery.com
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/si/Set-SIMail.ps1 -OutFile Set-SIMail.ps1
.\Set-SIMail.ps1To check the download first, compare its SHA-256 with the published one:
SHA-256 4c2ed24e8a8c1632827b444381a9bbb68c017aa13b5610389200f63684212923
Checksums: SHA256SUMS.txt · Version 3.0.79
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Set-SIMail.ps1 -Full · Source: Set-SIMail.ps1
Every script, identity and permission for your security review: SecurityInsight