Skip to content

Commit 90cdd26

Browse files
techlaketechlake
authored
Merge pull request #54 from Azure/feature/exemptions
Exemptions managed with EPAC
2 parents 6233374 + 2f99e76 commit 90cdd26

35 files changed

+1611
-781
lines changed

‎Definitions/Assignments/README.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,10 +99,10 @@ Assignment files are hierarchical for efficient Json definitions, avoiding dupli
9999
"Lowest Level Local Parameter": "Value"
100100
}
101101
}
102-
102+
103103
]
104104
},
105-
105+
106106
]
107107
},
108108
{
@@ -155,7 +155,7 @@ Assignment files are hierarchical for efficient Json definitions, avoiding dupli
155155
]
156156
}
157157
]
158-
}
158+
}
159159
```
160160

161161
<br/>
@@ -209,7 +209,9 @@ The assignment selector determines the array being selected for this run of the
209209

210210
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
211211

212-
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
212+
1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
213+
214+
1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
213215

214216
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
215217

‎Definitions/DocumentationSpecs/README.md renamed to ‎Definitions/Documentation/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,9 @@ Each array entry defines three (3) files to be generated: Markdown, csv, and Jso
203203

204204
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
205205

206-
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
206+
1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
207+
208+
1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
207209

208210
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
209211

‎Definitions/Exemptions/README.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Exemptions
2+
3+
## Table of Contents
4+
5+
- [Exemption Files](#exemption-files)
6+
- [Example](#example)
7+
- [Reading List](#reading-list)
8+
9+
## Exemption Files
10+
11+
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.
12+
13+
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.
14+
15+
### Format
16+
17+
`name`, `exemptioncategory`, `scope` and `assignmentId` are required fields. The others are optional.
18+
19+
```jsonc
20+
{
21+
"exemptions": [
22+
{
23+
"name": "Unique name",
24+
"displayName": "Descriptive name displayed on portal",
25+
"description": "More details",
26+
"exemptionCategory": "waiver",
27+
"scope": "/subscriptions/11111111-2222-3333-4444-555555555555",
28+
"policyAssignmentId": "/providers/microsoft.management/managementgroups/contoso-prod/providers/microsoft.authorization/policyassignments/prod-asb",
29+
"policyDefinitionReferenceIds": [
30+
"webApplicationFirewallShouldBeEnabledForApplicationGatewayMonitoringEffect"
31+
],
32+
"metadata": {
33+
"custom": "value"
34+
}
35+
}
36+
]
37+
}
38+
```
39+
40+
If you use spreadsheets (.csv or .xlsx):
41+
- Column headers must be exactly as the Json labels above.
42+
- `policyDefinitionReferenceIds` use comma separated list within each cell.
43+
- `metadata` cells must conatin valid Json.
44+
45+
46+
## Reading List
47+
48+
1. **[Pipeline](../../Pipeline/README.md)**
49+
50+
1. **[Update Global Settings](../../Definitions/README.md)**
51+
52+
1. **[Create Policy Definitions](../../Definitions/Policies/README.md)**
53+
54+
1. **[Create Initiative Definitions](#initiative-definitions)**
55+
56+
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
57+
58+
1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
59+
60+
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
61+
62+
**[Return to the main page](../../README.md)**
63+
<br/>

‎Definitions/Initiatives/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,9 @@ The Initiative definition files are structured based on the official [Azure Init
101101

102102
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
103103

104-
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
104+
1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
105+
106+
1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
105107

106108
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
107109

‎Definitions/Policies/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,9 @@ The Policy definition files are structured based on the official [Azure Policy d
8282

8383
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
8484

85-
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
85+
1. **[Define Policy Exemptions](../../Definitions/Exemptions/README.md)**
86+
87+
1. **[Documenting Assignments and Initiatives](../../Definitions/Documentation/README.md)**
8688

8789
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
8890

‎Definitions/README.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ This folder and subfolders contain the definitions to deploy. Tasks:
2626
1. Create custom Policy definitions (optional) in folder **[Policies](Policies/README.md)**
2727
1. Create custom Initiative definitions (optional) in folder **[Initiatives](Initiatives/README.md)**
2828
1. Define the Policy Assignments in folder **[Assignments](Assignments/README.md)**
29-
1. Define Documentation in folder **[DocumentationSpecs](../Definitions/DocumentationSpecs/README.md)**
29+
1. Define the Policy Exemptions in folder **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
30+
1. Define Documentation in folder **[Documentation](../Definitions/Documentation/README.md)**
3031

3132
## Global Settings
3233

@@ -139,7 +140,9 @@ Each entry in the array defines one of the environments:
139140

140141
1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
141142

142-
1. **[Documenting Assignments and Initiatives](../Definitions/DocumentationSpecs/README.md)**
143+
1. **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
144+
145+
1. **[Documenting Assignments and Initiatives](../Definitions/Documentation/README.md)**
143146

144147
1. **[Operational Scripts](../Scripts/Operations/README.md)**
145148

‎Pipeline/README.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ This repository contains starter pipeline definitions for Azure DevOps. **The au
1515
- [Build-AzPoliciesInitiativesAssignmentsPlan.ps1](#build-azpoliciesinitiativesassignmentsplanps1)
1616
- [Deploy-AzPoliciesInitiativesAssignmentsFromPlan.ps1](#deploy-azpoliciesinitiativesassignmentsfromplanps1)
1717
- [Set-AzPolicyRolesFromPlan.ps1](#set-azpolicyrolesfromplanps1)
18+
- [Consuming Excel Files](#consuming-excel-files)
1819
- [Pipeline Execution](#pipeline-execution)
1920
- [Reading List](#reading-list)
2021

@@ -143,6 +144,12 @@ Creates the role assignments for the Managed Identities required for `DeployIfNo
143144

