diff --git a/Docs/changes.md b/Docs/changes.md index c9daae7f..370b363f 100644 --- a/Docs/changes.md +++ b/Docs/changes.md @@ -1,16 +1,14 @@ # Changes in v10.0.0 -!!! danger "Caution" - - Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly. +> [!CAUTION] +> Read the [breaking changes](#breaking-changes-in-v1000) carefully and adjust your environment accordingly. ## Breaking Changes in v10.0.0 ### Changes in `globalSettings.jsonc` -!!! warning - - We heavily reworked the `globalSettings.jsonc` file. You will need to update the file. +> [!WARNING] +> We heavily reworked the `globalSettings.jsonc` file. You will need to update the file. Deprecated top-level elements: diff --git a/Docs/ci-cd-github-actions.md b/Docs/ci-cd-github-actions.md index 2feba54c..63fa3685 100644 --- a/Docs/ci-cd-github-actions.md +++ b/Docs/ci-cd-github-actions.md @@ -46,9 +46,8 @@ This section is retained from the previous documentation to enable you to contin 8. For role changes when the PR is approved again the same action runs - this time using the `Deploy-RolesPlan` for deployment. 9. When complete the PR is closed and the branch containing the plan is deleted. -!!! note - - This is a sample method of deploying policy and role changes - feel free to modify it to suit your environment and contribute to this project if you want to share an update. +> [!NOTE] +> This is a sample method of deploying policy and role changes - feel free to modify it to suit your environment and contribute to this project if you want to share an update. ### Setup in GitHub -- Legacy diff --git a/Docs/epac-extracting-policy-resources.md b/Docs/epac-extracting-policy-resources.md index c3911c25..11f7601b 100644 --- a/Docs/epac-extracting-policy-resources.md +++ b/Docs/epac-extracting-policy-resources.md @@ -2,23 +2,20 @@ 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`. -!!! 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. +> [!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. The scripts creates a `Definitions` folder in the `OutputFolder` with the subfolders for `policyDefinitions`, `policySetDefinitions`, `policyAssignments` and `policyExemptions`. -!!! tip - - In a new EPAC instance these folders can be directly copied to the `Definitions` folder enabling an initial transition from a pre-EPAC to EPAC environment. +> [!TIP] +> In a new EPAC instance these folders can be directly copied to the `Definitions` folder enabling an initial transition from a pre-EPAC to EPAC environment. * `policyDefinitions`, `policySetDefinitions` have a subfolder based on `metadata.category`. If the definition has no `category` `metadata` they are put in a subfolder labeled `Unknown Category`. Duplicates when including child scopes are sorted into the `Duplicates` folder. Creates one file per Policy and Policy Set. * `policyAssignments` creates one file per unique assigned Policy or Policy Set spanning multiple Assignments. * `policyExemptions` creates one subfolder per EPAC environment -!!! warning - - The script deletes the `$outputFolders/Definitions` folder before creating a new set of files. In interactive mode it will ask for confirmation before deleting the directory. +> [!WARNING] +> The script deletes the `$outputFolders/Definitions` folder before creating a new set of files. In interactive mode it will ask for confirmation before deleting the directory. ## Use case 1: Interactive or non-interactive single tenant diff --git a/Docs/epac-implementing.md b/Docs/epac-implementing.md index 82f7730a..bc242c9e 100644 --- a/Docs/epac-implementing.md +++ b/Docs/epac-implementing.md @@ -1,8 +1,7 @@ # Implementing Enterprise Policy as Code -!!! danger "Caution" - - EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page. +> [!CAUTION] +> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](desired-state-strategy.md) page. ## Getting Started @@ -28,9 +27,8 @@ The following steps are required to implement Enterprise Policy as Code (EPAC) i ## EPAC Concepts and Environments -!!! success "Important" - - Understanding the concepts and environments is crucial. Do **not** proceed until you completely understand this section. +> [!IMPORTANT] +> Understanding the concepts and environments is crucial. Do **not** proceed until you completely understand this section. ### EPAC Concepts diff --git a/Docs/index.md b/Docs/index.md index e3712548..b5588499 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -2,13 +2,11 @@ Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scripts which can be used in CI/CD based system or a semi-automated use to deploy Policies, Policy Sets, Policy Assignments, Policy Exemptions and Role Assignments. It also contains operational scripts to simplify operational tasks. -!!! danger "Caution" +> [!CAUTION] +> v10.0.0 has breaking changes. Please review the [Changes](changes.md) document. - v10.0.0 has breaking changes. Please review the [Changes](changes.md) document. - -!!! success "Important" - - Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using [Customer Usage Attribution](https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information. +> [!IMPORTANT] +> Starting with v8.0.0, Enterprise Policy as Code (EPAC) is tracking the usage using [Customer Usage Attribution](https://learn.microsoft.com/en-us/partner-center/marketplace/azure-partner-customer-usage-attribution). In accordance with Microsoft's privacy policies, you have the right to **opt-out** of this tracking. Please review [Telemetry below](#telemetry-tracking-using-customer-usage-attribution-pid) and [Microsoft Privacy](https://privacy.microsoft.com/en-US/) for more information. ## Benefits of EPAC @@ -22,17 +20,15 @@ Enterprise Azure Policy as Code (EPAC for short) is a number of PowerShell scrip - Integration with Azure Landing Zone recommended policies - Starter Kit with examples -!!! danger "Caution" - - EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](settings-desired-state.md) page. +> [!CAUTION] +> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will **delete any Policy resources not defined in the EPAC repo**. This behavior can be modified as documented in the [desired state strategy](settings-desired-state.md) page. ## Who Should use EPAC? EPAC is designed for medium and large organizations with a larger number of Policies, Policy Sets and Assignments and/or complex deployment scenarios, such as, multiple tenants, multiple teams managing Policies. -!!! tip - - EPAC provides a mature [integration with Azure Landing Zones](integrating-with-alz.md). Utilizing [Azure Landing Zones](https://aka.ms/alz/aac) together with EPAC is highly recommended. +> [!TIP] +> EPAC provides a mature [integration with Azure Landing Zones](integrating-with-alz.md). Utilizing [Azure Landing Zones](https://aka.ms/alz/aac) together with EPAC is highly recommended. ### Smaller Organizations diff --git a/Docs/integrating-with-alz-monitor.md b/Docs/integrating-with-alz-monitor.md index 603440e1..5c10673b 100644 --- a/Docs/integrating-with-alz-monitor.md +++ b/Docs/integrating-with-alz-monitor.md @@ -2,4 +2,4 @@ For users interested in deploying the [Azure Monitor Baseline Alerts](https://azure.github.io/azure-monitor-baseline-alerts/welcome/) project with EPAC - these policies have been extracted and converted to the EPAC format and are available at the [amba-export](https://github.com/anwather/amba-export) repository. -Please review the ```README``` available in that repository for usage within EPAC. \ No newline at end of file +Please review the ```README``` available in that repository for usage within EPAC. diff --git a/Docs/integrating-with-alz.md b/Docs/integrating-with-alz.md index 072ed78a..b4c19bc6 100644 --- a/Docs/integrating-with-alz.md +++ b/Docs/integrating-with-alz.md @@ -194,17 +194,14 @@ Sync-ALZPolicies -DefinitionsRootFolder .\Definitions -CloudEnvironment AzureClo Carefully review the proposed changes before deploying them. It is best to make sure you're project is stored in source control so you can easily see which files have changed before deployment. -!!! warning +> [!WARNING] +> If you have follow Scenario 1 above, the first time you run the `Sync-ALZPolicies` there will be many changes recorded due to formatting. Review the files completely before deploying. - If you have follow Scenario 1 above, the first time you run the `Sync-ALZPolicies` there will be many changes recorded due to formatting. Review the files completely before deploying. +> [!WARNING] +> Assignments deployed via the ALZ accelerators are kept in sync with the EnterprisePolicyAsCode module so ensure you have the latest PowerShell module installed before running `Sync-ALZPolicies` -!!! warning - - Assignments deployed via the ALZ accelerators are kept in sync with the EnterprisePolicyAsCode module so ensure you have the latest PowerShell module installed before running `Sync-ALZPolicies` - -!!! tip - - Rename or copy the default ALZ assignment files - when you do a sync it makes it easier to compare changes. +> [!TIP] +> Rename or copy the default ALZ assignment files - when you do a sync it makes it easier to compare changes. ## Keeping up to date with GitHub Actions diff --git a/Docs/integrating-with-slz.md b/Docs/integrating-with-slz.md index d128195f..90da109f 100644 --- a/Docs/integrating-with-slz.md +++ b/Docs/integrating-with-slz.md @@ -2,4 +2,4 @@ For users interested in deploying the [Sovereignty Policy Baseline](https://github.com/Azure/sovereign-landing-zone/blob/main/docs/scenarios/Sovereignty-Policy-Baseline.md) project with EPAC - these policies have been extracted and converted to the EPAC format and are available at the [spb-export](https://github.com/anwather/spb-export) repository. -Please review the ```README``` available in that repository for usage within EPAC. \ No newline at end of file +Please review the ```README``` available in that repository for usage within EPAC. diff --git a/Docs/policy-assignments-csv-parameters.md b/Docs/policy-assignments-csv-parameters.md index bd4370d3..5af0be78 100644 --- a/Docs/policy-assignments-csv-parameters.md +++ b/Docs/policy-assignments-csv-parameters.md @@ -5,9 +5,8 @@ Assigning single or multiple security and compliance focused Policy Sets (Initia To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a spreadsheet (CSV) to create `parameters`, `overrides` and optionally `nonComplianceMessages` for a single Policy assignment `definitionEntry` or multiple Policy definitions (`definitionEntryList`). -!!! tip - - This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`. +> [!TIP] +> This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`. ## Generate the CSV File @@ -32,9 +31,8 @@ The CSV file generated contains the following headers/columns: * `Parameters` can contain additional parameters. You can also specify such parameters in JSON. EPAC will use the union of all parameters. * `nonComplianceMessages` column is optional. The documentation script does not generate this columns. -!!! note - - Additional columns are allowed and ignored by EPAC. +> [!NOTE] +> Additional columns are allowed and ignored by EPAC. EPAC will find the effect parameter name for each Policy in each Policy Set and use them. If no effect parameter is defined by the Policy Set, EPAC will use `overrides` to set the effect. EPAC will generate the `policyDefinitionReferenceId` for `nonComplianceMessages`. @@ -133,6 +131,5 @@ If a Policy is added to a Policy Set, add the row manually to the CSV file. The Better, [regenerate the CSV file from the deployed Policy Assignments](operational-scripts-documenting-policy.md#assignment-documentation). This will ensure that all Policies are included in the CSV file. However, this does not generate the `nonComplianceMessages` column or any additional columns you added. -!!! note - - We have planned to add a feature to generate the CSV file from the Policy Assignments and merge them with your existing CSV File to preserve extra columns. \ No newline at end of file +> [!NOTE] +> We have planned to add a feature to generate the CSV file from the Policy Assignments and merge them with your existing CSV File to preserve extra columns. diff --git a/Docs/policy-assignments.md b/Docs/policy-assignments.md index 7b0a19ec..5dad8e59 100644 --- a/Docs/policy-assignments.md +++ b/Docs/policy-assignments.md @@ -47,9 +47,8 @@ To utilize the schema add a ```$schema``` tag to the JSON file. - Role Assignments for user-assigned Managed Identities (UAMI) are not managed by EPAC, and will not generate a `roles-plan.json` file. - `additionalRoleAssignments` are used when a resource required is not in the current scope. For example, a Policy Assignment that requires a Event Hub to be managed in a subscription not contained in the current management group. -!!! tip - - The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases. +> [!TIP] +> The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases. ## Assignment Element and Metadata @@ -65,9 +64,8 @@ Each Assignment is required to have a `name` which is used in it's resource id. Multiple `assignment` naming components in a tree branch are string concatenated for each of the three fields. -!!! warning - - Azure has a limit of 24 characters for the concatenated `name` string. EPAC displays an error if this limit is exceeded. +> [!WARNING] +> Azure has a limit of 24 characters for the concatenated `name` string. EPAC displays an error if this limit is exceeded. ### Defining `metadata` @@ -276,9 +274,8 @@ Assigning single or multiple security and compliance focused Policy Sets (Initia To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a spreadsheet (CSV) to create `parameters`, `overrides` and optionally `nonComplianceMessages` for a single Policy assignment `definitionEntry` or multiple Policy definitions (`definitionEntryList`). -!!! tip - - This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`. +> [!TIP] +> This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON `parameters`, `overrides` and `nonComplianceMessages`. Implement these steps as documented in [Managing Policy Assignment Parameters with a CSV file](policy-assignments-csv-parameters.md). @@ -289,9 +286,8 @@ Implement these steps as documented in [Managing Policy Assignment Parameters wi ### Defining `parameters` with JSON -!!! warning - - `parameters` have a simplified JSON structure. You do not need the additional `value` indirection Azure requests (EPAC will inject that indirection). +> [!WARNING] +> `parameters` have a simplified JSON structure. You do not need the additional `value` indirection Azure requests (EPAC will inject that indirection). ```json "parameters": { @@ -307,9 +303,8 @@ Implement these steps as documented in [Managing Policy Assignment Parameters wi }, ``` -!!! note - - Too enable `definitionEntryList`, parameters not present in the Policy or Policy Set definition are quietly ignored. +> [!NOTE] +> Too enable `definitionEntryList`, parameters not present in the Policy or Policy Set definition are quietly ignored. ## Advanced Elements diff --git a/Docs/policy-exemptions.md b/Docs/policy-exemptions.md index 961c8f34..691d82c8 100644 --- a/Docs/policy-exemptions.md +++ b/Docs/policy-exemptions.md @@ -31,9 +31,8 @@ To utilize the schema add a ```$schema``` tag to the JSON file. ## Defining Exemptions -!!! tip - - In v10.0.0, exemptions can be defined by specifying the Policy definition Ids or Names instead of Policy Assignment Ids. This significantly reduces the complexity of defining exemptions for Policy Sets with overlapping Policy definitions. **We recommend using Policy definition Ids or Names for new exemptions.** +> [!TIP] +> In v10.0.0, exemptions can be defined by specifying the Policy definition Ids or Names instead of Policy Assignment Ids. This significantly reduces the complexity of defining exemptions for Policy Sets with overlapping Policy definitions. **We recommend using Policy definition Ids or Names for new exemptions.** Each exemption must define the following properties: - `name` - unique name, we recommend a GUID. diff --git a/Docs/settings-desired-state.md b/Docs/settings-desired-state.md index a97cdc1e..a6cf8464 100644 --- a/Docs/settings-desired-state.md +++ b/Docs/settings-desired-state.md @@ -1,8 +1,7 @@ # Desired State Management -!!! danger "Caution" - - EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will delete any Policy resources not defined in the EPAC repo. +> [!CAUTION] +> EPAC is a true desired state deployment technology. It takes possession of all Policy Resources at the `deploymentRootScope` and its children. It will delete any Policy resources not defined in the EPAC repo. Desired State strategy enables you to adjust the default behavior to fit more complex scenarios, including shared responsibility scenarios. The use cases below show the archetypical use cases. For complex scenarios it is possible to combine multiple use cases. @@ -57,9 +56,8 @@ After short transitioning period (weeks), it is recommended to set `desiredState ## Exclude Resource Groups -!!! warning - - **Breaking Change in v10.0.0:** Policy Assignments at resource groups are **managed** by EPAC. The element `includeResourceGroups` has been deprecated and removed. +> [!WARNING] +> **Breaking Change in v10.0.0:** Policy Assignments at resource groups are **managed** by EPAC. The element `includeResourceGroups` has been deprecated and removed. To exclude resource groups from management by EPAC, add an `excludedScopes` array element with a wild card for the subscription and resourceGroups to `desiredState`. @@ -111,9 +109,8 @@ The hierarchical model allows a central team to manage the commonality while giv This is managed identical to use case 3. -!!! danger "Caution" - - Previously, it was possible for a solution at a child scope to inherit Policy definitions form EPAC-A. This feature has been removed in v10.0.0 since it was not possible to manage the dependencies between Policy and Policy Set definitions and Policy Assignments correctly. +> [!CAUTION] +> Previously, it was possible for a solution at a child scope to inherit Policy definitions form EPAC-A. This feature has been removed in v10.0.0 since it was not possible to manage the dependencies between Policy and Policy Set definitions and Policy Assignments correctly. > > To replicate the previous functionality, copy/replicate the custom Policy and Policy Set definitions files from EPAC-A repo to EPAC-C repo. diff --git a/Docs/settings-dfc-assignments.md b/Docs/settings-dfc-assignments.md index c5aab60f..f8826ea7 100644 --- a/Docs/settings-dfc-assignments.md +++ b/Docs/settings-dfc-assignments.md @@ -4,9 +4,8 @@ Defender for Cloud (DFC) is a suite of Azure Security Center (ASC) capabilities ## Defender for Cloud Assignments for Defender Plans -!!! note - - DfC manages the Policy Assignments for Defender Plans when a plan is enabled. EPAC v9.0.0 and later **never** manage these Policy Assignments. +> [!NOTE] +> DfC manages the Policy Assignments for Defender Plans when a plan is enabled. EPAC v9.0.0 and later **never** manage these Policy Assignments. ![image.png](Images/dfc-defender-plans-settings.png) @@ -16,9 +15,8 @@ DfC automatically assigns `Microsoft cloud security benchmark` to each new subsc These Assignments are enabled/created at the subscription level or at management group level. Since these Policies are set to to `Audit` and you will want to set many of them to `Deny`, it is recommended that EPAC manages them at the management group level. This is the default behavior. -!!! warning - - EPAC behavior for Security Policy **is controlled by** the `keepDfcSecurityAssignments` in `desiredState`. +> [!WARNING] +> EPAC behavior for Security Policy **is controlled by** the `keepDfcSecurityAssignments` in `desiredState`. - If set to `true` or `strategy` is `ownedOnly`, EPAC will **not** remove "DfC Security Policy Assignments" created by Defender for Cloud. - If **omitted** or **set to `false`** and `strategy` is `full`, EPAC will remove "DfC Security Policy Assignments" created by Defender for Cloud.