Added capabilities to manage DFC Plan Policy Assignments via EPAC

Author: apybar

Docs/guidance-exemptions.md

@@ -8,7 +8,7 @@ In the past, CSV has been the preferred tool in EPAC. However, the introduction
 
 ## Updating exemptions manually
 
-There are some usecases for manual update of the exemptions file. Generally, it is a consideration of what will be less effort to complete.
+There are some use cases for manual update of the exemptions file. Generally, it is a consideration of what will be less effort to complete.
 
 ### Expiration Update
 
@@ -20,7 +20,7 @@ Rather than update and export, an update to the date field can be accomplished w
 1. Open the json/jsonc/csv file used to manage Exemptions
 1. Update Content
     1. Search for the policyAssignmentId, including the full assignment path
-        1. Example: ```"policyAssignmentId": "/providers/Microsoft.Management/managementGroups/[ManagmenetGroupName]/providers/Microsoft.Authorization/policyAssignments/[PolicyAssignmentName]"```
+        1. Example: ```"policyAssignmentId": "/providers/Microsoft.Management/managementGroups/[ManagementGroupName]/providers/Microsoft.Authorization/policyAssignments/[PolicyAssignmentName]"```
     1. Modify the ```expiresOn``` field within the related block with the new timestamp
         1. Format: "YYYY-MM-DDTmm:hh:ssZ"
         1. Example: "2025-01-01T01:00:00Z"
@@ -37,7 +37,7 @@ In these cases, find each listing for affected assignments in the CSV/JSON file,
 
 1. Export Current Exemptions for pacSelector
 1. Update Content
-    1. Replace Root Management Group Name (Tenant GUID) with current assignment location (Tenant Intermediate Root Managment Group Name):
+    1. Replace Root Management Group Name (Tenant GUID) with current assignment location (Tenant Intermediate Root Management Group Name):
         1. ```"policyAssignmentId"```
         1. Epac Managed Exemptions: ```metadata\epacMetadata\"policyAssignmentId"```
     1. Replace temporary pacSelector with main pacSelector:

Docs/guidance-remediation.md

@@ -15,11 +15,11 @@ There are several different ways that policies that affect change can be deploye
     1. Allows use of Remediation Tasks for the policyAssignment even though it is disabled
     1. Considerations:
         1. Much faster, requiring little planning
-        1. Will not update new deployments, but allows remediation of existing deployments as approval is receieved
+        1. Will not update new deployments, but allows remediation of existing deployments as approval is received
         1. New-AzRemediationTasks **will** by default enforce policyAssignments with the *DoNotEnforce* configuration. It is recommended to either use the switch parameter `-OnlyDefaultEnforcementMode`, have these policyAssignments removed or set to default enforcement before that pipeline is enabled
 1. Use of Effect *Override* functionality
     1. Override can be set to any Effect that is supported by that policy
-    1. When overriding a policySet, the policyDefinitionReferenceId will be used to identify which policies recieve audit vs auditIfNotExist effect if both exist
+    1. When overriding a policySet, the policyDefinitionReferenceId will be used to identify which policies receive audit vs auditIfNotExist effect if both exist
     1. If no effects are available, an override to *audit* was accepted in all tested cases
     1. Considerations:
         1. Much more granular control, requiring review of available effects and generating a list of overrides
@@ -58,7 +58,7 @@ When this is enabled, Azure Resource Manager Configuration is being managed at o
 
 The objective at this point is to reduce the administration teams' effort to correct deployments that do not meet security standards outlined by the company by maintaining the configuration proactively, which is to say without prompting from human administrators to do so. While this *can* be a manual task, the EPAC CI/CD Pipeline for Remediation provided in the StarterKit should be leveraged for this in order to reduce the effort of the administration team.
 
