Updates to WAF documentation

docs/CHANGELOG-v1.md

@@ -31,8 +31,11 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 What's changed since pre-release v1.40.0-B0147:
 
+- Engineering:
+  - Quality updates to rule documentation by @BernieWhite.
+    [#3102](https://github.com/Azure/PSRule.Rules.Azure/issues/3102)
 - Bug fixes:
-  - Fixed evaluation of APIM policies when using embedded C# with quotes by #BernieWhite.
+  - Fixed evaluation of APIM policies when using embedded C# with quotes by @BernieWhite.
     [#3184](https://github.com/Azure/PSRule.Rules.Azure/issues/3184)
 
 ## v1.40.0-B0147 (pre-release)

docs/en/rules/Azure.Monitor.ServiceHealth.md

@@ -1,7 +1,7 @@
 ---
 severity: Important
-pillar: Operational Excellence
-category: Monitoring
+pillar: Reliability
+category: RE:10 Monitoring and alerting
 resource: Monitor
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Monitor.ServiceHealth/
 ---
@@ -27,5 +27,6 @@ Consider configuring an alert to notify administrators when services you are usi
 
 ## LINKS
 
+- [RE:10 Monitoring and alerting](https://learn.microsoft.com/azure/well-architected/reliability/monitoring-alerting-strategy)
 - [Service Health overview](https://learn.microsoft.com/azure/service-health/service-health-overview)
 - [Create activity log alerts on service notifications](https://learn.microsoft.com/azure/service-health/alerts-activity-log-service-notifications)

docs/en/rules/Azure.VM.PublicKey.md

@@ -1,21 +1,147 @@
 ---
 severity: Important
 pillar: Security
-category: Identity and access management
+category: SE:08 Hardening resources
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.PublicKey/
 ---
 
-# Use public keys for Linux
+# VM password-based authentication is enabled
 
 ## SYNOPSIS
 
 Linux virtual machines should use public keys.
 
 ## DESCRIPTION
 
-Linux virtual machines support either password or public key based authentication for the default administrator account.
+Linux virtual machines should have password authentication disabled to help with eliminating password-based attacks.
 
 ## RECOMMENDATION
 
-Consider using public key based authentication instead of passwords.
+Consider disabling password-based authentication on Linux virtual machines and instead use public keys.
+
+## EXAMPLES
+
+### Configure with Azure template
+
+To deploy virtual machines that pass this rule:
+
+- Set the `properties.osProfile.linuxConfiguration.disablePasswordAuthentication` property to `true`.
+
+For example:
+
+```json
+{
+  "type": "Microsoft.Compute/virtualMachines",
+  "apiVersion": "2024-03-01",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "properties": {
+    "hardwareProfile": {
+      "vmSize": "Standard_D8d_v5"
+    },
+    "osProfile": {
+      "computerName": "[parameters('name')]",
+      "adminUsername": "[parameters('adminUsername')]",
+      "linuxConfiguration": {
+        "disablePasswordAuthentication": true
+      }
+    },
+    "storageProfile": {
+      "imageReference": {
+        "publisher": "MicrosoftCblMariner",
+        "offer": "Cbl-Mariner",
+        "sku": "cbl-mariner-2-gen2",
+        "version": "latest"
+      },
+      "osDisk": {
+        "name": "[format('{0}-disk0', parameters('name'))]",
+        "caching": "ReadWrite",
+        "createOption": "FromImage",
+        "managedDisk": {
+          "storageAccountType": "Premium_LRS"
+        }
+      }
+    },
+    "networkProfile": {
+      "networkInterfaces": [
+        {
+          "id": "[resourceId('Microsoft.Network/networkInterfaces', parameters('nicName'))]"
+        }
+      ]
+    }
+  },
+  "zones": [
+    "1"
+  ],
+  "dependsOn": [
+    "[resourceId('Microsoft.Network/networkInterfaces', parameters('nicName'))]"
+  ]
+}
+```
+
+### Configure with Bicep
+
+To deploy virtual machines that pass this rule:
+
+- Set the `properties.osProfile.linuxConfiguration.disablePasswordAuthentication` property to `true`.
+
+For example:
+
+```bicep
+resource linux 'Microsoft.Compute/virtualMachines@2024-03-01' = {
+  name: name
+  location: location
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    hardwareProfile: {
+      vmSize: 'Standard_D8d_v5'
+    }
+    osProfile: {
+      computerName: name
+      adminUsername: adminUsername
+      linuxConfiguration: {
+        disablePasswordAuthentication: true
+      }
+    }
+    storageProfile: {
+      imageReference: {
+        publisher: 'MicrosoftCblMariner'
+        offer: 'Cbl-Mariner'
+        sku: 'cbl-mariner-2-gen2'
+        version: 'latest'
+      }
+      osDisk: {
+        name: '${name}-disk0'
+        caching: 'ReadWrite'
+        createOption: 'FromImage'
+        managedDisk: {
+          storageAccountType: 'Premium_LRS'
+        }
+      }
+    }
+    networkProfile: {
+      networkInterfaces: [
+        {
+          id: nic.id
+        }
+      ]
+    }
+  }
+  zones: [
+    '1'
+  ]
+}
+```
+
+## LINKS
+
+- [SE:08 Hardening resources](https://learn.microsoft.com/azure/well-architected/security/harden-resources)
+- [Azure security baseline for Linux Virtual Machines](https://learn.microsoft.com/security/benchmark/azure/baselines/virtual-machines-linux-security-baseline)
+- [Detailed steps: Create and manage SSH keys for authentication to a Linux VM in Azure](https://learn.microsoft.com/azure/virtual-machines/linux/create-ssh-keys-detailed)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.compute/virtualmachines)