144145
<br/>
145146

147+
## Consuming Excel Files
148+
149+
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.
150+
151+
<br/>
152+
146153
## Pipeline Execution
147154

148155
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
181188

182189
1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
183190

184-
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
191+
1. **[Define Policy Exemptions](../Definitions/Exemptions/README.md)**
192+
193+
1. **[Documenting Assignments and Initiatives](../Definitions/Documentation/README.md)**
185194

186195
1. **[Operational Scripts](../Scripts/Operations/README.md)**
187196

‎README.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,10 @@ More details:
2929
- [Create Policy Definitions](Definitions/Policies/README.md)
3030
- [Create Initiative Definitions](Definitions/Initiatives/README.md)
3131
- [Define Policy Assignments](Definitions/Assignments/README.md)
32-
- [Documenting Assignments and Initiatives](Definitions/DocumentationSpecs/README.md)
32+
- [Define Policy Exemptions](Definitions/Exemptions/README.md)
33+
34+
35+
- [Documenting Assignments and Initiatives](Definitions/Documentation/README.md)
3336
- [Operational Scripts](Scripts/Operations/README.md)
3437

3538
<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:
207210

208211
### Edit and create Policies, Initiatives and Assignments
209212

210-
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)
213+
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)
211214

212215
<br/>
213216

214217
### Document your Assignments
215218

216-
This solution can generate [documentation in markdown and csv formats](Definitions/DocumentationSpecs/README.md).
219+
This solution can generate [documentation in markdown and csv formats](Definitions/Documentation/README.md).
217220

218221
## GitHub Folder Structure
219222

@@ -261,7 +264,8 @@ The repo contains a script to synchronize directories in both directions: `Sync-
261264
1. **[Create Policy Definitions](Definitions/Policies/README.md)**
262265
1. **[Create Initiative Definitions](Definitions/Initiatives/README.md)**
263266
1. **[Define Policy Assignments](Definitions/Assignments/README.md)**
264-
1. **[Documenting Assignments and Initiatives](Definitions/DocumentationSpecs/README.md)**
267+
1. **[Define Policy Exemptions](Definitions/Exemptions/README.md)**
268+
1. **[Documenting Assignments and Initiatives](Definitions/Documentation/README.md)**
265269
1. **[Operational Scripts](Scripts/Operations/README.md)**
266270

267271
<br/>

0 commit comments

Comments
 (0)