Skip to content

Commit 4b8c5c6

Browse files
techlaketechlake
authored
Simplified global-settings.json, improved documentation scripts and multi-tenant handling
- Simplified `global-setting.jsonc`: **breaking changes** - Simplified the layout by removing the documentation specifications (`representativeAssignments` and `initiativeSetsToCompare`) from `global-settings.jsonc` and moving to a folder (see below) - Changed `managedIdentityLocation` to `managedIdentityLocations` (plural) - Improved and consolidated automated generation of documentation - Folder `Definitions/DocumentationSpecs` conatains the instructions on what to generate (moved with substantial format chnages from `global-settings.jsonc` - Single script to generate documentation: `Scripts\Operations\Build-PolicyAssignmentDocumentation.ps1` - Removed scripts `Get-AzEffectsForEnvironments.ps1` and `Get-AzEffectsForInitiative.ps1`, replaced by `Build-PolicyAssignmentDocumentation.ps1` - Improved multi-tenant and cloud selection support, prompts for re-authentication in interactive mode - Detects when wrong cloud selected (additional field in `pacEnvironments` (`global-settings.jsonc`) - Detects when logged into wrong tenant - Detects when default subscription wrong (switches to correct one) - Bug fixes - Solution had latent scope bug retrieving Policy and Initiative definitions from management Groups, if the default subscription was not in the right hierarchy. - Improved error handling
2 parents 6fae684 + 340ab66 commit 4b8c5c6

File tree

64 files changed

+5754
-1374
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+5754
-1374
lines changed

‎Definitions/Assignments/README.md

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
- [Components](#components)
77
- [Assignment File Overview Diagram](#assignment-file-overview-diagram)
8-
- [Assignment JSON file structure](#assignment-json-file-structure)
8+
- [Assignment Json file structure](#assignment-json-file-structure)
99
- [Assignment Node Components](#assignment-node-components)
1010
- [Details for `scope` and `notScope` Values](#details-for--scope--and--notscope--values)
1111
- [Using the `PacAssignmentSelector`](#using-the--pacassignmentselector-)
@@ -21,21 +21,21 @@ The components required for **creating / updating / deleting Policy assignments
2121

2222
| Component | What is it used for? | Where can it be found? |
2323
|--|--|--|
24-
| **Assignment JSON files** | The assignments JSON file follows the management group hierarchy (optionally including subscriptions and resource groups) and defines all policy and initiative assignments on these scopes. | `Definitions/Assignments` folder |
24+
| **Assignment Json files** | The assignments Json file follows the management group hierarchy (optionally including subscriptions and resource groups) and defines all policy and initiative assignments on these scopes. | `Definitions/Assignments` folder |
2525
| **Global Settings File** | The `global-settings.jsonc` file specifies common values for Policy Assignments | `Definitions` folder |
2626

27-
<br/>[Back to top](#policy-assignments)<br/>
27+
<br/>
2828

2929
## Assignment File Overview Diagram
3030

31-
Assignment files are hierarchical for efficient JSON definitions, avoiding duplication of JSON with copy/paste.
31+
Assignment files are hierarchical for efficient Json definitions, avoiding duplication of Json with copy/paste.
3232
<br/>
3333

3434
![Assignment File Overview Diagram](../../Docs/Images/PaC-Assignment-Structure.png)
3535

36-
<br/>[Back to top](#policy-assignments)<br/>
36+
<br/>
3737

38-
## Assignment JSON file structure
38+
## Assignment Json file structure
3939

4040
`scope` and `notScope` use a `PacAssignmentSelector` to specify which scope to use for different environments and tenants. The value for the `PacAssignmentSelector` is passed to the build script as a parameter. A star matches any `PacAssignmentSelector` specified.
4141

@@ -175,7 +175,7 @@ Assignment files are hierarchical for efficient JSON definitions, avoiding dupli
175175
| `definitionEntry` | Specifies the `policyName` or `initiativeName` for the assignment. The name should not be a fully qualified `id`. `friendlyNameToDocumentIfGuid` and is purely used as a comment to make the Json more readable if the name is a GUID. | Must exist exactly once in each branch of the tree. |
176176
| `additionalRoleAssignments` | `roleDefinitionIds` are calculated from the included (direct or indirect via Initiative) Policy definition(s). Fo some Policies, such as DINE `diagnosticsSettings` the monitor destination might be in a different branch of the Management Group tree from the Assignment. This field specifies any roles requiring assignments in that MG branch. The value is an array, each element containing two items: `roleDefinitionId` and `scope` | Union of all the `additionalRoleAssignments` defined in this branch |
177177

178-
<br/>[Back to top](#policy-assignments)<br/>
178+
<br/>
179179

180180
## Details for `scope` and `notScope` Values
181181

@@ -195,7 +195,7 @@ The assignment selector determines the array being selected for this run of the
195195
| Subscription | `/subscriptions/<subscriptionId>` |
196196
| Resource Group | `/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>` |
197197

198-
<br/>[Back to top](#policy-assignments)<br/>
198+
<br/>
199199

200200
## Reading List
201201

@@ -209,7 +209,8 @@ 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)**
213+
212214
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
213215

214216
**[Return to the main page](../../README.md)**
215-
<br/>[Back to top](#policy-assignments)<br/>

‎Definitions/DocumentationSpecs/README.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Documenting Assignments and Initiatives
2+
3+
## Table of Contents
4+
5+
- [Documentation Specification Files](#documentation-specification-files)
6+
- [Example File](#example-documentation-specification-file)
7+
- [Specifying Assignment Documentation](#specifying-assignment-documentation)
8+
- [Specifying Initiative Documentation](#specifying-initiative-documentation)
9+
- [Reading List](#reading-list)
10+
11+
## Overview
12+
13+
The names of the definition Json files don't matter. reads any file in the folder with a `.json` and `.jsonc` extension.
14+
15+
Script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](../../Scripts/Operations/README.md#build-policyassignmentdocumentationps1) documents Initiatives and Assignments in your environment. It retrieves its instruction from Json files in this folder.
16+
17+
- Read and process Policy Assignments representative of an environment category, such as PROD, DEV, SANDBOX. It generates Markdown and as Excel csv files.
18+
- Read and process Initiative definitions to compare them for Policy and effect overlap. It generates Markdown and as Excel csv files. Additionaly, it generates a Json file (`.jsonc`) defining all the parameters for the union of Policies in the Initiatives. This Json file is useful when writting assignment files to copy/paste/modify the parameter values.
19+
20+
<br/>
21+
22+
## Example Documentation Specification File
23+
24+
Each file must contain one or both documentation topics. This example file has both topics. Element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the Policy and Initiative definitions are deployed.
25+
26+
- [`documentAssignments`](#specifying-assignment-documentation)
27+
- [`documentInitiatives`](#specifying-initiative-documentation)
28+
29+
<br/>
30+
31+
```jsonc
32+
{
33+
"documentAssignments": {
34+
"environmentCategories": [
35+
{
36+
"pacEnvironment": "tenant1",
37+
"environmentCategory": "PROD",
38+
"scopes": [ // Used in Markdown output only
39+
"Management Groups: Contoso-Prod"
40+
],
41+
"representativeAssignments": [
42+
{
43+
"shortName": "ASB",
44+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-Prod/providers/Microsoft.Authorization/policyAssignments/prod-asb"
45+
},
46+
{
47+
"shortName": "ORG",
48+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-Prod/providers/Microsoft.Authorization/policyAssignments/prod-org"
49+
}
50+
]
51+
},
52+
{
53+
"pacEnvironment": "tenant1",
54+
"environmentCategory": "NONPROD",
55+
"scopes": [ // Used in Markdown output only
56+
"Management Groups: Contoso-NonProd"
57+
],
58+
"representativeAssignments": [
59+
{
60+
"shortName": "ASB",
61+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-NonProd/providers/Microsoft.Authorization/policyAssignments/prod-asb"
62+
},
63+
{
64+
"shortName": "ORG",
65+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-NonProd/providers/Microsoft.Authorization/policyAssignments/prod-org"
66+
}
67+
]
68+
},
69+
{
70+
"pacEnvironment": "tenant1",
71+
"environmentCategory": "DEV",
72+
"scopes": [ // Used in Markdown output only
73+
"Management Groups: Contoso-Dev"
74+
],
75+
"representativeAssignments": [
76+
{
77+
"shortName": "ASB",
78+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-Dev/providers/Microsoft.Authorization/policyAssignments/prod-asb"
79+
},
80+
{
81+
"shortName": "ORG",
82+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-Dev/providers/Microsoft.Authorization/policyAssignments/prod-org"
83+
}
84+
]
85+
},
86+
],
87+
"documentationSpecifications": [
88+
{
89+
"fileNameStem": "contoso-PROD-policy-effects",
90+
"type": "effectsPerEnvironment",
91+
"environmentCategory": "PROD",
92+
"title": "Contoso PROD environments Policy effects"
93+
},
94+
{
95+
"fileNameStem": "contoso-NONPROD-policy-effects",
96+
"type": "effectsPerEnvironment",
97+
"environmentCategory": "NONPROD",
98+
"title": "Contoso NONPROD environment Policy effects"
99+
},
100+
{
101+
"fileNameStem": "contoso-DEV-policy-effects",
102+
"type": "effectsPerEnvironment",
103+
"environmentCategory": "DEV",
104+
"title": "Contoso DEV environment Policy effects"
105+
},
106+
{
107+
"fileNameStem": "contoso-policy-effects-across-environments",
108+
"type": "effectsAcrossEnvironments",
109+
"environmentCategories": [
110+
"PROD",
111+
"NONPROD",
112+
"DEV"
113+
],
114+
"title": "Contoso Policy effects summary"
115+
}
116+
]
117+
},
118+
"documentInitiatives": [
119+
{
120+
"pacEnvironment": "tenant1",
121+
"fileNameStem": "contoso-compliance-initiatives",
122+
"title": "Document interesting Initiatives",
123+
"initiatives": [
124+
{
125+
"shortName": "ASB",
126+
"id": "/providers/Microsoft.Authorization/policySetDefinitions/1f3afdf9-d0c9-4c3d-847f-89da613e70a8" // Azure Security Benchmark v3
127+
},
128+
{
129+
"shortName": "NIST 800-171",
130+
"id": "/providers/Microsoft.Authorization/policySetDefinitions/03055927-78bd-4236-86c0-f36125a10dc9" // NIST SP 800-171 Rev. 2
131+
},
132+
{
133+
"shortName": "NIST 800-53",
134+
"id": "/providers/Microsoft.Authorization/policySetDefinitions/179d1daa-458f-4e47-8086-2a68d0d6c38f" // NIST SP 800-53 Rev. 5
135+
},
136+
{
137+
"shortName": "ORG",
138+
"id": "/providers/Microsoft.Management/managementGroups/Contoso-Root/providers/Microsoft.Authorization/policySetDefinitions/org-security-benchmark" // Organization Security Benchmark for Custom Policies
139+
}
140+
]
141+
}
142+
]
143+
}
144+
```
145+
146+
<br/>
147+
148+
## Specifying Assignment Documentation
149+
150+
### Element `environmentCategories`
151+
152+
For any given environment category, such as PROD, NONPROD, DEV, this section list Policy Assignment which are representative deployed in thos environments. In many organization, the same Policies and effects are applied to multiple Management Groups and even Azure tenants.
153+
154+
Each `environmentCategories` entry specifies:
155+
156+
- `pacEnvironment`: references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the Policy and Initiative definitions are deployed.
157+
- `environmentCategory`: name used for column headings.
158+
- `scopes`: used in Markdown output only for the Scopes section.
159+
- `representativeAssignments`: list Policy Assignment `id`s representing this `environmentCategory`. The `shortName` is used for column headings.
160+
161+
<br/>
162+
163+
### Element `documentationSpecifications`
164+
165+
This element defines the outputs. Each entry defines the output of one (1) Markdown and one (1) csv file.
166+
167+
- `fileNameStem`: the file name without the extension (.md, .csv)
168+
- `type`: two documentation types are supported.
169+
- `effectsPerEnvironment`: requires a single `environmentCategory`
170+
- Creates a Markdown file with Policies grouped by effect, sorted by Policy category and display name with effect columns for each Initiative in the representative Assignments. The effective effect is bolded and the other allowed values are listed in the same cell one per line in italics. **No allowed values listed indicate a hard-coded effect.**
171+
- Creates a csv file with Policies sorted by Policy category and display name with effect columns for each Initiative in the representative Assignments. The effective effect is listed first and the other allowed values are listed in the same cell one per line.
172+
- `effectsAcrossEnvironments`: compares the most stringent effect from the Assignments across all `environmentCategories` listed as effect columns.
173+
- `title`: Heading 1 text for Markdown.
174+
175+
<br/>
176+
177+
## Specifying Initiative Documentation
178+
179+
Compares Policy and Initiative definitions to Initiative definitions for Policy and effect overlap as Excel csv files.
180+
181+
Creates a Markdown file with Policies sorted by Policy category and display name with effect columns for each Initiative. The Policy column starts with the bolded display Name followed by the description and lines grouped by bolded Initiative short name with the effect parameter name in italics and the group names in normal text. In the per Initiative effect columns the default effect is bolded and the other allowed values are listed in the same cell one per line in italics. **No allowed values listed indicate a hard-coded effect.**
182+
183+
Create a Json file (`.jsonc`) defining all the parameters as Json for the union of Policies in the defined Initiative Definitions sorted an collated by Policy category and Policy display name. This Json file is useful when writing assignment files. You can use them with copy/paste and modify the parameter values in your assignment file(s).
184+
185+
Each array entry defines three (3) files to be generated: Markdown, csv, and Json parameter file (.jsonc)
186+
187+
- `pacEnvironment`: references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the Policy and Initiative definitions are deployed.
188+
- `fileNameStem`: the file name without the extension (.md, .csv, .jsonc)
189+
- `title`: Heading 1 text for Markdown.
190+
- `initiatives`: list Initiatives (`id`) to be compared and included in the parameter Json file. The `shortName` is used for column headings.
191+
192+
<br/>
193+
194+
## Reading List
195+
196+
1. **[Pipeline](../../Pipeline/README.md)**
197+
198+
1. **[Update Global Settings](../../Definitions/README.md)**
199+
200+
1. **[Create Policy Definitions](../../Definitions/Policies/README.md)**
201+
202+
1. **[Create Initiative Definitions](../../Definitions/Initiatives/README.md)**
203+
204+
1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
205+
206+
1. **[Documenting Assignments and Initiatives](../../Definitions/DocumentationSpecs/README.md)**
207+
208+
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
209+
210+
**[Return to the main page](../../README.md)**
211+
<br/>

‎Definitions/Initiatives/README.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
## Initiative (Policy Set) Definition Files
1111

12-
The names of the definition JSON files don't matter, the Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of JSON with comments by using `.jsonc` instead of `.json` for the file extension.
12+
The names of the definition Json files don't matter, the Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of Json with comments by using `.jsonc` instead of `.json` for the file extension.
1313

1414
> **NOTE**:
1515
> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
@@ -26,7 +26,7 @@ The Initiative definition files are structured based on the official [Azure Init
2626
- Do not specify an `id`
2727
- Make the `effects` parameterized
2828

29-
<br/>[Back to top](#initiative-definitions)<br/>
29+
<br/>
3030

3131
## Example
3232

@@ -83,7 +83,7 @@ The Initiative definition files are structured based on the official [Azure Init
8383
}
8484
```
8585

86-
<br/>[Back to top](#initiative-definitions)<br/>
86+
<br/>
8787

8888
## Merging Built-In Initiatives
8989

@@ -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)**
105+
104106
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
105107

106108
**[Return to the main page](../../README.md)**
107-
<br/>[Back to top](#initiative-definitions)<br/>
109+
<br/>

‎Definitions/Policies/README.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@
99

1010
## Policy Definition Files
1111

12-
The names of the definition JSON files don't matter, the Policy and Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of JSON with comments by using `.jsonc` instead of `.json` for the file extension.
12+
The names of the definition Json files don't matter, the Policy and Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of Json with comments by using `.jsonc` instead of `.json` for the file extension.
1313

1414
> **NOTE**:
1515
> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
1616
1717
The Policy definition files are structured based on the official [Azure Policy definition structure](https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure) published by Microsoft. There are numerous definition samples available on Microsoft's [GitHub repository for azure-policy](https://github.com/Azure/azure-policy).
1818

19-
<br/>[Back to top](#policy-definitions)<br/>
19+
<br/>
2020

2121
## Recommendations
2222

@@ -27,7 +27,7 @@ The Policy definition files are structured based on the official [Azure Policy d
2727
- Whenever feasible, provide a `defaultValue` for parameters, especially for an `effect` parameter.
2828
- Policy aliases are used by Azure Policy to refer to resource type properties in the `if` condition and in `existenceCondition`: <https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure#aliases>.
2929

30-
<br/>[Back to top](#policy-definitions)<br/>
30+
<br/>
3131

3232
## Example
3333

@@ -68,7 +68,7 @@ The Policy definition files are structured based on the official [Azure Policy d
6868
}
6969
```
7070

71-
<br/>[Back to top](#policy-definitions)<br/>
71+
<br/>
7272

7373
## Reading List
7474

@@ -82,7 +82,8 @@ 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)**
86+
8587
1. **[Operational Scripts](../../Scripts/Operations/README.md)**
8688

8789
**[Return to the main page](../../README.md)**
88-
<br/>[Back to top](#policy-definitions)<br/>

0 commit comments

Comments
 (0)