bring pattern matching feature to exemptions (#1008)

* added subscription pattern matching to exemptions

* undo formatting to try and get a cleaner PR

* add documentation

* update doc with tip

---------

Co-authored-by: Sean Krall <[email protected]>

Author: krallsm

Docs/policy-exemptions.md

@@ -168,7 +168,30 @@ It is unchanged from previous versions.
 In CSV files, the `scope` column is still supported for backward compatibility. We recommend using the `scopes` column for all new exemptions. `scopes` is a list of ampersand `&` separated strings.
 
 In JSON files, `scope` is a string and `scopes` is an array of strings.
- 
+
+### Pattern Matching
+
+You can define a pattern to match on subscriptions or resource groups for scopes. This allows an exemption to add matched subscriptions or resource group names to the exempted scope. It is not dynamic i.e. if you add subscriptions or resource groups later and want to include them you would have to run the plan again.
+
+The syntax is:
+
+```json
+"scopes": [
+    "/subscriptions/subscriptionsPattern/wildcard-pattern-to-match"
+  ]
+```
+
+or
+
+```json
+"scopes": [
+  "/subscriptions/*/resourceGroups/rg-pattern-to-match"
+]
+```
+
+> [!TIP]
+> If you want to match against a subscriptions name, rather than it's ID, you need to use the `subscriptionsPattern` to designate the name with the wildcards.
+
 ## Combining Policy Definitions at multiple Scopes
 
 When using **Option A** or **Option C**  and/or `scopes`, EPAC needs to generate concatenated values for `name`, `displayName`, and `description` to ensure uniqueness and readability.

Scripts/Helpers/Build-ExemptionsPlan.ps1

@@ -547,6 +547,60 @@ function Build-ExemptionsPlan {
                     $scopeIsValid = $true
                     $resourceStatus = "notAnIndividualResource"
                     $splits = $currentScope -split "/"
+                    
+                    $expandedScopes = [System.Collections.ArrayList]::new()
+                    $patternMatched = $false
+                    
+                    if ($trimmedScope -match "subscriptionsPattern") {
+                        $patternMatched = $true
+                        $rootScope = $ScopeTable["root"]
+                        if ($null -ne $rootScope) {
+                            $rootScopeChildren = $rootScope.childrenTable
+                            $pattern = $trimmedScope.split("/")[-1]
+                            $rootScopeChildren.Keys | Foreach-Object {
+                                if ($rootScopeChildren.$_.type -eq "/subscriptions") {
+                                    $subName = $rootScopeChildren.$_.displayName
+                                    if ($subName -like $pattern) {
+                                        $expandedScope = @{
+                                            scope = $rootScopeChildren.$_.id
+                                            scopePostfix = $scopePostfix
+                                        }
+                                        $null = $expandedScopes.Add($expandedScope)
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    elseif ($trimmedScope.Contains("*")) {
+                        $patternMatched = $true
+                        foreach ($scopeId in $ScopeTable.Keys) {
+                            if ($scopeId -ne "root" -and $scopeId -like $trimmedScope) {
+                                $expandedScope = @{
+                                    scope = $scopeId
+                                    scopePostfix = $scopePostfix
+                                }
+                                $null = $expandedScopes.Add($expandedScope)
+                            }
+                        }
+                    }
+                    
+                    if (-not $patternMatched) {
+                        $expandedScope = @{
+                            scope = $trimmedScope
+                            scopePostfix = $scopePostfix
+                        }
+                        $null = $expandedScopes.Add($expandedScope)
+                    }
+                    
+                    foreach ($expandedScopeInfo in $expandedScopes) {
+                        $currentScope = $expandedScopeInfo.scope
+                        $scopePostfix = $expandedScopeInfo.scopePostfix
+                        $trimmedScope = $currentScope.Trim()
+                        $subscriptionId = ""
+                        $scopeIsValid = $true
+                        $resourceStatus = "notAnIndividualResource"
+                        $splits = $currentScope -split "/"
+
                     if ($currentScope.StartsWith("/subscriptions/")) {
                         $subscriptionId = $splits[2]
                         if ($currentScope.Contains("/providers/")) {
@@ -1011,6 +1065,7 @@ function Build-ExemptionsPlan {
                     }
                     #endregion process each assignment (or multiple assignments)
 
+                    }
                 }
                 #endregion process each scope
             }