-While Infrastructure as Code is an excellent first layer, the second layer in a Defense In Depth model is to enforce this. In Azure Resource Manager, we use Azure Policy Remediation Tasks to accomplish this. Whereas Start-AzPolicyRemediation does allow very targetted deployments, EPAC seeks to take corrective action in broad swaths using the security structure that has been implemented. To this end, the cmdlet New-AzRemediationTasks was created, and can be used in a pipeline to remediate all policyAssignments (that have that capability) in a single pipeline action that should be scheduled with a cron trigger.
+While Infrastructure as Code is an excellent first layer, the second layer in a Defense In Depth model is to enforce this. In Azure Resource Manager, we use Azure Policy Remediation Tasks to accomplish this. Whereas Start-AzPolicyRemediation does allow very targeted deployments, EPAC seeks to take corrective action in broad swaths using the security structure that has been implemented. To this end, the cmdlet New-AzRemediationTasks was created, and can be used in a pipeline to remediate all policyAssignments (that have that capability) in a single pipeline action that should be scheduled with a cron trigger.
 
 Once the *Updating Security Posture* Workstreams above are complete, it is time to move on into the upper tiers of CMM for ARM Governance, congratulations! The environment will be largely self-correcting after this is complete.
 

Docs/guidance-scope-exclusions.md

@@ -8,7 +8,7 @@ There are several means of excluding a scope from a policyAssignment; however, i
 
 There are several ways of accomplishing scope changes, and the logic behind these decisions is fairly straightforward. However, that does not mean that there is an objectively right answer in all cases, and these pieces of guidance should aid in choosing a path forward.
 
-In all cases, simply moving the assignments down to a more specific level could solve the problem, but it is rarely the most effecient. Certainly assigning by each Resource Group can reduce the number of exclusions, but at the cost of a fail-open configuration for new Resource Groups as well as a significantly higher number of assignments. This is rarely, if ever, preferred.
+In all cases, simply moving the assignments down to a more specific level could solve the problem, but it is rarely the most efficient. Certainly assigning by each Resource Group can reduce the number of exclusions, but at the cost of a fail-open configuration for new Resource Groups as well as a significantly higher number of assignments. This is rarely, if ever, preferred.
 
 ### Decision: Periodic Review
 
@@ -18,7 +18,7 @@ If there is a requirement to review the scope change periodically, to confirm th
 
 While a decision around the scope will determine to which scope policyAssignments are applied, there are often changes to the Effect in order to descope individual items within a policySet. In this case, NotScope is generally the focus within the policyAssignment in order to provide that level of control.
 
