Merge pull request #54 from Azure/feature/exemptions

Exemptions managed with EPAC

Definitions/Assignments/README.md

@@ -99,10 +99,10 @@ Assignment files are hierarchical for efficient Json definitions, avoiding dupli
                                 "Lowest Level Local Parameter": "Value"
                             }
                         }
-                        
+
                     ]
                 },
-                
+
             ]
         },
         {
@@ -155,7 +155,7 @@ Assignment files are hierarchical for efficient Json definitions, avoiding dupli
             ]
         }
     ]
-} 
+}
 ```
 
 <br/>
@@ -209,7 +209,9 @@ The assignment selector determines the array being selected for this run of the
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 

Definitions/DocumentationSpecs/README.md → Definitions/Documentation/README.md

@@ -203,7 +203,9 @@ Each array entry defines three (3) files to be generated: Markdown, csv, and Jso
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 

Definitions/Exemptions/README.md

@@ -0,0 +1,63 @@
+# Exemptions
+
+## Table of Contents
+
+- [Exemption Files](#exemption-files)
+- [Example](#example)
+- [Reading List](#reading-list)
+
+## Exemption Files
+
+Exemptions can be defined as Json or CSV files. The names of the definition files don't matter. Additionally, through the use of a third-party PowerShell module from the PowerShell Gallery `ImportExcel` (https://www.powershellgallery.com/packages/ImportExcel, https://github.com/dfinke/ImportExcel/tree/master/Public). The contributors to this project are not responsible for any issues with that module. To mitigate the risk, the StarterKit has commented out the use of the conversion to protect your system from any vulnerabilities and executes the script without an Azure login.
+
+The pacEnvironment (see global-settings.jsonc) is represented with a folder, such as dev, test, tenant1, ... A missing folder indicates that the pacEnvironment's Exemptions are managed by this solution. To extract existing extension, the operations script Get-AzExemptions.ps1 can be used to generate Json and CSV files. The output should be used to start the Exemption definitions.
+
+### Format
+
+`name`, `exemptioncategory`, `scope` and `assignmentId` are required fields. The others are optional.
+
+```jsonc
+{
+    "exemptions": [
+        {
+            "name": "Unique name",
+            "displayName": "Descriptive name displayed on portal",
+            "description": "More details",
+            "exemptionCategory": "waiver",
+            "scope": "/subscriptions/11111111-2222-3333-4444-555555555555",
+            "policyAssignmentId": "/providers/microsoft.management/managementgroups/contoso-prod/providers/microsoft.authorization/policyassignments/prod-asb",
+            "policyDefinitionReferenceIds": [
+                "webApplicationFirewallShouldBeEnabledForApplicationGatewayMonitoringEffect"
+            ],
+            "metadata": {
+                "custom": "value"
+            }
+        }
+    ]
+}
+```
+
+If you use spreadsheets (.csv or .xlsx):
+- Column headers must be exactly as the Json labels above.
+- `policyDefinitionReferenceIds` use comma separated list within each cell.
+- `metadata` cells must conatin valid Json.
+
+
+## Reading List
+
+1. **[Pipeline](../../Pipeline/README.md)**
+
+1. **[Update Global Settings](../../Definitions/README.md)**
+
+1. **[Create Policy Definitions](../../Definitions/Policies/README.md)**
+
+1. **[Create Initiative Definitions](#initiative-definitions)**
+
+1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
+
+1. **[Operational Scripts](../../Scripts/Operations/README.md)**
+
+**[Return to the main page](../../README.md)**
+<br/>

Definitions/Initiatives/README.md

@@ -101,7 +101,9 @@ The Initiative definition files are structured based on the official [Azure Init
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 

Definitions/Policies/README.md

@@ -82,7 +82,9 @@ The Policy definition files are structured based on the official [Azure Policy d
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 

Definitions/README.md

@@ -26,7 +26,8 @@ This folder and subfolders contain the definitions to deploy. Tasks:
 1. Create custom Policy definitions (optional) in folder **[Policies](Policies/README.md)**
 1. Create custom Initiative definitions (optional) in folder **[Initiatives](Initiatives/README.md)**
 1. Define the Policy Assignments in folder **[Assignments](Assignments/README.md)**
-1. Define Documentation in folder **[DocumentationSpecs](../Definitions/DocumentationSpecs/README.md)**
+1. Define the Policy Exemptions in folder **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
+1. Define Documentation in folder **[Documentation](../Definitions/Documentation/README.md)**
 
 ## Global Settings
 
@@ -139,7 +140,9 @@ Each entry in the array defines one of the environments:
 
 1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../Scripts/Operations/README.md)**
 

Pipeline/README.md

@@ -15,6 +15,7 @@ This repository contains starter pipeline definitions for Azure DevOps. **The au
   - [Build-AzPoliciesInitiativesAssignmentsPlan.ps1](#build-azpoliciesinitiativesassignmentsplanps1)
   - [Deploy-AzPoliciesInitiativesAssignmentsFromPlan.ps1](#deploy-azpoliciesinitiativesassignmentsfromplanps1)
   - [Set-AzPolicyRolesFromPlan.ps1](#set-azpolicyrolesfromplanps1)
+- [Consuming Excel Files](#consuming-excel-files)
 - [Pipeline Execution](#pipeline-execution)
 - [Reading List](#reading-list)
 
@@ -143,6 +144,12 @@ Creates the role assignments for the Managed Identities required for `DeployIfNo
 
 <br/>
 
