Rule WAF docs update Azure#2570 (Azure#2955)

Author: BernieWhite

data/policy-ignore.json

@@ -268,11 +268,33 @@
     "reason": "Duplicate",
     "value": "Azure.SQL.Auditing"
   },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/17k78e20-9358-41c9-923c-fb736d382a12"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.SQL.TDE"
+  },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/abda6d70-9778-44e7-84a8-06713e6db027"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.SQL.AADOnly"
+  },
   {
     "policyDefinitionIds": [
       "/providers/Microsoft.Authorization/policyDefinitions/4750c32b-89c0-46af-bfcb-2e4541a818d5"
     ],
     "reason": "Duplicate",
     "value": "Azure.Cosmos.DisableMetadataWrite"
+  },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/b08ab3ca-1062-4db3-8803-eec9cae605d6",
+      "/providers/Microsoft.Authorization/policyDefinitions/72bc14af-4ab8-43af-b4e4-38e7983f9a1f"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.AppConfig.DisableLocalAuth"
   }
 ]

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-B0034:
+
+- Engineering:
+  - Quality updates to rule documentation by @BernieWhite.
+    [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)
+
 ## v1.38.0-B0034 (pre-release)
 
 What's changed since pre-release v1.38.0-B0011:

docs/en/rules/Azure.AKS.DNSPrefix.md

@@ -1,7 +1,7 @@
 ---
 severity: Awareness
 pillar: Operational Excellence
-category: Tagging and resource naming
+category: OE:04 Continuous integration
 resource: Azure Kubernetes Service
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AKS.DNSPrefix/
 ---
@@ -27,7 +27,7 @@ Consider using a DNS prefix that meets naming requirements.
 
 ## 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)
 - [Recommended abbreviations for Azure resource types](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.containerservice/managedclusters)

docs/en/rules/Azure.APIM.APIDescriptors.md

@@ -2,7 +2,7 @@
 reviewed: 2023-03-05
 severity: Awareness
 pillar: Operational Excellence
-category: Instrumentation
+category: OE:04 Tools and processes
 resource: API Management
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.APIM.APIDescriptors/
 ---
@@ -11,7 +11,7 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.APIM.A
 
 ## SYNOPSIS
 
-API Management APIs should have a display name and description.
+APIs should have a display name and description.
 
 ## DESCRIPTION
 
@@ -44,7 +44,7 @@ For example:
 ```json
 {
   "type": "Microsoft.ApiManagement/service/apis",
-  "apiVersion": "2021-08-01",
+  "apiVersion": "2022-08-01",
   "name": "[format('{0}/{1}', parameters('name'), 'echo-v1')]",
   "properties": {
     "displayName": "Echo API",
@@ -76,7 +76,7 @@ To deploy API Management APIs that pass this rule:
 For example:
 
 ```bicep
