<# .SYNOPSIS Azure & Microsoft 365 Copilot Agent Management and Audit Toolkit. .DESCRIPTION Connects to Microsoft Graph and Azure Management APIs to enumerate, audit, and export all registered Azure Copilot agents, their delegated scopes, and multi-tenant access permissions. .EXAMPLE .\Audit-CopilotAgents.ps1 -ExportPath "C:\Reports\CopilotAgents.csv" .NOTES Author: Souhaiel Morhag Company: MSEndpoint.com Blog: https://msendpoint.com Academy: https://app.msendpoint.com/academy LinkedIn: https://linkedin.com/in/souhaiel-morhag GitHub: https://github.com/Msendpoint License: MIT #> [CmdletBinding()] param ( [Parameter(Mandatory = $false)] [string]$ExportPath = ".\AzureCopilot_Agents_Audit.csv", [Parameter(Mandatory = $false)] [string]$TenantId ) $ErrorActionPreference = "Stop" Write-Host "═══════════════════════════════════════════════════════════════" -ForegroundColor Cyan Write-Host " 🚀 MSEndpoint - Azure & M365 Copilot Agent Audit Toolkit" -ForegroundColor Yellow Write-Host "═══════════════════════════════════════════════════════════════" -ForegroundColor Cyan try { # Check for Microsoft.Graph module if (-not (Get-Module -ListAvailable -Name Microsoft.Graph.Authentication)) { Write-Host "📦 Installing Microsoft.Graph.Authentication..." -ForegroundColor Yellow Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Force } Write-Host "🔐 Authenticating to Microsoft Graph & Azure Management..." -ForegroundColor Green $Scopes = @( "Application.Read.All", "Directory.Read.All", "DelegatedPermissionGrant.ReadWrite.All" ) Connect-MgGraph -Scopes $Scopes -NoWelcome Write-Host "🔍 Querying Copilot and Service Principals..." -ForegroundColor Green $allApps = Get-MgServicePrincipal -Filter "tags/any(t: t eq 'Copilot') or startswith(displayName, 'Copilot')" -All $results = [System.Collections.Generic.List[PSCustomObject]]::new() foreach ($app in $allApps) { $scopes = (Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId $app.Id -All).Scope -join "; " $results.Add([PSCustomObject]@{ AgentName = $app.DisplayName AppId = $app.AppId ObjectId = $app.Id AccountEnabled = $app.AccountEnabled DelegatedScopes = if ($scopes) { $scopes } else { "None" } Publisher = $app.PublisherName AuditDate = (Get-Date).ToString("yyyy-MM-dd HH:mm:ss") }) } if ($results.Count -gt 0) { $results | Export-Csv -Path $ExportPath -NoTypeInformation -Encoding UTF8 Write-Host "✅ Audit Complete! Found $($results.Count) Copilot agents." -ForegroundColor Green Write-Host "📄 Exported report to: $ExportPath" -ForegroundColor Cyan $results | Format-Table -AutoSize } else { Write-Host "ℹ No Copilot agents currently registered in this tenant." -ForegroundColor Yellow } } catch { Write-Error "❌ Fatal Error during Copilot Agent Audit: $_" } finally { Write-Host "✨ Audit session completed." -ForegroundColor DarkGray }