Feature/aw/sync 20 9 24 (#749)

* Fix typos in documentation * Telemetry update * Fix for metadata in exemptions * New assignment export feature * Documentation generation fixes. --------- Co-authored-by: Anthony Watherston <[email protected]>
Azure · Sep 20, 2024 · 060bb29 · 060bb29
1 parent df152ae
commit 060bb29
Show file tree

Hide file tree

Showing 15 changed files with 528 additions and 46 deletions.
diff --git a/Docs/ci-cd-ado-pipelines.md b/Docs/ci-cd-ado-pipelines.md
@@ -19,15 +19,18 @@ The provided Azure DevOps pipelines utilize the template functionality to create
 
 If utilizing the GitHub flow branching strategy, three pipeline files are created
 
-  - [epac-dev-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-dev-pipeline.yml)
-  - [epac-tenant-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-tenant-pipeline.yml)
-  - [epac-remediation-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-remediation-pipeline.yml)
+- [epac-dev-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-dev-pipeline.yml)
+- [epac-tenant-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-tenant-pipeline.yml)
+- [epac-remediation-pipeline](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/AzureDevOps/GitHub-Flow/epac-remediation-pipeline.yml)
 
 ### epac-dev-pipeline
+
 This represents the Develop Policy Resources in a Feature Branch flow as described in [Branching Flows](ci-cd-branching-flows.md/#develop-policy-resources-in-a-feature-branch). In general, The EPAC-Dev pipeline is configured to run when any change is pushed to a `feature/*` branch. It runs across three (3) stages: Plan, Deploy & Tenant Plan.
 
 ### epac-tenant-pipeline
+
 This represents the Simplified `GitHub Flow` for Deployment as described in [Branching Flows](ci-cd-branching-flows.md/#simplified-`github-flow`-for-deployment). In general, The epac-tenant-pipeline is configured to run when any change is pushed to main and runs across three (3) stages: Plan, Deploy Policy & Deploy Roles. The Deploy stages utilize [Azure DevOps environments](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops) to configure approval gates
 
 ### epac-remediation-pipeline
-This pipeline runs on a schedule to automatically start remediation tasks for each environment.
+
+This pipeline runs on a schedule to automatically start remediation tasks for each environment.
diff --git a/Docs/integrating-with-alz.md b/Docs/integrating-with-alz.md
@@ -182,8 +182,8 @@ To deploy the ALZ policies using EPAC follow the steps below.
 
 6. Update assignment parameters.
 
-> [!WARNING] 
-> Carefully review the parameters and policies deployed as they have recently changed. Review each asssignment file carefully and ensure all parameter values are completed. Due to changes in usage of the Azure Monitor Agent - there are some Data Collection Rules that must be deployed prior to assigning the policies - the source for these DCRs are provided in the assignment file parameter comments. 
+> [!WARNING]
+> Carefully review the parameters and policies deployed as they have recently changed. Review each assignment file carefully and ensure all parameter values are completed. Due to changes in usage of the Azure Monitor Agent - there are some Data Collection Rules that must be deployed prior to assigning the policies - the source for these DCRs are provided in the assignment file parameter comments.
 
     Several of the assignment files also have parameters which need to be in place. Pay attention to the requirements about having a Log Analytics workspace deployed prior to assigning these policies as it is a requirement for several of the assignments. Less generic parameters are also available for modification in the assignment files.
 

diff --git a/Docs/operational-scripts-documenting-policy.md b/Docs/operational-scripts-documenting-policy.md
@@ -57,6 +57,9 @@ Each file must contain one or both documentation topics. This example file in th
                 "environmentCategories": [], // when using 'documentAllAssignments', this value will be overwritten
                 "title": "Contoso Policy effects",
                 "markdownAdoWiki": true,
+                "markdownIncludeComplianceGroupNames": true,
+                "markdownSuppressParameterSection": false,
+                "markdownMaxParameterLength": 42, //default is 42
                 "markdownAdoWikiConfig": [
                     {
                         "adoOrganization": "MyOrganization",
@@ -175,6 +178,9 @@ Each file must contain one or both documentation topics. This example file in th
             ],
             "title": "Contoso Policy effects",
             "markdownAdoWiki": true,
+            "markdownIncludeComplianceGroupNames": true,
+            "markdownSuppressParameterSection": false,
+            "markdownMaxParameterLength": 42, //default is 42
             "markdownAdoWikiConfig": [
                 {
                     "adoOrganization": "MyOrganization",
@@ -224,8 +230,8 @@ Markdown processors vary slightly. This shipt has settings to tune the output to
 
 ### 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`).
+* 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
@@ -237,16 +243,18 @@ Markdown processors vary slightly. This shipt has settings to tune the output to
 
 ### Automating Azure DevOps Wiki Markdown
 
-- EPAC can be used to automate the population of your Azure DevOps Wiki pages with the generated markdown files. To do this, you must call "Build-PolicyDocumentation" with the parameter "WikiClonePat". The value of the parameter should be the name of the Personal Access Token (PAT) set in your pipeline variable. Example:
+* EPAC can be used to automate the population of your Azure DevOps Wiki pages with the generated markdown files. To do this, you must call "Build-PolicyDocumentation" with the parameter "WikiClonePat". The value of the parameter should be the name of the Personal Access Token (PAT) set in your pipeline variable. Example:
 
 ```
 Build-PolicyDocumentation.ps1 -WikiClonePat $(WikiClonePat)
 ```
-- This PAT only requires "Read & write" permissions for "Code", as it will modify and push these markdown files to your Wiki. For more information please see ["Azure DevOps: Use personal access tokens"](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows)
-- In order for your EPAC to reach your Wiki, you must configure the "markdownAdoWikiConfig" property within your policyDeocumention file.
-  - **adoOrganization**: Name of your ADO Organization
-  - **adoProject**: Name of your ADO Project
-  - **adoWiki**: Name of your Wiki (If Wiki was not manually set up, it will be created for you based on the name given here)
+
+* This PAT only requires "Read & write" permissions for "Code", as it will modify and push these markdown files to your Wiki. For more information please see ["Azure DevOps: Use personal access tokens"](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows)
+
+* In order for your EPAC to reach your Wiki, you must configure the "markdownAdoWikiConfig" property within your policy documentation file.
+  * **adoOrganization**: Name of your ADO Organization
+  * **adoProject**: Name of your ADO Project
+  * **adoWiki**: Name of your Wiki (If Wiki was not manually set up, it will be created for you based on the name given here)
 
 ```jsonc
 "markdownAdoWikiConfig": [
@@ -258,11 +266,11 @@ Build-PolicyDocumentation.ps1 -WikiClonePat $(WikiClonePat)
                 ]
 ```
 
-- For a full implementation using an example pipeline, please see ["EPAC GitHub: epac-dev-pipeline-with-adowiki.yml"](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/GitHubActions/GitHub-Flow-With-ADOWiki/epac-dev-pipeline-with-adowiki.yml)
+* For a full implementation using an example pipeline, please see ["EPAC GitHub: epac-dev-pipeline-with-adowiki.yml"](https://github.com/Azure/enterprise-azure-policy-as-code/blob/main/StarterKit/Pipelines/GitHubActions/GitHub-Flow-With-ADOWiki/epac-dev-pipeline-with-adowiki.yml)
 
 ### 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/>`.
+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
@@ -282,7 +290,7 @@ In some markdown processors very long parameter name break the display. You can
 "markdownSuppressParameterSection": true, // default is false, set to true to suppress the parameter section in the Markdown output
 ```
 
-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.
+Alternatively, you can set `markdownMaxParameterLength` to a maximum length. EPAC will truncate the name at that length and append an ellipsis. The default is 42 characters. The minimum is 16 characters.
 
 ```jsonc
 "markdownMaxParameterLength": 42, // default is 42
@@ -299,10 +307,10 @@ When enabled, this section lists all Policy Assignments across all scopes where
 `documentAllAssignments` entry specifies:
 
 * `pacEnvironment`: references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the Policies and Policy Sets are deployed.
-* `fileNameStemPrefix`: add a prefix to the fileNameStem set in "documentationSpecifications". Usefull when needing to avoid overwriting of files.
-* `skipPolicyAssignments`: list of Policy Assignment ID's used to define Policy Assinments that do not want to included in the output.
-* `skipPolicyDefinitions`: list of Policy Definition and Policy Set ID's used to define Policy Assinments that do not want to included in the output.
-* `overrideEnvironmentCategory`: list of custom defined Environment Categories that will overwrite the auto-generated values. By default, all Policy Assignment scopes are treated as an individual "Environment Category", therefore leverage this section to override these Environemnt Categories and create custom groupings. (For an example see [`Example Documentation Specification File using 'documentAllAssignments'`](#Example-Documentation-Specification-File-using-documentAllAssignments))
+* `fileNameStemPrefix`: add a prefix to the fileNameStem set in "documentationSpecifications". Useful when needing to avoid overwriting of files.
+* `skipPolicyAssignments`: list of Policy Assignment ID's used to define Policy Assignments that do not want to included in the output.
+* `skipPolicyDefinitions`: list of Policy Definition and Policy Set ID's used to define Policy Assignments that do not want to included in the output.
+* `overrideEnvironmentCategory`: list of custom defined Environment Categories that will overwrite the auto-generated values. By default, all Policy Assignment scopes are treated as an individual "Environment Category", therefore leverage this section to override these Environment Categories and create custom groupings. (For an example see [`Example Documentation Specification File using 'documentAllAssignments'`](#example-documentation-specification-file-using-documentallassignments))
 
 ### Element `documentationSpecifications`
 
@@ -374,7 +382,7 @@ Each entry in the array defines a set of outputs:
 
 * `<fileNameStem>-summary.md`: This Markdown file is intended for developers for a quick overview of the effects and parameters in place for each `environmentCategory`. It does not provide details about the individual Initiatives assigned. It is equivalent to `<fileNameStem>-parameters.csv`. The Policies are sorted by `category` and ``displayName`. Each`environmentCategory` column shows the current enforcement level in bold. If the value is fixed, the value is also in italics. If it is parametrized, the other allowed values are shown in italics.
 
-* `<fileNameStem>-full.md`: This Markdown file is intended for security personel requiring more details about the Assignments and Policies. It displays the same information as the summary plus the additional details equivalent to `<fileNameStem>-full.csv`. The Policies are sorted by `category` and ``displayName`. Each`environmentCategory` column shows the current enforcement level in bold. If the value is fixed, the value is also in italics. If it is parametrized, the other allowed values are shown in italics. The additional details are:
+* `<fileNameStem>-full.md`: This Markdown file is intended for security teams requiring more details about the Assignments and Policies. It displays the same information as the summary plus the additional details equivalent to `<fileNameStem>-full.csv`. The Policies are sorted by `category` and ``displayName`. Each`environmentCategory` column shows the current enforcement level in bold. If the value is fixed, the value is also in italics. If it is parametrized, the other allowed values are shown in italics. The additional details are:
   * Group Names
   * Effects per `environmentCategory` and Policy Set with additional details on the origin of the effect.
 

diff --git a/Docs/operational-scripts-reference.md b/Docs/operational-scripts-reference.md
@@ -2,7 +2,7 @@
 
 ## Script `Build-PolicyDocumentation`
 
-Builds documentation from instructions in policyDocumentations folder reading the delployed Policy Resources from the EPAC envioronment.
+Builds documentation from instructions in policyDocumentations folder reading the deployed Policy Resources from the EPAC environment.
 
 ```ps1
 Build-PolicyDocumentation [[-DefinitionsRootFolder] <String>] [[-OutputFolder] <String>] [-WindowsNewLineCells] [-Interactive <Boolean>] [-SuppressConfirmation] [-IncludeManualPolicies] [<CommonParameters>]
@@ -32,7 +32,7 @@ Suppresses prompt for confirmation to delete existing file in interactive mode
 
 #### `-IncludeManualPolicies [<SwitchParameter>]`
 
-Include Policies with effect Manual. Default: do not include Polcies with effect Manual.
+Include Policies with effect Manual. Default: do not include Policies with effect Manual.
 
 ## Script `New-AzRemediationTasks`
 

diff --git a/Docs/operational-scripts.md b/Docs/operational-scripts.md
@@ -36,6 +36,26 @@ The Hydration Kit is a set of scripts that can be used to deploy an EPAC environ
 
 The scripts `New-AzureDevOpsBug` and `New-GitHubIssue` create a Bug or Issue when there are one or multiple failed Remediation Tasks.
 
+
+## Export from AzAdvertizer
+
+The script `Export-AzAdvertizer.ps1` creates for you the policyAssignments, policyDefinitions, and policySetDefinitions based on the provided URL in an Output folder under 'ALZ-Export'.
+
+Parameters:
+- **AzAdvertizerUrl**: Mandatory url of the policy or policy set from AzAdvertizer.
+
+- **OutputFolder**: Output Folder. Defaults to the path 'Output'.
+
+- **AutoCreateParameters**: Automatically create parameters for Azure Policy Sets and Assginment Files.
+
+- **UseBuiltIn**: Default to using builtin policies rather than local versions.
+
+- **Scope**: Used to set scope value on each assignment file.
+
+- **PacSelector**: Used to set PacEnvironment for each assignment file.
+
+- **OverwriteOutput**: Used to Overwrite the contents of the output folder with each run. Helpful when running consecutively.
+
 ## Non-compliance Reports
 
 `Export-NonComplianceReports` exports non-compliance reports for EPAC environments . It outputs the reports in the `$OutputFolders/non-compliance-reports` folder.

diff --git a/Docs/policy-assignments.md b/Docs/policy-assignments.md
@@ -216,7 +216,7 @@ You can specify them in `global-settings.jsonc` or at any node in the tree. The
 
 In some scenarios you will need `additionalRoleAssignments`; e.g., for diagnostics settings to Event Hubs, the target resource might be in a different Management Group and therefore the Managed Identity requires additional role assignments. You must specify the `additionalRoleAssignments` based on EPAC Environment or use `"*"`to use the same `additionalRoleAssignments`for all of the EPAC Environments.  If the pacEnvironment under deployment is specified in the additionalRoleAssignments, the `"*"` assignments will be ignored.
 
-If the additional assignment is to made to a managing tenant in the sceenario where the pacEnvironment under deployment is a manganged (lighthouse) tenant, you must specify `""crossTenant": true"` for that assignment.  Ensure all necessary ABAC permissions are in place for the executing SPN.
+If the additional assignment is to made to a managing tenant in the scenario where the pacEnvironment under deployment is a managed (Azure Lighthouse) tenant, you must specify `""crossTenant": true"` for that assignment.  Ensure all necessary ABAC permissions are in place for the executing SPN.
 
 ```json
 "additionalRoleAssignments": {

diff --git a/Docs/start-extracting-policy-resources.md b/Docs/start-extracting-policy-resources.md
@@ -1,6 +1,6 @@
 # Start by Extracting existing Policy Resources
 
-Script `Export-AzPolicyResources` (Operations) extracts existing Policies, Policy Sets, and Policy Assignments and Exemptions outputing them in EPAC format into subfolders in folder `$outputFolders/Definitions`. The subfolders are `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`.
+Script `Export-AzPolicyResources` (Operations) extracts existing Policies, Policy Sets, and Policy Assignments and Exemptions outputting them in EPAC format into subfolders in folder `$outputFolders/Definitions`. The subfolders are `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`.
 
 > [!TIP]
 > The script collects information on ownership of the Policy resources into a CSV file. You can analyze this file to assist in the transition to EPAC.