Minor README.md and Build-PolicyAssignmentDocumentation.ps1 improvements

Minor README.md and Build-PolicyAssignmentDocumentation.ps1 improvements.

Author: techlake

Pipeline/README.md

@@ -62,12 +62,12 @@ Create service connections for each of your environments and require minimum rol
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | sc-pac-dev | devAllStage  | Owner ||||
 | sc-pac-test    | testAllStage || Owner |||
-| sc-pac-plan-1 | prodPlanFeatureStage <br/> prodPlanMainStage ||| Policy Reader ||
-| sc-pac-plan-2 | prodPlanFeatureStage <br/> prodPlanMainStage |||| Policy Reader |
-| sc-pac-prod-1 | prodDeployStage-1 ||| Policy Contributor ||
-| sc-pac-prod-2 | prodDeployStage-2 |||| Policy Contributor |
-| sc-pac-roles-1 | prodRolesStage-1 ||| User Administrator ||
-| sc-pac-roles-2 | prodRolesStage-2 |||| User Administrator |
+| sc-pac-plan-1 | prodPlanFeatureStage <br/> prodPlanMainStage ||| Policy Reader<br/>Security Reader ||
+| sc-pac-plan-2 | prodPlanFeatureStage <br/> prodPlanMainStage |||| Policy Reader<br/>Security Reader |
+| sc-pac-prod-1 | prodDeployStage-1 ||| Policy Contributor<br/>Security Reader ||
+| sc-pac-prod-2 | prodDeployStage-2 |||| Policy Contributor<br/>Security Reader |
+| sc-pac-roles-1 | prodRolesStage-1 ||| User Administrator<br/>Security Reader ||
+| sc-pac-roles-2 | prodRolesStage-2 |||| User Administrator<br/>Security Reader |
 | none | prodNoPolicyStage-1 <br/> prodNoRoleStage-1 <br/> prodNoPolicyStage-2 </br> prodNoRoleStage-2 |||||
 
 <br/>

README.md

@@ -33,7 +33,7 @@ More details:
 - [Operational Scripts](Scripts/Operations/README.md)
 
 <br/><p style="background-color:Yellow;color:Black;border:5px solid Red;padding-left: 10px;padding-right: 10px;padding-top: 10px;padding-bottom: 10px;">
-<b><u>Warning:</u> If you have a existing Policies, Initiatives and Assignments in your environment, do not forget to change the "brownfield" variable in the pipeline to true.<br/><br/><u>Why?</u> This solution uses the desired state strategy. It will remove any custom Policies, Initiatives or Policy Assignments not duplicated in the definition files. The Build-AzPoliciesInitiativesAssignmentsPlan.ps1 script's switch parameter SuppressDeletes changes this behavior. Set the "brownfield" variable in the pipeline to true; it will set the switch parameter preventing deletions of existing Policies, Initiatives and Policy Assignments while transitioning to Enterprise Policy as Code.</b>
+<b><u>Warning:</u> If you have a existing Policies, Initiatives and Assignments in your environment, you have not transferred to EPAC, do not forget to change the "brownfield" variable in the pipeline to true.<br/><br/><u>Why?</u> This solution uses the desired state strategy. It will remove any custom Policies, Initiatives or Policy Assignments not duplicated in the definition files. The Build-AzPoliciesInitiativesAssignmentsPlan.ps1 script's switch parameter SuppressDeletes changes this behavior. Set the "brownfield" variable in the pipeline to true; it will set the switch parameter preventing deletions of existing Policies, Initiatives and Policy Assignments. This allows for a gradual transition from your existing Policy management to Enterprise Policy as Code.</b>
 </p><br/>
 
 ## Security & Compliance for Cloud Infrastructure
@@ -69,10 +69,10 @@ Git lacks a capability to ignore files/directories during a PR only. This repo h
   - You may add additional folders, such as a folder for your own operational scripts.
 - Syncing from GitHub repo.
   - Fetch changes from GitHub to `MyForkRepo`.