-Example: Exempt a workload contained within a managment group from requiring Storage to use TLS 1.2 defined in the policySet [Enforce-EncryptTransit_20241211](https://www.azadvertizer.net/azpolicyinitiativesadvertizer/Enforce-EncryptTransit_20241211.html) in order to support a legacy service which must use TLS 1.1, while retaining the enforcement for all other Services.
+Example: Exempt a workload contained within a management group from requiring Storage to use TLS 1.2 defined in the policySet [Enforce-EncryptTransit_20241211](https://www.azadvertizer.net/azpolicyinitiativesadvertizer/Enforce-EncryptTransit_20241211.html) in order to support a legacy service which must use TLS 1.1, while retaining the enforcement for all other Services.
 
 ### Decision: Scope at policyAssignment or pacSelector
 

Docs/integrating-with-alz-library.md

@@ -15,16 +15,16 @@ To use the ALZ policies in an environment successfully there are some Azure Reso
 This file contains information that drives the sync process. The file includes management group IDs, default enforcement mode, and parameter values. **It must be generated at least once before executing the sync process.**
 
 1. Ensure that the EPAC module is up to date - required minimum version to use these features is 10.9.0.
-2. Use to code to clone the library repository and create the default file. There are examples below on how to run this commnand - you will only need to run one of these depending on your requirements.
+2. Use to code to clone the library repository and create the default file. There are examples below on how to run this command - you will only need to run one of these depending on your requirements.
 
 ```ps1
 # Create a Pac Environment default file for ALZ policies using the latest release of the ALZ Library release
 New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -PacEnvironmentSelector "epac-dev"
 
-# Create a default file for ALZ policies specifiying a tagged release of the ALZ Library 
+# Create a default file for ALZ policies specifying a tagged release of the ALZ Library 
 New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -Tag "platform/alz/2025.02.0"
 
-# Create a default file for ALZ policies by provising a path to a cloned/modified library 
+# Create a default file for ALZ policies by providing a path to a cloned/modified library 
 New-ALZPolicyDefaultStructure -DefinitionsRootFolder .\Definitions -Type ALZ -LibraryPath <<path to library>>
 
 # Create a default file for AMBA policies using the latest release of the ALZ Library
@@ -89,7 +89,7 @@ Sync-ALZPolicyFromLibrary -DefinitionsRootFolder .\Definitions -Type AMBA -PacEn
 
 ```
 
-Carefully review the generated policy assigments and ensure all parameter and scope information is correct.
+Carefully review the generated policy assignments and ensure all parameter and scope information is correct.
 
 2. When complete run `Build-DeploymentPlans` to ensure the correct changes are made. During the first sync for either a new or existing environment there will be many changes due to updating of the existing policies.
 
@@ -145,7 +145,7 @@ If you need to have separate parameter values or different management group name
 
 1. Generate a policy structure file using `New-ALZPolicyDefaultStructure` and specify the `-PacEnvironmentSelector` parameter.
 
-This generates a standard file structure however the file's name will now include the Pac Selector given. This default structure will now be used everytime you run the "Sync-ALZPolicyFromLibrary" command with the matching PacEnvironmentSelector.
+This generates a standard file structure however the file's name will now include the Pac Selector given. This default structure will now be used every time you run the "Sync-ALZPolicyFromLibrary" command with the matching PacEnvironmentSelector.
 
 For example: -
 
@@ -180,7 +180,7 @@ To deploy the workload specific compliance guardrails for Azure Landing Zones th
 
 By default ALZ specifies deploying all the guardrail policies to the `platform` and `landingzones` management group and when the `Sync-ALZPolicyFromLibrary` with the `-CreateGuardrailAssignments` parameter command runs it will generate assignments which are scoped to these management groups.
 
-To modify this behaviour you can update/modify the scopes in the `deployment.scopes` entry - or if you want to deploy different guardrails to different scopes simply create another entry within the `enforceGuardrails.deployment` array similar to below.
+To modify this behavior you can update/modify the scopes in the `deployment.scopes` entry - or if you want to deploy different guardrails to different scopes simply create another entry within the `enforceGuardrails.deployment` array similar to below.
 
 ```
 "enforceGuardrails": {
@@ -254,7 +254,7 @@ The updated management group structure would follow similar to below:-
     }
 ```
 
-3. Now that the new archetypes have been added there needs to be archetype defintion files created - which tie together which assignments are associated to these archetypes. For this example we will apply the same assignments as what would have been applied to the `corp` management group to the new management groups.
+3. Now that the new archetypes have been added there needs to be archetype definition files created - which tie together which assignments are associated to these archetypes. For this example we will apply the same assignments as what would have been applied to the `corp` management group to the new management groups.
 4. In the forked repository in the folder `\platform\alz\archetype_definitions` we can copy the `corp.alz_archetype_definition.json` file twice and rename it to `non-production.alz_archetype_definition.json` and `production.alz_archetype_definition.json`. For each file update the `name` key in the file to match e.g.
 
 ```
@@ -313,3 +313,21 @@ Sync-ALZPolicyFromLibrary.ps1 -DefinitionsRootFolder .\Definitions\ -Type ALZ -L
 ```
 
 9. When maintaining parity with updates from the ALZ team including policy changes and new assignments it will be necessary to sync your forked repo and carefully check the incoming changes.
+
+### Migrating from the legacy sync process to the new sync process
+
+The process to migrate from the legacy sync process to the new process mainly involves changed to how the assignment files are generated and maintained. If the environment structure is well-aligned to the Cloud Adoption Framework the process will be fairly seamless. For environments which aren't aligned it will present a little bit more of a challenge however the initial complexity is balanced by less maintenance in the future when synchronising.
+
+## CAF Aligned
+
+Use the process [documented here](integrating-with-alz-library.md#using-the-new-azure-landing-zone-library-sync-process).
+
+Ensure that the management groups and the parameter values are updated in the newly generated structure file. When synchronising and running the build plan changes should be fairly minimal as all the assignments already exist - but any discrepancies should be examined as to why changes are being made.
+
+## CAF Unaligned
+
+Because the environment is not aligned to CAF - the sync process using the legacy method will already require a number of changes to the default assignment files. In this case it is best to maintain a [custom library](integrating-with-alz-library.md#using-a-custom-library-for-custom-management-group-structures).
+
+Carefully add the new archetypes to the cloned library - ensuring that all assignments are included.
+
+Again the sync process should be fairly simple as all the assignments already exist - however there will be more assignment files to manage. Setting up the custom library properly will ensure a seamless transition.

Docs/operational-scripts.md

@@ -58,7 +58,7 @@ Parameters:
 
 * **UseBuiltIn**: Default to using builtin policies rather than local versions.
 
-* **PacSelector**: Used to set PacEnvironment for each assignment file based on the pac selector privided. This pulls from global-settings.jsonc, therefore it must exist or an erro will be thrown.
+* **PacSelector**: Used to set PacEnvironment for each assignment file based on the pac selector provided. This pulls from global-settings.jsonc, therefore it must exist or an error will be thrown.
 
 * **OverwriteScope**: Used to overwrite scope value on each assignment file.
 

Docs/policy-definitions.md

@@ -50,7 +50,7 @@ The names of the definition JSON files don't matter, the Policy and Policy Set d
 
 ## Custom Definitions
 
-Custom definitions are uploaded to Azure at the time of initial deployment to a pacSelector. For each pacSelector, the definition is uploaded to the pacSelector's defined root. This makes it available to the entirity of that pacSelector, while facilitating code promotion by allowing each pacSelector to recieve the updated definition as part of the release/deployment process.
+Custom definitions are uploaded to Azure at the time of initial deployment to a pacSelector. For each pacSelector, the definition is uploaded to the pacSelector's defined root. This makes it available to the entirety of that pacSelector, while facilitating code promotion by allowing each pacSelector to receive the updated definition as part of the release/deployment process.
 
 ## Definition Delivery
 
@@ -85,4 +85,4 @@ It is customary to include a `category` and a `version` in the `metadata` sectio
 
 EPAC injects `deployedBy` into the `metadata` section. This is a string that identifies the deployment source. It defaults to `epac/$pacOwnerId/$pacSelector`. You can override this value in `global-settings.jsonc`
 
-**Not recommended:** Adding `deployedBy` to the `metadata` section in the Policy definition file will override the value for this definition only from `global-settings.jsonc` or default value.
+**Not recommended:** Adding `deployedBy` to the `metadata` section in the Policy definition file will override the value for this definition only from `global-settings.jsonc` or default value.

Docs/policy-set-definitions.md

@@ -56,7 +56,7 @@ The names of the definition JSON files don't matter, the Policy Sets are registe
 
 ## Custom Definitions
 
-Custom definitions are uploaded to Azure at the time of initial deployment to a pacSelector. For each pacSelector, the definition is uploaded to the pacSelector's defined root. This makes it available to the entirity of that pacSelector, while facilitating code promotion by allowing each pacSelector to recieve the updated definition as part of the release/deployment process.
+Custom definitions are uploaded to Azure at the time of initial deployment to a pacSelector. For each pacSelector, the definition is uploaded to the pacSelector's defined root. This makes it available to the entirety of that pacSelector, while facilitating code promotion by allowing each pacSelector to receive the updated definition as part of the release/deployment process.
 
 ## Policy Definition Groups
 
@@ -99,4 +99,4 @@ It is customary to include a `category` and a `version` in the `metadata` sectio
 
 EPAC injects `deployedBy` into the `metadata` section. This is a string that identifies the deployment source. It defaults to `epac/$pacOwnerId/$pacSelector`. You can override this value in `global-settings.jsonc`
 
-**Not recommended:** Adding `deployedBy` to the `metadata` section in the Policy definition file will override the value for this definition only from `global-settings.jsonc` or default value.
+**Not recommended:** Adding `deployedBy` to the `metadata` section in the Policy definition file will override the value for this definition only from `global-settings.jsonc` or default value.