update Terraform modules and docs

.devcontainer/Dockerfile

@@ -6,15 +6,15 @@ FROM ubuntu:20.04
 ENV DEBIAN_FRONTEND=noninteractive
 
 # Terraform, providers and tflint versions
-ARG TERRAFORM_VERSION=1.0.3
-ARG AZURERM_VERSION=2.69.0
+ARG TERRAFORM_VERSION=1.0.6
+ARG AZURERM_VERSION=2.76.0
 ARG RANDOM_VERSION=3.1.0
 ARG TIME_VERSION=0.7.2
-ARG TFLINT_VERSION=0.30.0
-ARG TFLINT_AZURERM=0.11.0
+ARG TFLINT_VERSION=0.32.1
+ARG TFLINT_AZURERM=0.13.1
 
 # Azure CLI version
-ARG AZURE_CLI_VERSION=2.26.1-1~focal
+ARG AZURE_CLI_VERSION=2.28.0-1~focal
 
 # Update distro (software-properties-common installs the add-apt-repository command)
 RUN apt-get update \

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# This group is the default set of reviewers for PRs to main.
+@Azure/mission-lz-reviewers

.github/ISSUE_TEMPLATE/issue.md → .github/ISSUE_TEMPLATE/backlog_item.md

@@ -1,6 +1,6 @@
 ---
-name: Issue
-about: Use issues for planned work
+name: Backlog item
+about: Use backlog items for planned work
 title: ''
 labels: ''
 assignees: ''
@@ -15,4 +15,4 @@ assignees: ''
 
 **Acceptance Criteria**
 - 
--
+- 

.gitignore

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
+
 # Terraform artifacts
 *.tfvars
 *.terraform
@@ -9,48 +10,13 @@ terraform-provider-azurerm_v*
 terraform-provider-random_v*
 *.terraform.lock.hcl
 
-# Setup config variables file
-mlz.config
-saca-hub.tfvars.json
-tier-0.tfvars.json
-tier-1.tfvars.json
-tier-2.tfvars.json
-globals.tfvars.json
-*.tfvars.json
-!*.orig.tfvars.json
+# Terraform logs
+crash.log
 
-# Bash artifacts
-*.vars
+# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
+# example: *tfplan*
+*plan*
+*.plan*
 
 # Mac files
 .DS_Store
