Get-GraphScriptPermissions.ps1
|
<#PSScriptInfo
.VERSION 1.0.0 .DESCRIPTION Analyze a PowerShell script for Microsoft Graph cmdlets and required permissions. .GUID e452ad1e-a89e-4160-9356-c97415e6cc37 .AUTHOR Gabriel Delaney .COMPANYNAME Phoenix Horizons LLC .COPYRIGHT 2025 Phoenix Horizons LLC .TAGS Graph, PowerShell, Permissions .LICENSEURI https://github.com/TheTolkienBlackGuy/Get-GraphScriptPermissions/blob/main/LICENSE .PROJECTURI https://github.com/TheTolkienBlackGuy/Get-GraphScriptPermissions .ICONURI .EXTERNALMODULEDEPENDENCIES Microsoft.Graph.Authentication .REQUIREDSCRIPTS .EXTERNALSCRIPTDEPENDENCIES .RELEASENOTES Initial release .PRIVATEDATA #> <# .SYNOPSIS Analyze a PowerShell script for Microsoft Graph cmdlets and required permissions. .DESCRIPTION Parses a script, finds Microsoft Graph cmdlets, and returns the least privileged and full permission sets for each. Optionally exports the results. .PARAMETER ScriptPath The path to the script file to analyze. .PARAMETER OutputPath Optional path to export results as CSV. .EXAMPLE .\Get-GraphScriptPermissions.ps1 -ScriptPath .\myscript.ps1 .EXAMPLE .\Get-GraphScriptPermissions.ps1 -ScriptPath .\myscript.ps1 -OutputPath .\permissions.csv .INPUTS System.String .OUTPUTS System.Object[] #> [CmdletBinding()] Param( [Parameter(Mandatory=$true,Position=0)] [ValidateScript({Test-Path -Path $_})] [string]$ScriptPath, [Parameter(Mandatory=$false,Position=1)] [string]$OutputPath ) #requires -Modules Microsoft.Graph.Authentication #region Helper functions # Function to find the Graph cmdlets in a script Function Find-GraphCmdletString { <# .SYNOPSIS Extracts cmdlets that query the Graph API from a script. .DESCRIPTION Extracts cmdlets that query the Graph API from a script. .PARAMETER Content The content of the script to search. .EXAMPLE Find-GraphCmdletString -Content $script_content .EXAMPLE Get-Content -Path $script_path | Find-GraphCmdletString .INPUTS System.String .OUTPUTS System.Object[] #> [CmdletBinding()] [OutputType([system.object[]])] Param( [Parameter(Mandatory=$true,Position=0,ValueFromPipeline=$true)] [object]$Content ) Begin { # Get the cmdlets that do not query the Graph API $exclusions = (Get-Command -Module Microsoft.Graph.Authentication).Name # Get the approved verbs $approved_verbs = (Get-Verb).Verb # Create a regex pattern to match the approved verbs followed by -Mg and any alphanumeric characters $pattern = "($($approved_verbs -join '|'))-Mg\w+" # Initialize an array to store the results $line_number = 0 } Process { foreach ($line in $content) { # Increment the line number $line_number++ # Skip empty lines If (!$line) { continue } # Remove comments $line = $line -replace '\s*#.*$','' # Skip lines that are just comments. Currently doesn't support block comments. if ($line.Trim().StartsWith("#")) { continue } # Find all cmdlets in the line $cmdlet_matches = ($line | Select-String -Pattern $pattern -AllMatches).Matches.Value foreach ($cmdlet in $cmdlet_matches) { # Microsoft.Graph.Authentication do not query the Graph API so we can ignore them If ($cmdlet -in $exclusions) { continue } $obj = [ordered] @{} # Add the cmdlet to the object $obj["Cmdlet"] = $cmdlet $obj["Line"] = $line.Trim() $obj["LineNumber"] = $line_number [pscustomobject]$obj } } } } # Function to get the permissions for a given Graph cmdlet Function Get-GraphCmdletPermissions { <# .SYNOPSIS Wrapper for Find-MgGraphCommand that extracts permissions. .DESCRIPTION For a given Graph cmdlet, returns the least privileged permission, all valid permissions, and the cmdlet name. .PARAMETER Cmdlet The Graph cmdlet to query. .EXAMPLE Get-GraphCmdletPermissions -Cmdlet Get-MgUser .INPUTS System.String .OUTPUTS System.Object #> [CmdletBinding()] [OutputType([System.Object])] Param( [Parameter(Mandatory=$true,Position=0)] [string]$Cmdlet, [Parameter(Mandatory=$false,Position=1)] [string]$ApiVersion = "v1.0" ) Begin { # Create the parameters for Find-MgGraphCommand $find_cmd_params = @{} $find_cmd_params["Command"] = $cmdlet $find_cmd_params["ApiVersion"] = $apiVersion # Initialize the has_scope variable $has_scope = $false # Get the Graph context $context = Get-MgContext # If the context is not authenticated with Microsoft Graph, throw a warning If ($context) { $current_scopes = $context.Scopes } } Process { Try { # Get the permissions for the cmdlet $permissions = (Find-MgGraphCommand @find_cmd_params ).Permissions | Where-Object { $_.FullDescription -notlike "Allows you*" -and $_.FullDescription -notmatch "\byour\b" } } Catch { Write-Error "$($_.Exception.Message)" -ErrorAction Stop } # Check if the current scopes have any of the permissions Foreach ($scope in $current_scopes) { If ($scope -in $permissions.Name) { $has_scope = $true Break } } # Create the object $obj = [ordered] @{} $obj["Cmdlet"] = $cmdlet $obj["LeastPrivilegedEffectivePermission"] = If ($permissions) { $permissions[0].Name } Else { "None" } $obj["Description"] = If ($permissions) { $permissions[0].Description } Else { "None" } $obj["Permissions"] = If ($permissions) { ($permissions.Name | Select-Object -Unique) -join ", " } Else { "None" } $obj["HasScope"] = $has_scope } End { # Return the object [pscustomobject]$obj } } #endregion #region Main # Initialize the results list $results = [System.Collections.Generic.List[System.Object]]::new() # Get the script content $script_content = Get-Content -Path $scriptPath # Find the Graph cmdlets in the script $graph_cmdlets = $script_content | Find-GraphCmdletString # Group by cmdlet and merge line numbers $grouped = $graph_cmdlets | Group-Object -Property Cmdlet # Get the permissions for each Graph cmdlet foreach ($group in $grouped) { $perm_info = Get-GraphCmdletPermissions -Cmdlet $group.Name # Create the object $obj = [ordered] @{} $obj["Cmdlet"] = $group.Name $obj["LineNumbers"] = ($group.Group.LineNumber -join ", ") $obj["LeastPrivilegedEffectivePermission"] = $perm_info.LeastPrivilegedEffectivePermission $obj["Description"] = $perm_info.Description $obj["Permissions"] = $perm_info.Permissions | Select-Object -Unique $obj["HasScope"] = $perm_info.HasScope # Add the object to the results list [void]$results.Add([pscustomobject]$obj) } #endregion #region Output if ($outputPath) { try { $results | Export-Csv -Path $outputPath -NoTypeInformation -Force Write-Output "Results exported to $outputPath" } catch { Write-Warning "Failed to export results to $outputPath. $($_.Exception.Message)" } } $results #endregion |