-  - Execute `Sync-Repo.ps1` to copy files from `MyForkRepo` to `MyWorkingRepo` feature branch.
+  - Execute [`Sync-Repo.ps1`](#sync-repops1) to copy files from `MyForkRepo` to `MyWorkingRepo` feature branch.
   - PR `MyWorkingRepo` feature branch.
 - Contribute to GitHub
-  - Execute `Sync-Repo.ps1` to copy files from `MyWorkingRepo` to `MyForkRepo` feature branch
+  - Execute [`Sync-Repo.ps1`](#sync-repops1) to copy files from `MyWorkingRepo` to `MyForkRepo` feature branch
   - PR `MyForkRepo` feature branch.
   - PR changes in your fork (`MyForkRepo`) to GitHub.
   - GitHub maintainers will review PR.
@@ -173,19 +173,26 @@ Explanations
 - `cloud` is used to select clouds (e.g., `AzureCloud`, `AzureUSGovernment`, `AzureGermanCloud`, ...).
 - `tenantId` is the GUID of your Azure AD tenant
 - `defaultSubscriptionId` is required to resolve Azure scopes correctly.
-- `rootScope` defines the location of your custom Policy and Initiative definitions. It also denotes the highest scope for an assignment. The roles for the CI/CD SPNs must assigned here.
+- `rootScope` defines the location of your custom Policy and Initiative definitions. It also denotes the highest scope for an assignment. The roles for the CI/CD SPNs must be assigned here.
 
 We explain the `managedIdentityLocations` and `globalNotScopes` elements in `global-settings.jsonc` [here](Definitions/README.md).
 
+<p style="background-color:Yellow;color:Black;border:5px solid Red;padding-left: 10px;padding-right: 10px;padding-top: 10px;padding-bottom: 10px;"><b><u>Note:</u>&nbsp;&nbsp;If the default output for az cli is configured wrong then you will encounter an unexpected error from ConvertFrom-Json in Invoke-AzCli. The initial default in az cli out-of-box is correct. You can set it back to the correct default with "az config set core.output=json"
+</b></p><br/>
+
+```ps1
+az config set core.output=json
+```
+
 <br/>
 
 ### Azure DevOps CI/CD Pipeline
 
 Setup your pipeline based on the provided starter kit pipeline. The yml file contains commented out sections to run in a IaaS Azure DevOps server (it requires a different approach to artifact storage) and for 2 additional tenants. Uncomment or delete the commented sections to fit your environment.
 
 <p style="background-color:Yellow;color:Black;border:5px solid Red;padding-left: 10px;padding-right: 10px;padding-top: 10px;padding-bottom: 10px;">
-<b><u>Warning:</u> If you have a existing Policies, Initiatives and Policy Assignments in your environment, do not forget to change the "brownfield" variable in the pipeline to true.</b>
-</p><br/>
+<b><u>Warning:</u>&nbsp;&nbsp;If you have a existing Policies, Initiatives and Policy Assignments in your environment you have not transferred to EPAC, do not forget to change the "brownfield" variable in the pipeline to true.
+</b></p><br/>
 
 Pipelines can customized to fit your needs:
 
@@ -200,10 +207,14 @@ Pipelines can customized to fit your needs:
 
 ### Edit and create Policies, Initiatives and Assignments
 
-Using the sttarter kit edit the directories in the `Definitions` folder
+Using the starter kit edit the directories in the `Definitions` folder. To simplify entering parameters, you can use the [Initiative documenting feature](Definitions/DocumentationSpecs/README.md#documenting-assignments-and-initiatives) which creates Markdown, CSV and a Json parameter file. You need to specify your initiatives to be documented (folder [`Definitions\DocumentationSpecs`](Definitions/DocumentationSpecs/README.md#specifying-initiative-documentation)) and execute script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](Scripts/Operations/README.md#build-policyassignmentdocumentationps1)
 
 <br/>
 
+### Document your Assignments
+
+This solution can generate [documentation in markdown and csv formats](Definitions/DocumentationSpecs/README.md).
+
 ## GitHub Folder Structure
 
 <br/>

Scripts/Helpers/Convert-EffectToString.ps1

@@ -2,33 +2,33 @@
 
 function Convert-EffectToString {
     param (
-        [string] $effect, 
+        [string] $effect,
         [array] $allowedValues,
-        [bool] $isParameterized,
         [switch] $Markdown
     )
 
     [string] $text = ""
     $effectShort = Convert-EffectToShortForm -effect $effect
     if ($Markdown.IsPresent) {
-        $text = "**$effectShort**"
-        if ($isParameterized) {
-            foreach ($allowed in $allowedValues) {
-                if ($allowed -ne $effect) {
-                    $effectShort = Convert-EffectToShortForm -effect $allowed
-                    $text += "<br/>*$effectShort*"
-                }
+        if ($allowedValues.Count -eq 1) {
+            $text = "***$effectShort***"
+        }
+        else {
+            $text = "**$effectShort**"
+        }
+        foreach ($allowed in $allowedValues) {
+            if ($allowed -cne $effect) {
+                $effectShort = Convert-EffectToShortForm -effect $allowed
+                $text += "<br/>*$effectShort*"
             }
         }
     }
     else {
         $text += $effectShort
-        if ($isParameterized) {
-            foreach ($allowed in $allowedValues) {
-                if ($allowed -ne $effect) {
-                    $effectShort = Convert-EffectToShortForm -effect $allowed
-                    $text += "\n$effectShort"
-                }
+        foreach ($allowed in $allowedValues) {
+            if ($allowed -cne $effect) {
+                $effectShort = Convert-EffectToShortForm -effect $allowed
+                $text += "\n$effectShort"
             }
         }
     }

Scripts/Helpers/Out-InitiativeDocumentationToFile.ps1

@@ -125,7 +125,6 @@ function Out-InitiativeDocumentationToFile {
                 $text = Convert-EffectToString `
                     -effect $effectValue `
                     -allowedValues $effectAllowedValues `
-                    -isParameterized $isEffectParameterized `
                     -Markdown
                 $addedEffectColumns += " $text |"
 
@@ -191,11 +190,9 @@ function Out-InitiativeDocumentationToFile {
                 $perInitiative = $initiativeList.$shortName
                 $effectValue = $perInitiative.effectValue
                 $effectAllowedValues = $perInitiative.effectAllowedValues
-                $isEffectParameterized = $perInitiative.isEffectParameterized
                 $text = Convert-EffectToString `
                     -effect $effectValue `
-                    -allowedValues $effectAllowedValues `
-                    -isParameterized $isEffectParameterized
+                    -allowedValues $effectAllowedValues
                 $null = $cells.Add($text)
             }
             else {

Scripts/Helpers/Out-PolicyAssignmentDocumentationAcrossEnvironmentsToFile.ps1

@@ -62,31 +62,34 @@ function Out-PolicyAssignmentDocumentationAcrossEnvironmentsToFile {
         foreach ($id in $flatPolicyList.Keys) {
             $flatPolicyEntry = $flatPolicyList.$id
 
-            [hashtable] $policyEffectsFlatEntry = @{}
+            [hashtable] $policyEffectsFlatEntry = $null
             if ($policyEffectsFlatList.ContainsKey($id)) {
                 $policyEffectsFlatEntry = $policyEffectsFlatList.$id
-                $effectAllowedValuesCurrent = $policyEffectsFlatEntry.effectAllowedValues
-                $effectAllowedValuesNew = $flatPolicyEntry.effectAllowedValues
-                if ($effectAllowedValuesNew.Count -gt $effectAllowedValuesCurrent.Count) {
-                    $policyEffectsFlatEntry.effectAllowedValue = $effectAllowedValuesNew
-                }
             }
             else {
 
                 $policyEffectsFlatEntry = @{
-                    category            = $flatPolicyEntry.category
-                    displayName         = $flatPolicyEntry.displayName
-                    description         = $flatPolicyEntry.description
-                    effectByEnvironment = @{}
-                    effectAllowedValues = $flatPolicyEntry.effectAllowedValues
+                    category      = $flatPolicyEntry.category
+                    displayName   = $flatPolicyEntry.displayName
+                    description   = $flatPolicyEntry.description
+                    byEnvironment = @{}
                 }
                 $policyEffectsFlatList.Add($id, $policyEffectsFlatEntry)
             }
 
             $effectiveAssignment = $flatPolicyEntry.effectiveAssignment
             $effect = $effectiveAssignment.effect
-            $effectByEnvironment = $policyEffectsFlatEntry.effectByEnvironment
-            $effectByEnvironment.Add($environmentCategory, $effect)
+            $effectAllowedValues = $effectiveAssignment.effectAllowedValues
+            $parameters = $effectiveAssignment.parameters
+            $byEnvironment = $policyEffectsFlatEntry.byEnvironment
+            if (!$byEnvironment.ContainsKey($environmentCategory)) {
+                $byEnvironment.Add($environmentCategory, @{
+                        effect              = $effect
+                        effectAllowedValues = $effectAllowedValues
+                        parameters          = $parameters
+                    }
+                )
+            }
         }
     }
 
@@ -132,21 +135,36 @@ function Out-PolicyAssignmentDocumentationAcrossEnvironmentsToFile {
     $policyEffectsFlatList.Values | Sort-Object -Property { $_.category }, { $_.displayName } | ForEach-Object -Process {
         # Build additional columns
         $addedEffectColumns = ""
-        $effectByEnvironment = $_.effectByEnvironment
+        $byEnvironment = $_.byEnvironment
+        $parameterFragment = ""
         foreach ($environmentCategory in $environmentCategories) {
-            if ($effectByEnvironment.ContainsKey($environmentCategory)) {
-                $effect = Convert-EffectToShortForm -effect  $effectByEnvironment.$environmentCategory
-                $addedEffectColumns += " $effect |"
+            if ($byEnvironment.ContainsKey($environmentCategory)) {
+                $environmentCategoryValues = $byEnvironment.$environmentCategory
+                $effectValue = $environmentCategoryValues.effect
+                $effectAllowedValues = $environmentCategoryValues.effectAllowedValues
+                # $parameters = $environmentCategoryValues.parameters
+
+                $text = Convert-EffectToString `
+                    -effect $effectValue `
+                    -allowedValues $effectAllowedValues `
+                    -Markdown
+                $addedEffectColumns += " $text |"
+
+                # if ($null -ne $parameters -and $parameters.Count -gt 0) {
+                #     $parameterFragment += "<br/>**$($environmentCategory):**"
+                #     $text = Convert-ParametersToString -parameters $parameters -Markdown
+                #     $parameterFragment += $text
+                # }
             }
             else {
                 $addedEffectColumns += "  |"
             }
         }
-        $null = $body.Add("| $($_.category) | **$($_.displayName)**<br/>$($_.description) | $addedEffectColumns")
+        $null = $body.Add("| $($_.category) | **$($_.displayName)**<br/>$($_.description)$($parameterFragment) | $addedEffectColumns")
     }
     $null = $allLines.AddRange($headerAndToc)
     $null = $allLines.AddRange($body)
-    
+
     # Output file
     $outputFilePath = "$($outputPath -replace '[/\\]$', '')/$fileNameStem.md"
     $allLines | Out-File $outputFilePath -Force
@@ -162,26 +180,33 @@ function Out-PolicyAssignmentDocumentationAcrossEnvironmentsToFile {
     foreach ($environmentCategory in $environmentCategories) {
         $null = $cells.Add($environmentCategory)
     }
-    $headerString = Convert-ListToToCsvRow($cells) 
+    $headerString = Convert-ListToToCsvRow($cells)
     $null = $allLines.Add($headerString)
 
     $policyEffectsFlatList.Values | Sort-Object -Property { $_.category }, { $_.displayName } | ForEach-Object -Process {
         # Build common columns
         $cells.Clear()
         $null = $cells.AddRange(@($_.category, $_.displayName, $_.description))
 
-        $effectByEnvironment = $_.effectByEnvironment
+        $byEnvironment = $_.byEnvironment
         # Build effect by environmentCategory columns
         foreach ($environmentCategory in $environmentCategories) {
-            if ($effectByEnvironment.ContainsKey($environmentCategory)) {
-                $effect = Convert-EffectToShortForm -effect $effectByEnvironment.$environmentCategory
-                $null = $cells.Add($effect)
+            if ($byEnvironment.ContainsKey($environmentCategory)) {
+                $environmentCategoryValues = $byEnvironment.$environmentCategory
+                $effectValue = $environmentCategoryValues.effect
+                $effectAllowedValues = $environmentCategoryValues.effectAllowedValues
+                # $parameters = $environmentCategoryValues.parameters
+
+                $text = Convert-EffectToString `
+                    -effect $effectValue `
+                    -allowedValues $effectAllowedValues
+                $null = $cells.Add($text)
             }
             else {
                 $null = $cells.Add("n/a")
             }
         }
-        $row = Convert-ListToToCsvRow($cells) 
+        $row = Convert-ListToToCsvRow($cells)
         $null = $allLines.Add($row)
     }
 

Scripts/Helpers/Out-PolicyAssignmentDocumentationPerEnvironmentToFile.ps1

@@ -92,12 +92,9 @@ function Out-PolicyAssignmentDocumentationPerEnvironmentToFile {
                 $assignmentFlat = $allAssignments.$shortName
                 $effectValue = $assignmentFlat.effect
                 $effectAllowedValues = $assignmentFlat.effectAllowedValues
-                $effectReason = $assignmentFlat.effectReason
-                $isParameterized = $effectReason -ne "PolicyFixed" -and $effectReason -ne "InitiativeFixed" -and $effectReason -ne "PolicyDefault"
                 $text = Convert-EffectToString `
                     -effect $effectValue `
                     -allowedValues $effectAllowedValues `
-                    -isParameterized $isParameterized `
                     -Markdown
                 $addedEffectColumns += " $text |"
 
@@ -158,12 +155,9 @@ function Out-PolicyAssignmentDocumentationPerEnvironmentToFile {
                 $assignmentFlat = $allAssignments.$shortName
                 $effectValue = $assignmentFlat.effect
                 $effectAllowedValues = $assignmentFlat.effectAllowedValues
-                $effectReason = $assignmentFlat.effectReason
-                $isParameterized = $effectReason -ne "PolicyFixed" -and $effectReason -ne "InitiativeFixed" -and $effectReason -ne "PolicyDefault"
                 $text = Convert-EffectToString `
                     -effect $effectValue `
-                    -allowedValues $effectAllowedValues `
-                    -isParameterized $isParameterized
+                    -allowedValues $effectAllowedValues
                 $null = $cells.Add($text)
             }
             else {