Various fixes (#657)

Co-authored-by: Anthony Watherston <[email protected]>
Azure · Jun 6, 2024 · 7867c8c · 7867c8c
1 parent 5bb617c
commit 7867c8c
Show file tree

Hide file tree

Showing 8 changed files with 298 additions and 159 deletions.
diff --git a/Docs/operational-scripts-documenting-policy.md b/Docs/operational-scripts-documenting-policy.md
@@ -136,22 +136,45 @@ Each file must contain one or both documentation topics. This example file in th
 
 Markdown processors vary slightly. This shipt has settings to tune the output to match the Markdown processor you are using.
 
-Azure DevOps Wikis (and maybe others) recognize `[[_TOC_]]` to insert a table of contents. Setting to `addMarkdownAdoWikiToc` to true enables generating the table of content.
+### Azure DevOps Wiki Markdown
+
+- Some Markdown processors (including Azure DevOps Wikis) recognize `[[_TOC_]]` to insert a table of contents. Setting to `markdownAddToc` to `true` enables generating the table of content.
+- Azure DevOps Wikis do not need a heading (title) at level 1. It needs the subheadings at level 1 instead. Setting `markdownAdoWiki` to true enables formatting the headings for Azure DevOps Wiki and generating the table of content (implicitly sets `markdownAddToc` to `true`).
+
+```jsonc
+"markdownAddToc": true, // default is false, set to true to add a table of contents
+```
+
+```jsonc
+"markdownAdoWiki": true, // default is false, set to true to format headings for Azure DevOps Wiki and generate a table of contents
+```
+
+### Embedded HTML in Markdown Tables
+
+EPAC uses embedded HTML to format Markdown tables. Some Markdown processors, such as SharePoint, do not recognize embedded HTML. Setting `markdownNoEmbeddedHtml` to `true` emits commas `, ` instead of the HTML tag `<br/>`.
+
+```jsonc
+"markdownNoEmbeddedHtml": true, // default is false, set to true to remove embedded HTML in Markdown tables
+```
+
+### Improve Markdown Readability
+
+Policy definition group names are not included in Markdown to reduce clutter. You can include a column by setting `markdownIncludeComplianceGroupNames` to `true`,
 
 ```jsonc
-"addMarkdownAdoWikiToc": true, // default is false, set to true to add markdown ADO Wiki TOC
+"markdownIncludeComplianceGroupNames": true, // default is false, set to true to include compliance group names
 ```
 
-SharePoint (and maybe others) do not recognize embedded HTML, such as line braeks (`<br/>`) within a Markdown table. Setting `noMarkdownInTableLineBreaks` to true emits commas instead of the HTML tag.
+In some markdown processors very long parameter name break the display. You can set `markdownSuppressParameterSection` to true to completely suppress the parameter section in the Markdown output.
 
 ```jsonc
-"noMarkdownInTableLineBreaks": true, // default is false, set to true to remove markdown in table line breaks
+"markdownSuppressParameterSection": true, // default is false, set to true to suppress the parameter section in the Markdown output
 ```
 
-Policy definition group names are not included in Markdown to reduce clutter. You can include a column by setting `includeComplianceGroupNamesInMarkdown` to true,
+Alternatively, you can set `markdownMaxParameterLength` to a maximum length. EPAC will truncate the name at that length and append an ellipsis. The default is 40 characters. The minimum is 16 characters.
 
 ```jsonc
-"includeComplianceGroupNamesInMarkdown": true, // default is false, set to true to include compliance group names
+"markdownMaxParameterLength": 42, // default is 42
 ```
 
 ## Assignment Documentation

diff --git a/Docs/policy-exemptions.md b/Docs/policy-exemptions.md
@@ -361,3 +361,9 @@ Legacy column `policyAssignmentId` is still supported for backward compatibility
 - Column `policyDefinitionReferenceIds` must be an ampersand separated list containing any of the following:
   - Empty to exempt all Policies in the Policy Set
   - One of the [options as detailed above](#specifying-policydefinitionreferenceids)
+
+## Moving from Excluded Scopes to Exemptions
+
+If you are moving from using excluded scopes to the use of exemptions the by default EPAC will not deploy new exemptions that are part of an assignment excluded scopes. As well as this - EPAC will delete any exemption if finds that is deployed to an excluded scope.
+
+You can override this behavior by using the switch ```-SkipNotScopedExemptions``` when you call ```Build-DeploymentPlans```.
diff --git a/Schemas/policy-documentation-schema.json b/Schemas/policy-documentation-schema.json
@@ -80,14 +80,23 @@
                                 "title": {
                                     "type": "string"
                                 },
-                                "addMarkdownAdoWikiToc": {
+                                "markdownAddToc": {
                                     "type": "boolean"
                                 },
-                                "noMarkdownInTableLineBreaks": {
+                                "markdownAdoWiki": {
                                     "type": "boolean"
                                 },
-                                "includeComplianceGroupNamesInMarkdown": {
+                                "markdownNoEmbeddedHtml": {
                                     "type": "boolean"
+                                },
+                                "markdownIncludeComplianceGroupNames": {
+                                    "type": "boolean"
+                                },
+                                "markdownSuppressParameterSection": {
+                                    "type": "boolean"
+                                },
+                                "markdownMaxParameterLength": {
+                                    "type": "integer"
                                 }
                             },
                             "required": [
@@ -149,6 +158,24 @@
                                     "type": "string"
                                 }
                             ]
+                        },
+                        "markdownAddToc": {
+                            "type": "boolean"
+                        },
+                        "markdownAdoWiki": {
+                            "type": "boolean"
+                        },
+                        "markdownNoEmbeddedHtml": {
+                            "type": "boolean"
+                        },
+                        "markdownIncludeComplianceGroupNames": {
+                            "type": "boolean"
+                        },
+                        "markdownSuppressParameterSection": {
+                            "type": "boolean"
+                        },
+                        "markdownMaxParameterLength": {
+                            "type": "integer"
                         }
                     },
                     "required": [

diff --git a/Scripts/Deploy/Build-DeploymentPlans.ps1 b/Scripts/Deploy/Build-DeploymentPlans.ps1
@@ -53,7 +53,9 @@ param (
 
     [Parameter(HelpMessage = "If set, outputs variables consumable by conditions in a DevOps pipeline.")]
     [ValidateSet("ado", "gitlab", "")]
-    [string] $DevOpsType = ""
+    [string] $DevOpsType = "",
+
+    [switch]$SkipNotScopedExemptions
 )
 
 $PSDefaultParameterValues = @{
@@ -332,17 +334,33 @@ if ($buildSelections.buildAny) {
 
     if ($buildSelections.buildPolicyExemptions) {
         # Process Exemption JSON files
-        Build-ExemptionsPlan `
-            -ExemptionsRootFolder $policyExemptionsFolderForPacEnvironment `
-            -ExemptionsAreNotManagedMessage $exemptionsAreNotManagedMessage `
-            -PacEnvironment $pacEnvironment `
-            -ScopeTable $scopeTable `
-            -AllDefinitions $allDefinitions `
-            -AllAssignments $allAssignments `
-            -CombinedPolicyDetails $combinedPolicyDetails `
-            -Assignments $assignments `
-            -DeployedExemptions $deployedPolicyResources.policyExemptions `
-            -Exemptions $exemptions
+        if ($SkipNotScopedExemptions) {
+            Build-ExemptionsPlan `
+                -ExemptionsRootFolder $policyExemptionsFolderForPacEnvironment `
+                -ExemptionsAreNotManagedMessage $exemptionsAreNotManagedMessage `
+                -PacEnvironment $pacEnvironment `
+                -ScopeTable $scopeTable `
+                -AllDefinitions $allDefinitions `
+                -AllAssignments $allAssignments `
+                -CombinedPolicyDetails $combinedPolicyDetails `
+                -Assignments $assignments `
+                -DeployedExemptions $deployedPolicyResources.policyExemptions `
+                -Exemptions $exemptions `
+                -SkipNotScopedExemptions
+        }
+        else {
+            Build-ExemptionsPlan `
+                -ExemptionsRootFolder $policyExemptionsFolderForPacEnvironment `
+                -ExemptionsAreNotManagedMessage $exemptionsAreNotManagedMessage `
+                -PacEnvironment $pacEnvironment `
+                -ScopeTable $scopeTable `
+                -AllDefinitions $allDefinitions `
+                -AllAssignments $allAssignments `
+                -CombinedPolicyDetails $combinedPolicyDetails `
+                -Assignments $assignments `
+                -DeployedExemptions $deployedPolicyResources.policyExemptions `
+                -Exemptions $exemptions
+        }
     }
 
     Write-Information "==================================================================================================="

diff --git a/Scripts/Helpers/Build-AssignmentDefinitionNode.ps1 b/Scripts/Helpers/Build-AssignmentDefinitionNode.ps1
@@ -344,11 +344,18 @@ function Build-AssignmentDefinitionNode {
                     $thisScopeGlobalNotScopeList = $thisScopeDetails.notScopesList
                     $thisScopeGlobalNotScopeTable = $thisScopeDetails.notScopesTable
                     foreach ($notScope in $definition.notScopesList) {
-                        if (-not $thisScopeGlobalNotScopeTable.ContainsKey($notScope)) {
-                            if ($thisScopeChildren.ContainsKey($notScope)) {
+                        $individualResource = $false
+                        $notScopeTrimmed = $notScope
+                        $splits = $notScope -split "/"
+                        if ($splits.Count -gt 5) {
+                            $individualResource = $true
+                            $notScopeTrimmed = $splits[0..4] -join "/"
+                        }
+                        if (-not $thisScopeGlobalNotScopeTable.ContainsKey($notScopeTrimmed)) {
+                            if ($thisScopeChildren.ContainsKey($notScopeTrimmed)) {
                                 $null = $thisNotScopeList.Add($notScope)
                             }
-                            elseif ($notScope.Contains("*")) {
+                            elseif (!$individualResource -and $notScope.Contains("*")) {
                                 foreach ($scopeChildId in $thisScopeChildren.Keys) {
                                     if ($scopeChildId -like $notScope) {
                                         $null = $thisNotScopeList.Add($scopeChildId)

diff --git a/Scripts/Helpers/Build-ExemptionsPlan.ps1 b/Scripts/Helpers/Build-ExemptionsPlan.ps1
@@ -10,7 +10,8 @@ function Build-ExemptionsPlan {
         $CombinedPolicyDetails,
         $Assignments,
         $DeployedExemptions,
-        $Exemptions
+        $Exemptions,
+        [switch]$SkipNotScopedExemptions
     )
 
     Write-Information "==================================================================================================="
@@ -618,8 +619,15 @@ function Build-ExemptionsPlan {
                                 if ($includeAssignment) {
                                     foreach ($notScope in $calculatedPolicyAssignment.notScopes) {
                                         if ($trimmedScope -eq $notScope -or $parentTable.ContainsKey($notScope)) {
-                                            $includeAssignment = $false
-                                            break
+                                            if ($SkipNotScopedExemptions) {
+                                                $includeAssignment = $true
+                                                break
+                                            }
+                                            else {
+                                                $includeAssignment = $false
+                                                break
+                                            }
+
                                         }
                                     }
                                     if ($includeAssignment) {