DfC Assignments strategy change (#452)

Docs/code-promotion-module-release-process.md

@@ -0,0 +1,64 @@
+# EPAC Development to Production Promotion Process
+
+A guide for maintainers on how to move internal EPAC development (ADO) to production (GitHub).
+
+Assumption: You have completed PR in for EPAC Development in ADO ([https://secinfra.visualstudio.com/\_git/epac-development](https://secinfra.visualstudio.com/_git/epac-development)) and are ready to release to public GitHub EPAC project.
+
+You are using known local path names for EPAC Development repo and GitHub repo, for example:
+
+EPAC Development local repo: `C:\GitRepoClones\epac-development`
+EPAC GitHub local repo: `C:\GitRepoClones\enterprise-azure-policy-as-code`
+
+## Code Promotion Process
+
+1. Create a branch in GitHub ([https://github.com/Azure/enterprise-azure-policy-as-code](https://github.com/Azure/enterprise-azure-policy-as-code)).
+
+2. Update local production repo with content from local development repo. In local VS code repo for EPAC GitHub, open terminal:
+   `PS C:\GitRepoClones\enterprise-azure-policy-as-code> .\Sync-ToGH.ps1`.
+
+3. Commit changes and sync.
+
+4. Go to [https://github.com/Azure/enterprise-azure-policy-as-code](https://github.com/Azure/enterprise-azure-policy-as-code), go to `Compare and Pull Request`
+
+5. Add PR title and create PR.
+
+6. Complete GitHub Review and merge PR process.
+
+7. Delete branch from GitHub.
+
+8. Go to VSCode for EPAC Release (GitHub) (ex `C:\GitRepoClones\enterprise-azure-policy-as-code`) In Source Control, select main branch. Move to Remotes and fetch, then sync changes.
+
+9. Move to branches, delete local branch (force delete may be required).
+
+10. Open terminal, type `git remote prune origin`
+
+# Module Release Process
+
+This is a guide on how to release a new version of the project - including automated PowerShell module publish. It is used by the EPAC maintainers only.
+
+## GitHub Release Process
+
+1. Navigate to https://github.com/Azure/enterprise-azure-policy-as-code/releases
+2. Click on **Draft a new release**
+3. Click on **Choose a tag** and enter in the new release version - it should be in the format "v(major).(minor).(build)" i.e. v7.3.4 **Don't forget the v**
+4. When prompted click on **Create new tag: vX.X.X on publish**
+5. Add a release title - you can just use the new version number.
+6. Click on **Generate release notes** to pull all the notes in from related PRs. Update if necessary.
+7. Click **Publish Release**
+
+Now just verify the module publish action has run
+
+## Verify Action
+
+1. Click on **Actions**
+2. Verify that a workflow run has started with the same name as the release.
+
+It should finish successfully - if there is a failure review the build logs.
+
+# Documentation Release Process
+
+A guide for maintainers on how to update documentation..
+
+1. Modify files in the Docs folder following the format of other files. For a list of acceptable admonitions please see [here](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)
+2. If you are adding a new file ensure it is added to the `mkdocs.yml` file in the appropriate section. Use the built site to determine where a new document should be placed.
+3. Create a PR and merge - the actions will commence automatically. There are two actions which run in the background to update the GitHub Pages site.

Docs/desired-state-strategy.md

@@ -1,6 +1,6 @@
 # Desired state strategy
 
-Desired State strategy enables shared responsibility scenarios. the following documents the archetypical use cases. For complex scenarios it is possible to combine multiple use cases (e.g., Use case 2a and 3, use case 1 and 2a, ...).
+Desired State strategy enables shared responsibility scenarios. the following documents the archetypical use cases. For complex scenarios it is possible to combine multiple use cases.
 
 ## Use Case 1: Centralized Team
 

Docs/dfc-assignments.md

@@ -0,0 +1,38 @@
+# Managing Defender for Cloud Assignments
+
+Defender for Cloud (DFC) is a suite of Azure Security Center (ASC) capabilities that helps you prevent, detect, and respond to threats. It provides you with integration of Microsoft's threat protection technology and expertise. For more information, see [Azure Defender for Cloud](https://docs.microsoft.com/en-us/azure/security-center/defender-for-cloud).
+
+## Behavior of EPAC Prior to v9.0.0
+
+Defender for Cloud uses Azure Policy Assignments to enable and configure the various capabilities. These assignments are created at the subscription level.
+
+* Policy Assignments required for [Defender plans](#defender-for-cloud-settings-for-defender-plans) (e.g., SQL, App Service, ...)
+* Policy Assignments required for [Security policies](#defender-for-cloud-settings-for-security-policy-sets) (e.g., Microsoft Cloud Security Benchmark, NIST 800-53 Rev 5, NIST 800-171, ...)
+
+Prior to v9.0.0 of EPAC, Defender for Cloud Assignments were removed by EPAC. This was a problem for Microsoft's customers, especially for Defender Plans. 
+
+## Revised behavior of EPAC Starting with v9.0.0:
+
+* EPAC **no longer manages** Defender for Cloud Assignments required for Defender Plans. 
+* EPAC behavior for Security Policy **is controlled by** the `keepDfcSecurityAssignments` in `desiredState` setting per `pacEnvironment` in `global-settings.jsonc`.
+    * If set to `true`, EPAC will **not** remove Security Policy Set Assignments created by Defender for Cloud.
+    * If **omitted** or **set to `false`**, EPAC will remove Security Policy Set Assignments created by Defender for Cloud.
+
+    ```json
+    "desiredState": {
+        "strategy": "full",
+        "keepDfcSecurityAssignments": true
+    }
+    ```
+
+**Security Policies should be manged by EPAC at the Management Group level.**; This is the recommended approach for managing Security Policies instead of relying on the auto-assignments.
+
+## Defender for Cloud Settings
+
+### Defender for Cloud settings for Defender Plans
+
+![image.png](Images/dfc-defender-plans-settings.png)
+
+### Defender for Cloud settings for Security Policy Sets
+
+![image.png](Images/dfc-security-policy-sets-settings.png)

Docs/index.md

@@ -37,9 +37,14 @@ You have the right and means to **opt-out**; see [Usage Tracking](usage-tracking
 - [Azure Enterprise Policy as Code – A New Approach](https://techcommunity.microsoft.com/t5/core-infrastructure-and-security/azure-enterprise-policy-as-code-a-new-approach/ba-p/3607843)
 - [Azure Enterprise Policy as Code – Azure Landing Zones Integration](https://techcommunity.microsoft.com/t5/core-infrastructure-and-security/azure-enterprise-policy-as-code-azure-landing-zones-integration/ba-p/3642784)
 
-## Microsoft's Security & Compliance for Cloud Infrastructure
+## EPAC and Defender for Cloud Assignments
 
-This `enterprise-policy-as-code` **(EPAC)** repo has been developed in partnership with the Security & Compliance for Cloud Infrastructure (S&C4CI) offering available from Microsoft's Industry Solutions (Consulting Services). Microsoft Industry Solutions can assist you with securing your cloud. S&C4CI improves your new or existing security posture in Azure by securing platforms, services, and workloads at scale.
+Defender for Cloud uses Azure Policy Assignments to enable and configure the various capabilities. Prior to v9.0.0 of EPAC removed these subscription-level assignments.
+
+* Policy Assignments required for Defender plans (e.g., SQL, App Service, ...). These is no longer managed (removed) by EPAC v9.0.0 and later.
+* Policy Assignments required for Security policies (e.g., Microsoft Cloud Security Benchmark, NIST 800-53 Rev 5, NIST 800-171, ...). The defult `desiredState` behavior is to manage (remove) these assignments. Setting `keepDfcSecurityAssignments` to `true` disables the management (removal) by EPAC.
+
+Carefully review [Managing Defender for Cloud Assignments](dfc-assignments.md) .
 
 ## Terminology
 

Schemas/global-settings-schema.json

@@ -47,6 +47,9 @@
                                 "includeResourceGroups": {
                                     "type": "boolean"
                                 },
+                                "keepDfcSecurityAssignments": {
+                                    "type": "boolean"
+                                },
                                 "excludedScopes": {
                                     "type": "array",
                                     "items": [