-resource api 'Microsoft.ApiManagement/service/apis@2021-08-01' = {
+resource api 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
   parent: service
   name: 'echo-v1'
   properties: {
@@ -97,6 +97,6 @@ resource api 'Microsoft.ApiManagement/service/apis@2021-08-01' = {
 
 ## LINKS
 
-- [Human-readable data](https://learn.microsoft.com/azure/architecture/framework/devops/monitor-instrument#human-readable-data)
+- [OE:04 Tools and processes](https://learn.microsoft.com/azure/well-architected/operational-excellence/tools-processes)
 - [Import and publish your first API](https://learn.microsoft.com/azure/api-management/import-and-publish)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service/apis)

docs/en/rules/Azure.APIM.AvailabilityZone.md

@@ -170,6 +170,8 @@ resource service_api_mgmt_test2_name_resource 'Microsoft.ApiManagement/service@2
 }
 ```
 
+<!-- external:avm avm/res/api-management/service zones -->
+
 ## NOTES
 
 This rule applies when analyzing resources deployed to Azure using *pre-flight* and *in-flight* data.

docs/en/rules/Azure.APIM.Ciphers.md

@@ -2,7 +2,7 @@
 reviewed: 2023-03-05
 severity: Critical
 pillar: Security
-category: Encryption
+category: SE:07 Encryption
 resource: API Management
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.APIM.Ciphers/
 ---
@@ -147,9 +147,11 @@ resource service 'Microsoft.ApiManagement/service@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service customProperties -->
+
 ## LINKS
 
-- [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit)
+- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#data-in-transit)
 - [Manage protocols and ciphers in Azure API Management](https://learn.microsoft.com/azure/api-management/api-management-howto-manage-protocols-ciphers)
 - [Cryptographic Recommendations](https://learn.microsoft.com/security/sdl/cryptographic-recommendations)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service)

docs/en/rules/Azure.APIM.ManagedIdentity.md

@@ -121,6 +121,8 @@ resource service 'Microsoft.ApiManagement/service@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service managedIdentities -->
+
 ## LINKS
 
 - [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access#resource-identity)

docs/en/rules/Azure.APIM.MinAPIVersion.md

@@ -24,16 +24,16 @@ You can transition to API version 2021-08-01 or later at any point prior to 30 S
 
 ## RECOMMENDATION
 
-Limit control plane API calls to API Management with version '2021-08-01' or newer.
+Limit control plane API calls to API Management with version `2021-08-01` or newer.
 
 ## EXAMPLES
 
 ### Configure with Azure template
 
 To deploy API Management services that pass this rule:
 
-- Set the `apiVersion` property to `'2021-08-01'` or newer.
-- Set the `properties.apiVersionConstraint.minApiVersion` property to `'2021-08-01'` or newer.
+- Set the `apiVersion` property to `2021-08-01` or newer.
+- Set the `properties.apiVersionConstraint.minApiVersion` property to `2021-08-01` or newer.
 
 For example:
 
@@ -82,7 +82,7 @@ For example:
 To deploy API Management services that pass this rule:
 
 - Use the API Version `Microsoft.ApiManagement/service@2021-08-01` or newer.
-- Set the `properties.apiVersionConstraint.minApiVersion` property to `'2021-08-01'` or newer.
+- Set the `properties.apiVersionConstraint.minApiVersion` property to `2021-08-01` or newer.
 
 For example:
 
@@ -124,6 +124,8 @@ resource service 'Microsoft.ApiManagement/service@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service minApiVersion -->
+
 ## NOTES
 
 This rule fails:
@@ -137,6 +139,10 @@ This rule fails:
 - When you use the Azure portal or REST API version 2020-06-01-preview or later to delete an API Management instance, it's soft-deleted.
 - An API Management instance deleted using a REST API version before 2020-06-01-preview is permanently deleted.
 
+### Rule configuration
+
+<!-- module:config rule AZURE_APIM_MIN_API_VERSION -->
+
 Configure `AZURE_APIM_MIN_API_VERSION` to set the minimum API version used for control plane API calls to the API Management instance.
 
 ```yaml

docs/en/rules/Azure.AppConfig.DisableLocalAuth.md

@@ -86,40 +86,16 @@ resource store 'Microsoft.AppConfiguration/configurationStores@2023-03-01' = {
 }
 ```
 
-### Configure with Bicep Public Registry
-
-To deploy App Configuration Stores that pass this rule:
-
-- Set the `params.disableLocalAuth` parameter to `true`.
-
-For example:
-
-```bicep
-module br_public_store 'br/public:app/app-configuration:1.1.2' = {
-  name: 'store'
-  params: {
-    skuName: 'Standard'
-    disableLocalAuth: true
-    enablePurgeProtection: true
-    publicNetworkAccess: 'Disabled'
-    replicas: [
-      {
-        name: 'eastus'
-        location: 'eastus'
-      }
-    ]
-  }
-}
-```
+<!-- external:avm avm/res/app-configuration/configuration-store disableLocalAuth -->
 
 ### Configure with Azure Policy
 
 To address this issue at runtime use the following policies:
 
-Name | Resource
----- | --------
-App Configuration stores should have local authentication methods disabled | `/providers/Microsoft.Authorization/policyDefinitions/b08ab3ca-1062-4db3-8803-eec9cae605d6`
-Configure App Configuration stores to disable local authentication methods | `/providers/Microsoft.Authorization/policyDefinitions/72bc14af-4ab8-43af-b4e4-38e7983f9a1f`
+- [App Configuration stores should have local authentication methods disabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/App%20Configuration/DisableLocalAuth_Audit.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/b08ab3ca-1062-4db3-8803-eec9cae605d6`
+- [Configure App Configuration stores to disable local authentication methods](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/App%20Configuration/DisableLocalAuth_Modify.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/72bc14af-4ab8-43af-b4e4-38e7983f9a1f`
 
 ## LINKS
 
@@ -129,5 +105,4 @@ Configure App Configuration stores to disable local authentication methods | `/p
 - [Disable access key authentication](https://learn.microsoft.com/azure/azure-app-configuration/howto-disable-access-key-authentication)
 - [Azure security baseline for Azure App Configuration](https://learn.microsoft.com/security/benchmark/azure/baselines/azure-app-configuration-security-baseline)
 - [Azure Policy built-in definitions for Azure App Configuration](https://learn.microsoft.com/azure/azure-app-configuration/policy-reference)
-- [Bicep public registry](https://azure.github.io/bicep-registry-modules/#app)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.appconfiguration/configurationstores)

docs/en/rules/Azure.AppConfig.Name.md

@@ -2,7 +2,7 @@
 reviewed: 2022-09-24
 severity: Awareness
 pillar: Operational Excellence
-category: Repeatable infrastructure
+category: OE:04 Continuous integration
 resource: App Configuration
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AppConfig.Name/
 ---
@@ -41,15 +41,16 @@ For example:
 ```json
 {
   "type": "Microsoft.AppConfiguration/configurationStores",
-  "apiVersion": "2022-05-01",
+  "apiVersion": "2023-03-01",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "sku": {
     "name": "standard"
   },
   "properties": {
     "disableLocalAuth": true,
-    "enablePurgeProtection": true
+    "enablePurgeProtection": true,
+    "publicNetworkAccess": "Disabled"
   }
 }
 ```
@@ -58,12 +59,12 @@ For example:
 
 To deploy configuration stores that pass this rule:
 
-- Set `name` to a value that meets the requirements.
+- Set the `name` property to a value that meets the requirements.
 
 For example:
 
 ```bicep
-resource store 'Microsoft.AppConfiguration/configurationStores@2022-05-01' = {
+resource store 'Microsoft.AppConfiguration/configurationStores@2023-03-01' = {
   name: name
   location: location
   sku: {
@@ -72,43 +73,20 @@ resource store 'Microsoft.AppConfiguration/configurationStores@2022-05-01' = {
   properties: {
     disableLocalAuth: true
     enablePurgeProtection: true
-  }
-}
-```
-
-### Configure with Bicep Public Registry
-
-To deploy App Configuration Stores that pass this rule:
-
-- Set `params.name` to a value that meets the requirements.
-
-For example:
-
-```bicep
-module br_public_store 'br/public:app/app-configuration:1.1.2' = {
-  name: 'store'
-  params: {
-    skuName: 'Standard'
-    disableLocalAuth: true
-    enablePurgeProtection: true
     publicNetworkAccess: 'Disabled'
-    replicas: [
-      {
-        name: 'eastus'
-        location: 'eastus'
-      }
-    ]
   }
 }
 ```
 
+<!-- external:avm avm/res/app-configuration/configuration-store name -->
+
 ## NOTES
 
 This rule does not check if App Configuration store 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#microsoftappconfiguration)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.appconfiguration/configurationstores)
 - [Recommended abbreviations for Azure resource types](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations)

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

@@ -75,35 +75,10 @@ resource store 'Microsoft.AppConfiguration/configurationStores@2023-03-01' = {
 }
 ```
 
-### Configure with Bicep Public Registry
-
-To deploy App Configuration Stores that pass this rule:
-
-- Set the `params.enablePurgeProtection` parameter to `true`.
-
-For example:
-
-```bicep
-module br_public_store 'br/public:app/app-configuration:1.1.2' = {
-  name: 'store'
-  params: {
-    skuName: 'Standard'
-    disableLocalAuth: true
-    enablePurgeProtection: true
-    publicNetworkAccess: 'Disabled'
-    replicas: [
-      {
-        name: 'eastus'
-        location: 'eastus'
-      }
-    ]
-  }
-}
-```
+<!-- external:avm avm/res/app-configuration/configuration-store enablePurgeProtection -->
 
 ## LINKS
 
 - [Data management for reliability](https://learn.microsoft.com/azure/architecture/framework/resiliency/data-management)
 - [Purge protection](https://learn.microsoft.com/azure/azure-app-configuration/concept-soft-delete#purge-protection)
-- [Bicep public registry](https://azure.github.io/bicep-registry-modules/#app)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.appconfiguration/configurationstores)