+## Consuming Excel Files
+
+Exemptions and assignments can use Json, CSV and Excel (.xlsx) files. Support for Excel files uses a third-party PowerShell module from the PowerShell Gallery. However, the StarterKit pipeline disables the use of .xslx files module (`Convert-XlsToCSV.ps1`) to mitigate potential vulnerability risks in a third-party utility (this does not imply any such vulnerabilities exist). You can enable it at your own risk by uncommenting the sections in each planning stage. The pipeline further mitigates the risk by executing this step without Azure credentials.
+
+<br/>
+
 ## Pipeline Execution
 
 Upon `commit to a feature branch or a manual pipeline run`, the pipeline runs stage devAllStage to deploy Policies, Initiatives and Assignments to the PAC DEV environment. Second, it calculates the plan for PROD environment deployment based on the Feature branch. This plan is never executed. Instead the logs and if desired the artifact generated are used by the developer to verify the definition files and to determine if the code is ready for a Pull Request. The PR approver(s) will use the same input plus the source code changes to decide the PR approval or rejection.
@@ -181,7 +188,9 @@ If there are no changes, empty stage(s) are executed to explicitly show that no
 
 1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
 
-1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
+
+1. **[Documenting Assignments and Initiatives](../Definitions/Documentation/README.md)**
 
 1. **[Operational Scripts](../Scripts/Operations/README.md)**
 

README.md

@@ -29,7 +29,10 @@ More details:
 - [Create Policy Definitions](Definitions/Policies/README.md)
 - [Create Initiative Definitions](Definitions/Initiatives/README.md)
 - [Define Policy Assignments](Definitions/Assignments/README.md)
-- [Documenting Assignments and Initiatives](Definitions/DocumentationSpecs/README.md)
+- [Define Policy Exemptions](Definitions/Exemptions/README.md)
+
+
+- [Documenting Assignments and Initiatives](Definitions/Documentation/README.md)
 - [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;">
@@ -207,13 +210,13 @@ Pipelines can customized to fit your needs:
 
 ### Edit and create Policies, Initiatives and Assignments
 
-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)
+Using the starter kit edit the directories in the `Definitions` folder. To simplify entering parameters, you can use the [Initiative documenting feature](Definitions/Documentation/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\Documentation`](Definitions/Documentation/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).
+This solution can generate [documentation in markdown and csv formats](Definitions/Documentation/README.md).
 
 ## GitHub Folder Structure
 
@@ -261,7 +264,8 @@ The repo contains a script to synchronize directories in both directions: `Sync-
 1. **[Create Policy Definitions](Definitions/Policies/README.md)**
 1. **[Create Initiative Definitions](Definitions/Initiatives/README.md)**
 1. **[Define Policy Assignments](Definitions/Assignments/README.md)**
-1. **[Documenting Assignments and Initiatives](Definitions/DocumentationSpecs/README.md)**
+1. **[Define Policy Exemptions](Definitions/Exemptions/README.md)**
+1. **[Documenting Assignments and Initiatives](Definitions/Documentation/README.md)**
 1. **[Operational Scripts](Scripts/Operations/README.md)**
 
 <br/>