-
-# .NET Core
-project.lock.json
-project.fragment.lock.json
-artifacts/
-**/Properties/launchSettings.json
-
-# NuGet Packages
-*.nupkg
-# The packages folder can be ignored because of Package Restore
-**/[Pp]ackages/*
-# except build/, which is used as an MSBuild target.
-!**/[Pp]ackages/build/
-# Uncomment if necessary however generally it will be regenerated when needed
-#!**/[Pp]ackages/repositories.config
-# NuGet v3's project.json files produces more ignorable files
-*.nuget.props
-*.nuget.targets
-
-# Python Tools for Visual Studio (PTVS)
-__pycache__/
-*.pyc
-**/.idea/
-**/config_output/
-**/exec_output
-
-# ignore generated output
-**/generated-configurations/*
-mlz.zip
-mlz.tar

CONTRIBUTING.md

@@ -51,8 +51,8 @@ These roles demonstrate how we think about doing the work. A single person can o
 
 ### Artifacts
 
-- Product backlog: The product backlog is defined using GitHub issues. Issue templates are in the repo for Issues (new development) and bugs. Backlog items (issues and bugs) are grouped into releases and prioritized within each release. See the [product owner process](#product-owner-process) for more details.
-- Monthly releases: Each release is defined using a GitHub project. One release is finished each month. We plan major themes for each release, but the actual content of a finished release depends on what is accomplished using our Kanban process.
+- Product backlog: The product backlog is defined using GitHub issues. [Issue templates](.github/ISSUE_TEMPLATE) are in the repo for [backlog items (new development) and bugs](https://github.com/Azure/missionlz/issues/new/choose). Issues are grouped into releases and prioritized within each release. See the [product owner process](#product-owner-process) for more details.
+- Monthly releases: Each release is defined using a GitHub project. GitHub projects are visible on the [Projects](https://github.com/Azure/missionlz/projects) tab of the GitHub site. One release is finished each month. We plan major themes for each release, but the actual content of a finished release depends on what is accomplished using our Kanban process.
 - Software increment: Each change to the software is implemented as a git commit to the main branch. GitHub pull requests are used to define and review each commit to main as a squashed merge (all changes combined into a single commit.) See the [development process](#development-process) for more details.
 
 ### Events
@@ -64,9 +64,9 @@ These roles demonstrate how we think about doing the work. A single person can o
 
 ### Development Process
 
-#### Select an Issue
+#### Select a Backlog Item
 
-Team members select issues to develop. More than one member can work on a single issue, and pair programming and other collaboration is encouraged. Generally, issues that have higher priority should be done before lower priority issues, but any issue may be selected from the backlog by any team member.
+Team members select backlog items or bugs to develop. More than one member can work on a single issue, and pair programming and other collaboration is encouraged. Generally, issues that have higher priority should be done before lower priority issues, but any issue may be selected from the backlog by any team member.
 
 #### Create a Branch
 
@@ -86,9 +86,11 @@ Multiple PRs can be created for an issue, but there is usually a single pull req
 
 A draft PR can be used to request feedback from the team.
 
+A [`CODEOWNERS`](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-code-owners) file defines the set of default reviewers for PRs to main.
+
 #### Review Other PRs
 
-When PRs are requested, review each change and run full test deployment, specifically focused on the areas that have changed. Provide comments and feedback directly related to the PR.
+When PRs are requested, review each change and run a full test deployment, specifically focused on the areas that have changed. Provide comments and feedback directly related to the PR.
 
 #### Ensure Quality
 
@@ -98,24 +100,20 @@ The main branch is always production quality. The PR reviewer is responsible for
 
 #### Product Backlog
 
-The backlog is defined in the form of GitHub issues, including bugs and regular issues. Any team member or external stakeholder can author a backlog item. The product owner is responsible for ensuring that all backlog items in a release meet the standards of being ready for development. The standards include:
+The backlog is defined in the form of GitHub issues, including bugs and backlog items. Any team member or external stakeholder can author a backlog item. The product owner is responsible for ensuring that all backlog items in a release meet the standards of being ready for development. The standards include:
 
 - A clear title
-- A concise benefit/result/outcome that defines the benefit someone would receive when the issue is completed.
+- A concise benefit/result/outcome that defines the benefit someone would receive when the issue is completed
 - An optional tag that defines who will benefit from the issue being completed
-- A detailed description that contains more context and may contain implementation details.
-- A full list of acceptance criteria that clearly define when the issue is complete.
-- Scope that is as small as possible and is also a complete and useful new feature for a stakeholder.
+- A detailed description that contains more context and may contain implementation details
+- A full list of acceptance criteria that clearly define when the issue is complete
+- Scope that is as small as possible and is also a complete and useful new feature for a stakeholder
 
 #### Triage
 
 The product owner is responsible for ensuring that each issue is fully triaged and is either closed or added to a release backlog. Triage with the team primarily happens at the weekly planning meeting and can also happen via GitHub as comments within an issue.
 
-When new issues are added to the GitHub issues list, the product owner makes sure that a `needs triage` label is added so that the issue will be discussed in the next planning meeting.
-
-#### Release Definition
-
-The product owner defines the releases in the form of GitHub projects. One release is defined per month. Each release has one or more themes. The themes are reviewed and agreed upon by the team during the weekly planning meeting.
+When new issues are added to the GitHub issues list, the product owner ensures that a `needs triage` label is added so that the issue will be discussed in the next planning meeting.
 
 #### Weekly Planning Meeting
 
@@ -128,10 +126,14 @@ The product owner sets the agenda for the meeting. The agenda includes:
 
 #### Backlog Prioritization
 
-The product owner is responsible for ensuring that the backlog items are prioritized within each release. Setting priority is a collaborative effort by the team. Priority is defined by the stack rank order of the "To do" column in a release.
+The product owner is responsible for ensuring that the backlog items are prioritized within each release. Setting priority is a collaborative effort by the team and usually happens during the weekly planning meeting. Priority is defined by the stack rank order of the "To do" column in a release.
 
 #### Architecture
 
 The product owner is responsible for ensuring that enough architecture documentation exists for the development team and stakeholders. Developing the architecture is a collaborative effort with the rest of the team. Any team member may contribute to the architecture, and some issues may be added to the backlog for discovery and testing in order to determine the elements of the architecture.
 
+#### Release Definition
+
+The product owner defines the releases in the form of GitHub projects. One release is defined per month. Each release has one or more themes. The themes are reviewed and agreed upon by the team during the weekly planning meeting.
+
 **Thank You!** - Your contributions to open source, large or small, make projects like this possible. Thank you for taking the time to contribute.

docs/policies.md

@@ -0,0 +1,92 @@
+# Mission Landing Zone Regulatory Compliance - NIST Policies
+
+As part of Mission Landing Zone (MLZ) it's been a goal to ensure deployments have the tools and resources available that allow it to be compliant with most regulations across industries. This does not mean that workloads are compliant, but it does mean that the technologies in use can be compliant. This is caused by not only the varying number of compliance bodies involved and and the regulations they mandate but also caused by the decisions required by how and what controls are followed.
+
+For the purposes of this documentation we created an example method in which the MLZ deployment can be audited for current National Institute of Standards and Technology (NIST) controls and requirements using [Azure Policies built in initiative](https://docs.microsoft.com/en-us/azure/governance/policy/samples/nist-sp-800-53-r4) for NIST 800-53. _Note: this is focused on NIST controls that have built in policies in Azure clouds._
+
+![Policy and the MLZ deployment footprint](images/20210419_missionlz_as_of_Aug2021_Policy.png)
+
+## Known Issues
+
+Currently there are a set of known issues with this approach. The first and somewhat important detail is that these policies are based on built in policies available in the different Azure environments. There are some variances currently between clouds. This will always happen when separate isolated environments have different deployment cycles but also can be based on preview testing versus generally available components in one cloud environment versus another.
+
+A secondary issue comes from the method in which the assignment is deployed. This results in 'out of band' requirements for customers. In particular, the current built-in NIST initiative has a couple policies attached that modify and/or deploy if a resource doesn't exist. Example, VM extensions for guest policy configuration would be deployed if they don't exist in the VM. These types of policies require a managed identity be created that the Policy engine can use to take these actions. This managed identity must have contributor access to the resources but deploying as a contributor and not owner limits the ability. The terraform MLZ deployment as it is today using service principles with contributor rights cannot make this role assignment but the managed identity is created. This is by design for security purposes.
+
+The final note is that these are audits based on NIST controls and recommendations that will require out of band work. As an example, storage account redundancy and encryption will require a decision process on what MLZ is using as temporary storage for logs versus requirements for the workloads. For example, encryption can be accomplished with multiple key models, which one is required for what category of data?
+
+## Deploying
+
+Deploying policy assignments for NIST along with a standard deployment of MLZ is simple and described below. This example will add a separate assignment of the built in NIST initiative per resource group in the deployment.
+
+### Deploying with Bicep
+
+To include one of the built in Azure policy initiatives for NIST 800-53, CMMC Level 3 or DoD IL5 compliance add the parameter with one of the following, NIST, IL5 or CMMC. For example:
+
+```plaintext
+az deployment sub create \
+  --location eastus \
+  --template-file mlz.bicep \
+  --parameters policy=<one of 'CMMC', 'IL5', or 'NIST'>
+```
+
+Or, you can apply policy after deploying MLZ:
+
+```plaintext
+az deployment group create \
+  --resource-group <Resource Group to assign> \
+  --name <original deployment name + descriptor> \
+  --template-file ./src/bicep/modules/policyAssignment.bicep \
+  --parameters builtInAssignment=<one of 'CMMC', 'IL5', or 'NIST'> logAnalyticsWorkspaceName=<Log analytics workspace name> \
+  --parameters logAnalyticsWorkspaceName=<Log Analytics Workspace Name> \
+  --parameters logAnalyticsWorkspaceResourceGroupName=<Log Analytics Workspace Resource Group Name>
+```
+
+### Deploying with Terraform
+
+By default, the Terraform implementaiton at `src/terraform/mlz/main.tf` will assign the NIST 800-53 policies. You can disable this by providing a `false` value to the `create_policy_assignment` variable:
+
+```plaintext
+cd src/terraform/mlz
+terraform init
+terraform apply -var="create_policy_assignment=false"
+```
+
+After the resources are deployed, you will need to go into go into each assignment and retrieve the managed identity and modify its role access to contributor scoped to the associated resource group. This is due to the initiative including modify and deploy policies that act on resources, like deploying the require policy guest configuration extensions to VMs.
+
+## Modifying
+
+### Modifying with Bicep
+
+The project stores well-known policies at [src/bicep/modules/policies](../src/bicep/modules/policies) where JSON files named for the initiatives with default parameters (except for a Log Analytics workspace ID value `<LAWORKSPACE>` that we substitute at deployment time -- any other parameter can be modified as needed).
+
+### Modifying with Terraform
+
+This project uses a custom terraform module called 'policy-assignments'. This can be modified for adding additional initiatives if desired. The module deployments retrieve their parameter values from a local json file stored in the module directory named 'nist-parameter-values' and named after the cloud environment they are deploying to, public or usgovernment.
+
+Example parameters file snippet:
+
+```arm
+{
+    "listOfMembersToExcludeFromWindowsVMAdministratorsGroup": 
+    {
+      "value": "admin"
+    },
+    "listOfMembersToIncludeInWindowsVMAdministratorsGroup": 
+    {
+      "value": "azureuser"
+    },
+    "logAnalyticsWorkspaceIdforVMReporting": 
+    {
+      "value": ${jsonencode(laws_instance_id)}
+    },
+    "IncludeArcMachines": 
+    {
+        "value": "true"
+    }
+```
+
+In the above example the 'logAnalyticsWorkspaceIdforVMReporting' is retrieved from the running terraform deployment variables. This could be modified to use a central logging workspace if desired.
+
+## What's Next
+
+While this is only a start, the NIST controls included in the built-in initiatives are a good start to understanding requirements on top of MLZ for compliance. In the near future the hopes are for this to be expanded with additional built-in initiatives as well as offering an option to create your own initiative and custom policies. Potential additions will be server baselines, IL compliances, and custom policies.