Refactoring and doc updates for Key Vault (Azure#2939)

* Refactoring and doc updates for Key Vault

* Bump change log

* Updates

Author: BernieWhite

data/policy-ignore.json

@@ -78,13 +78,6 @@
     "reason": "Duplicate",
     "value": "Azure.MySQL.UseSSL"
   },
-  {
-    "policyDefinitionIds": [
-      "/providers/Microsoft.Authorization/policyDefinitions/0b60c0b2-2dc2-4e1c-b5c9-abbed971de53"
-    ],
-    "reason": "Duplicate",
-    "value": "Azure.KeyVault.PurgeProtect"
-  },
   {
     "policyDefinitionIds": [
       "/providers/Microsoft.Authorization/policyDefinitions/b6e2945c-0b7b-40f5-9233-7a5323b5cdc6"
@@ -128,13 +121,28 @@
     "reason": "Duplicate",
     "value": "Azure.KeyVault.SoftDelete"
   },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/0b60c0b2-2dc2-4e1c-b5c9-abbed971de53"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.KeyVault.PurgeProtect"
+  },
   {
     "policyDefinitionIds": [
       "/providers/Microsoft.Authorization/policyDefinitions/12d4fa5e-1f9f-4c21-97a9-b99b3c6611b5"
     ],
     "reason": "Duplicate",
     "value": "Azure.KeyVault.RBAC"
   },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/55615ac9-af46-4a59-874e-391cc3dfb490",
