Grant-SIIdentity
Grant a managed identity everything SecurityInsight reads with
Purpose
Grants a managed identity (a VM's, an Azure Arc server's, or a user-assigned one) -- or, with -AppId, an app registration that signs in with a certificate -- everything SecurityInsight needs: Key Vault Secrets User on the SI vault, Reader at the collection scopes, Monitoring Metrics Publisher on the DCR resource group, Log Analytics Reader on the workspaces, the storage data roles, AcrPull, and the read-only Microsoft Graph / Defender application permissions. Prints present / missing; changes nothing without -Apply.
When to run it
When an identity is added, moved or found missing a permission (Get Started's permission check names this command).
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Owner or User Access Administrator | each scope it grants on | to add the role assignments |
| entraRole | Privileged Role Administrator (or Global Administrator) | the tenant | to grant application permissions (appRoleAssignments) |
| other | Microsoft Graph AppRoleAssignment.ReadWrite.All (when an app runs it instead of a person) | the tenant | to grant the identity its application permissions |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure RBAC | grant | the managed identity | Key Vault Secrets User | the SecurityInsight Key Vault | read its configuration and the licence | remove the role assignment |
| Azure RBAC | grant | the managed identity | Reader | the collection scope(s) (tenant root group or subscriptions) | enumerate Azure resources (Resource Graph) | remove the role assignment |
| Azure RBAC | grant | the managed identity | Monitoring Metrics Publisher | the DCR resource group | send rows through the SI data collection rules | remove the role assignment |
| Azure RBAC | grant | the managed identity | Log Analytics Reader | the SI workspace (and the Defender / Sentinel workspace) | Risk Analysis and correlation query the tables | remove the role assignment |
| Azure RBAC | grant | the managed identity | Storage Blob Data Contributor, Storage Queue Data Contributor, Storage Table Data Contributor | the SI storage account | SI's own run state | remove the role assignments |
| Azure RBAC | grant | the managed identity | AcrPull | the SI registry | pull the engine image | remove the role assignment |
| Entra application permissions | grant | the managed identity's service principal | Microsoft Graph User.Read.All, Group.Read.All, Directory.Read.All, Device.Read.All, Application.Read.All, AuditLog.Read.All, Policy.Read.All, RoleManagement.Read.All, RoleManagement.Read.Directory, RoleManagementPolicy.Read.Directory, RoleEligibilitySchedule.Read.Directory, RoleAssignmentSchedule.Read.Directory, PrivilegedAccess.Read.AzureADGroup, IdentityRiskyUser.Read.All, IdentityRiskEvent.Read.All, IdentityRiskyServicePrincipal.Read.All, ThreatHunting.Read.All, UserAuthenticationMethod.Read.All, DeviceManagementManagedDevices.Read.All, DeviceManagementConfiguration.Read.All, AccessReview.Read.All, SecurityAlert.Read.All, SecurityEvents.Read.All; Microsoft Threat Protection AdvancedHunting.Read.All; WindowsDefenderATP Machine.Read.All, Vulnerability.Read.All, SecurityRecommendation.Read.All, Score.Read.All | the tenant | read-only collection | remove the appRoleAssignments |
| Azure RBAC + Entra (only with -Tagging) | grant | the asset-tagging identity | Tag Contributor; Machine.ReadWrite.All; CustomSecAttributeAssignment.ReadWrite.All (write grants, opt-in) | the tagging scopes / the tenant | asset tagging writes tags only when switched on | remove the role assignments and appRoleAssignments |
| Azure RBAC | grant | the SecurityInsight identity | Monitoring Contributor | the data collection rule resource group (only with -AllowSchemaCreate) | the first run creates its own data collection rules | remove the role assignment (Azure portal -> the resource group -> Access control) |
| Azure RBAC | grant | the SecurityInsight identity | Log Analytics Contributor | the Log Analytics workspace (only with -AllowSchemaCreate) | the first run creates its own tables | remove the role assignment (Azure portal -> the workspace -> Access control) |
What it only reads
- existing role assignments
- existing appRoleAssignments
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -PrincipalId | yes | ||
| -IdentityName | yes | ||
| -IdentityResourceGroup | yes | ||
| -VmName | yes | ||
| -VmResourceGroup | yes | ||
| -ArcMachineName | yes | ||
| -ArcResourceGroup | yes | ||
| -AppId | yes | an app registration (certificate sign-in): its application (client) id; its service principal is found by that id | |
| -ConfigPath | no | ||
| -SubscriptionId | no | the subscription to work in; given, it wins over the config (the guided install passes its own answer) | |
| -ReaderScopes | no | ||
| -KeyVaultName | no | ||
| -AllowSchemaCreate | no | ||
| -Tagging | no | #236: the asset-tagging plan (writes) instead of the read-only collection plan -- for asset tagging's own identity | |
| -WebApp | no | #446: the Pro web app's own identity (uami-si-management): read-only Microsoft Graph for names, the people picker and the enterprise application's role holders. Needs no config file; give -SubscriptionId with -IdentityName. | |
| -TaggingScopes | no | ||
| -ReportOnly | no | With -Tagging: only what the job needs to RUN and report (its licence -- give -KeyVaultName --, the rules' reads, its activity rows, its run log) -- never the writes. What setup now grants every install; fix request 85bd728f. | |
| -WorkspaceResourceId | no | A container install has no config file on the machine running this: give its values instead (each wins over the config). | |
| -StorageAccountName | no | ||
| -StorageResourceGroup | no | ||
| -DcrResourceGroup | no | ||
| -AcrRegistryId | no | With -Tagging: the install's container registry (resource id) -- the job pulls its image as its own identity (AcrPull) | |
| -OnlyAppPermissions | no | Only the application permissions of the plan (Microsoft Graph, Defender): no Azure role is read or granted, and no install configuration is needed -- for a change that was approved as exactly that. | |
| -Only | no | Only these application permissions of the plan, by name (e.g. SecurityAlert.Read.All). Implies -OnlyAppPermissions. A name that is not in the plan stops the run: nothing outside the plan is ever granted. | |
| -Apply | no |
Preview with -WhatIf
The plan: every grant listed as present / missing; nothing is granted (same as running without -Apply).
Undo
Remove the listed role assignments and appRoleAssignments (the plan prints each with its scope).
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/Grant-SIIdentity.ps1 -OutFile Grant-SIIdentity.ps1
.\Grant-SIIdentity.ps1 -PrincipalId <PrincipalId> -IdentityName <IdentityName> -IdentityResourceGroup <IdentityResourceGroup> -VmName <VmName> -VmResourceGroup <VmResourceGroup> -ArcMachineName <ArcMachineName> -ArcResourceGroup <ArcResourceGroup> -AppId <AppId>To check the download first, compare its SHA-256 with the published one:
SHA-256 1ebe1979307757bb4a89d5f492dd67240ad84f8336a5439b4ea8d2e8b3ee3d49
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 .\Grant-SIIdentity.ps1 -Full · Source: Grant-SIIdentity.ps1
Every script, identity and permission for your security review: SecurityInsight