+      "/providers/Microsoft.Authorization/policyDefinitions/ac673a9a-f77d-4846-b2d8-a57f8e1c01dc"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.KeyVault.Firewall"
+  },
   {
     "policyDefinitionIds": [
       "/providers/Microsoft.Authorization/policyDefinitions/5d4e3c65-4873-47be-94f3-6f8b953a3598",

docs/CHANGELOG-v1.md

@@ -29,6 +29,12 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
+What's changed since pre-release v1.38.0-B0011:
+
+- Engineering:
+  - Quality updates to rule documentation by @BernieWhite.
+    [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)
+
 ## v1.38.0-B0011 (pre-release)
 
 What's changed since v1.37.0:

docs/en/rules/Azure.KeyVault.AccessPolicy.md

@@ -1,8 +1,8 @@
 ---
-reviewed: 2023-02-18
+reviewed: 2024-06-17
 severity: Important
 pillar: Security
-category: Identity and access management
+category: SE:05 Identity and access management
 resource: Key Vault
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.KeyVault.AccessPolicy/
 ---
@@ -32,15 +32,17 @@ Consider assigning access to Key Vault data based on the principle of least priv
 
 To deploy Key Vaults that pass this rule:
 
-- Avoid assigning `purge` and `all` permissions for Key Vault objects.
-  Use specific permissions such as `get` and `set`.
+- Use Azure RBAC as the authorization system instead. _OR_
+- Configure the access policies by setting `properties.accessPolicies`:
+  - Avoid assigning `purge` and `all` permissions for Key Vault objects.
+    Use specific permissions such as `get` and `set`.
 
 For example:
 
 ```json
 {
   "type": "Microsoft.KeyVault/vaults",
-  "apiVersion": "2022-07-01",
+  "apiVersion": "2023-07-01",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "properties": {
@@ -73,13 +75,15 @@ For example:
 
 To deploy Key Vaults that pass this rule:
 
-- Avoid assigning `purge` and `all` permissions for Key Vault objects.
-  Use specific permissions such as `get` and `set`.
+- Use Azure RBAC as the authorization system instead. _OR_
+- Configure the access policies by setting `properties.accessPolicies`:
+  - Avoid assigning `purge` and `all` permissions for Key Vault objects.
+    Use specific permissions such as `get` and `set`.
 
 For example:
 
 ```bicep
-resource vault 'Microsoft.KeyVault/vaults@2022-07-01' = {
+resource vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
   name: name
   location: location
   properties: {
@@ -108,8 +112,13 @@ resource vault 'Microsoft.KeyVault/vaults@2022-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/key-vault/vault accessPolicies -->
+
 ## LINKS
 
-- [Automate and use least privilege](https://learn.microsoft.com/azure/architecture/framework/security/security-principles#automate-and-use-least-privilege)
+- [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access)
+- [Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control](https://learn.microsoft.com/azure/key-vault/general/rbac-guide)
+- [Azure role-based access control vs. access policies](https://learn.microsoft.com/azure/key-vault/general/rbac-access-policy)
+- [Migrate from vault access policy to an Azure role-based access control permission model](https://learn.microsoft.com/azure/key-vault/general/rbac-migration)
 - [Best practices to use Key Vault](https://learn.microsoft.com/azure/key-vault/general/best-practices)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults)

docs/en/rules/Azure.KeyVault.AutoRotationPolicy.md

@@ -1,8 +1,8 @@
 ---
-reviewed: 2022-09-09
+reviewed: 2024-06-17
 severity: Important
 pillar: Security
-category: Key and secret management
+category: SE:09 Application secrets
 resource: Key Vault
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.KeyVault.AutoRotationPolicy/
 ---
@@ -31,8 +31,8 @@ Consider enabling auto-rotation on Key Vault keys.
 
 To set auto-rotation for a key:
 
-- Set `properties.rotationPolicy.lifetimeActions[*].action.type` to `Rotate`.
-- Set `properties.rotationPolicy.lifetimeActions[*].trigger.timeAfterCreate` to the time duration after key creation to rotate.
+- Set the `properties.rotationPolicy.lifetimeActions[*].action.type` property to `Rotate`.
+- Set the `properties.rotationPolicy.lifetimeActions[*].trigger.timeAfterCreate` property to a time duration such as `P30D`.
 
 For example:
 
@@ -80,9 +80,8 @@ For example:
 
 To set auto-rotation for a key:
 
-- Set `properties.rotationPolicy.lifetimeActions[*].action.type` to `Rotate`.
-- Set `properties.rotationPolicy.lifetimeActions[*].trigger.timeAfterCreate` to the time duration
-after key creation to rotate.
+- Set the `properties.rotationPolicy.lifetimeActions[*].action.type` property to `Rotate`.
+- Set the `properties.rotationPolicy.lifetimeActions[*].trigger.timeAfterCreate` property to a time duration such as `P30D`.
 
 For example:
 
@@ -127,7 +126,7 @@ resource vaultName_key1 'Microsoft.KeyVault/vaults/keys@2021-06-01-preview' = {
 
 ## LINKS
 
-- [Operational considerations](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-keys#operational-considerations)
+- [SE:09 Application secrets](https://learn.microsoft.com/azure/well-architected/security/application-secrets)
 - [IM-3: Manage application identities securely and automatically](https://learn.microsoft.com/security/benchmark/azure/security-controls-v3-identity-management#im-3-manage-application-identities-securely-and-automatically)
 - [Configure cryptographic key auto-rotation in Azure Key Vault](https://learn.microsoft.com/azure/key-vault/keys/how-to-configure-key-rotation)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults/keys)

docs/en/rules/Azure.KeyVault.Firewall.md

@@ -1,8 +1,8 @@
 ---
-reviewed: 2023-08-20
+reviewed: 2024-06-17
 severity: Important
 pillar: Security
-category: Application endpoints
+category: SE:06 Network controls
 resource: Key Vault
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.KeyVault.Firewall/
 ---
@@ -101,12 +101,21 @@ resource vault 'Microsoft.KeyVault/vaults@2023-02-01' = {
 }
 ```
 
+<!-- external:avm avm/res/key-vault/vault networkAcls -->
+
+### Configure with Azure Policy
+
+To address this issue at runtime use the following policies:
+
+- [Azure Key Vault should have firewall enabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/FirewallEnabled_Audit.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/55615ac9-af46-4a59-874e-391cc3dfb490`.
+- [Configure key vaults to enable firewall](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/FirewallEnabled_Modify.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/ac673a9a-f77d-4846-b2d8-a57f8e1c01dc`.
+
 ## LINKS
 
-- [Public endpoints](https://learn.microsoft.com/azure/architecture/framework/security/design-network-endpoints#public-endpoints)
+- [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)
+- [NS-2: Secure cloud services with network controls](https://learn.microsoft.com/security/benchmark/azure/baselines/key-vault-security-baseline#disable-public-network-access)
 - [Configure Azure Key Vault firewalls and virtual networks](https://learn.microsoft.com/azure/key-vault/general/network-security)
-- [Azure security baseline for Key Vault - Disable Public Network Access](https://learn.microsoft.com/security/benchmark/azure/baselines/key-vault-security-baseline#disable-public-network-access)
-- [Azure Policies - Azure Key Vault should have firewall enabled](https://www.azadvertizer.net/azpolicyadvertizer/55615ac9-af46-4a59-874e-391cc3dfb490.html)
-- [Azure Key Vault should have firewall enabled](https://portal.azure.com/#view/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2F55615ac9-af46-4a59-874e-391cc3dfb490)
 - [Trusted services](https://learn.microsoft.com/azure/key-vault/general/overview-vnet-service-endpoints#trusted-services)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults)

docs/en/rules/Azure.KeyVault.KeyName.md

@@ -1,7 +1,7 @@
 ---
 severity: Awareness
 pillar: Operational Excellence
-category: Repeatable infrastructure
+category: OE:04 Continuous integration
 resource: Key Vault
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.KeyVault.KeyName/
 ---
@@ -32,7 +32,7 @@ This rule does not check if Key names are unique.
 
 ## LINKS
 
-- [Repeatable infrastructure](https://learn.microsoft.com/azure/architecture/framework/devops/automation-infrastructure)
+- [OE:04 Continuous integration](https://learn.microsoft.com/azure/well-architected/operational-excellence/release-engineering-continuous-integration)
 - [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-name-rules#microsoftkeyvault)
-- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults/secrets)
 - [Tagging and resource naming](https://learn.microsoft.com/azure/architecture/framework/devops/app-design#tagging-and-resource-naming)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults/secrets)

docs/en/rules/Azure.KeyVault.PurgeProtect.md

@@ -93,6 +93,8 @@ resource vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/key-vault/vault enablePurgeProtection -->
+
 ### Configure with Azure CLI
 
 ```bash
@@ -109,7 +111,8 @@ Update-AzKeyVault -ResourceGroupName '<resource_group>' -Name '<name>' -EnablePu
 
 To address this issue at runtime use the following policies:
 
-- [Key vaults should have deletion protection enabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/KeyVault_Recoverable_Audit.json)
+- [Key vaults should have deletion protection enabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/Recoverable_Audit.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/0b60c0b2-2dc2-4e1c-b5c9-abbed971de53`.
 
 ## LINKS
 

docs/en/rules/Azure.KeyVault.RBAC.md

@@ -92,6 +92,8 @@ resource vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/key-vault/vault enableRbacAuthorization -->
+
 ### Configure with Azure CLI
 
 ```bash
@@ -108,7 +110,8 @@ Update-AzKeyVault -ResourceGroupName '<resource_group>' -Name '<name>' -EnableRb
 
 To address this issue at runtime use the following policies:
 
-- [Azure Key Vault should use RBAC permission model](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/AzureKeyVault_Should_Use_RBAC.json)
+- [Azure Key Vault should use RBAC permission model](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/Should_Use_RBAC.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/12d4fa5e-1f9f-4c21-97a9-b99b3c6611b5`.
 
 ## NOTES
 
@@ -119,11 +122,11 @@ For information about limitations see _Azure role-based access control vs. acces
 ## LINKS
 
 - [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access)
+- [IM-1: Use centralized identity and authentication system](https://learn.microsoft.com/security/benchmark/azure/baselines/key-vault-security-baseline#im-1-use-centralized-identity-and-authentication-system)
 - [What is Azure role-based access control?](https://learn.microsoft.com/azure/role-based-access-control/overview)
 - [Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control](https://learn.microsoft.com/azure/key-vault/general/rbac-guide)
 - [Azure role-based access control vs. access policies](https://learn.microsoft.com/azure/key-vault/general/rbac-access-policy)
 - [Migrate from vault access policy to an Azure role-based access control permission model](https://learn.microsoft.com/azure/key-vault/general/rbac-migration)
 - [Azure Key Vault security](https://learn.microsoft.com/azure/key-vault/general/security-features)
 - [Azure security baseline for Key Vault](https://learn.microsoft.com/security/benchmark/azure/baselines/key-vault-security-baseline)
-- [IM-1: Use centralized identity and authentication system](https://learn.microsoft.com/security/benchmark/azure/baselines/key-vault-security-baseline#im-1-use-centralized-identity-and-authentication-system)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.keyvault/vaults)

docs/en/rules/Azure.KeyVault.SoftDelete.md

@@ -91,6 +91,8 @@ resource vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
 }
 ```
 
+<!-- external:avm avm/res/key-vault/vault enableSoftDelete -->
+
 ### Configure with Azure CLI
 
 ```bash
@@ -101,7 +103,8 @@ az keyvault update -n '<name>' -g '<resource_group>' --retention-days 90
 
 To address this issue at runtime use the following policies:
 
-- [Key vaults should have soft delete enabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/KeyVault_SoftDeleteMustBeEnabled_Audit.json)
+- [Key vaults should have soft delete enabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Key%20Vault/SoftDeleteMustBeEnabled_Audit.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/1e66c121-a66a-4b1f-9b83-0fd99bf0fc2d`.
 
 ## LINKS
 

docs/examples-keyvault.json

@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.24.24.22086",
-      "templateHash": "3218451149490833125"
+      "version": "0.28.1.47646",
+      "templateHash": "14429599704704727241"
     }
   },
   "parameters": {

src/PSRule.Rules.Azure/rules/Azure.KeyVault.Rule.ps1

@@ -124,8 +124,3 @@ Rule 'Azure.KeyVault.AutoRotationPolicy' -Ref 'AZR-000123' -Type 'Microsoft.KeyV
         );
     }
 }
-
-# Synopsis: KeyVaults should only accept explicitly allowed traffic.
-Rule 'Azure.KeyVault.Firewall' -Ref 'AZR-000355' -Type 'Microsoft.KeyVault/vaults'  -Tag @{ release = 'GA'; ruleSet = '2023_03'; 'Azure.WAF/pillar' = 'Security'; } {
-    $Assert.HasFieldValue($TargetObject, 'Properties.networkAcls.defaultAction', 'Deny')
-}

src/PSRule.Rules.Azure/rules/Azure.KeyVault.Rule.yaml

@@ -15,8 +15,8 @@ metadata:
   name: Azure.KeyVault.SoftDelete
   ref: AZR-000124
   tags:
-    release: 'GA'
-    ruleSet: '2020_06'
+    release: GA
+    ruleSet: 2020_06
     Azure.WAF/pillar: Reliability
 spec:
   type:
@@ -33,8 +33,8 @@ metadata:
   name: Azure.KeyVault.PurgeProtect
   ref: AZR-000125
   tags:
-    release: 'GA'
-    ruleSet: '2020_06'
+    release: GA
+    ruleSet: 2020_06
     Azure.WAF/pillar: Reliability
 spec:
   type:
@@ -64,4 +64,24 @@ spec:
     field: properties.enableRbacAuthorization
     equals: true
 
+---
+# Synopsis: Vaults should only accept explicitly allowed traffic.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: Azure.KeyVault.Firewall
+  ref: AZR-000355
+  tags:
+    release: GA
+    ruleSet: 2023_03
+    Azure.WAF/pillar: Security
+  labels:
+    Azure.MCSB.v1/control: NS-2
+spec:
+  type:
+  - Microsoft.KeyVault/vaults
+  condition:
+    field: properties.networkAcls.defaultAction
+    equals: Deny
+
 #endregion Rules

tests/PSRule.Rules.Azure.Tests/PolicyAssignmentVisitorTests.cs

@@ -95,7 +95,7 @@ public void GetPolicyDefinitionWithIgnore()
 
             var definitions = context.GetDefinitions();
             Assert.NotNull(definitions);
-            Assert.Equal(113, definitions.Length);
+            Assert.Equal(112, definitions.Length);
 
             // Check category and version
             var actual = definitions.FirstOrDefault(definition => definition.DefinitionId == "/providers/Microsoft.Authorization/policyDefinitions/34c877ad-507e-4c82-993e-3452a6e0ad3c");