Rule documentation quality updates (#3152)

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

@@ -1,16 +1,16 @@
 ---
 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.HTTPBackend/
 ---
 
-# Use HTTPS backend connections
+# API Management allows unencrypted traffic to backends
 
 ## SYNOPSIS
 
-Use HTTPS for communication to backend services.
+Unencrypted communication could allow disclosure of information to an untrusted party.
 
 ## DESCRIPTION
 
@@ -110,6 +110,8 @@ resource api 'Microsoft.ApiManagement/service/apis@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service apis -->
+
 To deploy API backends that pass this rule:
 
 - Set the `properties.url` property to a URL that starts with `https://`.
@@ -129,9 +131,11 @@ resource backend 'Microsoft.ApiManagement/service/backends@2021-08-01' = {
 }
 ```
 
+<!-- external:avm avm/res/api-management/service backends -->
+
 ## 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#encrypt-data-in-transit)
 - [Manage protocols and ciphers in Azure API Management](https://learn.microsoft.com/azure/api-management/api-management-howto-manage-protocols-ciphers)
 - [Secure backend services using client certificate authentication in Azure API Management](https://learn.microsoft.com/azure/api-management/api-management-howto-mutual-certificates)
 - [Azure deployment reference for APIs](https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service/apis)

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

@@ -1,16 +1,16 @@
 ---
 severity: Important
 pillar: Security
-category: Data protection
+category: SE:07 Encryption
 resource: API Management
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.APIM.HTTPEndpoint/
 ---
 
-# Publish APIs through HTTPS connections
+# API Management allows unencrypted communication with clients
 
 ## SYNOPSIS
 
-Enforce HTTPS for communication to API clients.
+Unencrypted communication could allow disclosure of information to an untrusted party.
 
 ## DESCRIPTION
 
@@ -23,7 +23,75 @@ When using HTTP, sensitive information may be exposed to an untrusted party.
 Consider setting the each API to only accept HTTPS connections.
 In the portal, this is done by configuring the HTTPS URL scheme.
 
+## EXAMPLES
+
+### Configure with Azure template
+
+To deploy apis that pass this rule:
+
+- Set the `properties.protocols` property to include `https`. AND
+- Remove `http` from the `properties.protocols` property.
+
+For example:
+
+```json
+{
+  "type": "Microsoft.ApiManagement/service/apis",
+  "apiVersion": "2022-08-01",
+  "name": "[format('{0}/{1}', parameters('name'), 'echo-v1')]",
+  "properties": {
+    "displayName": "Echo API",
+    "description": "An echo API service.",
+    "type": "http",
+    "path": "echo",
+    "serviceUrl": "https://echo.contoso.com",
+    "protocols": [
+      "https"
+    ],
+    "apiVersion": "v1",
+    "apiVersionSetId": "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('name'), 'echo')]",
+    "subscriptionRequired": true
+  },
+  "dependsOn": [
+    "[resourceId('Microsoft.ApiManagement/service', parameters('name'))]",
+    "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('name'), 'echo')]"
+  ]
+}
+```
+
+### Configure with Bicep
+
+To deploy apis that pass this rule:
+
+- Set the `properties.protocols` property to include `https`. AND
+- Remove `http` from the `properties.protocols` property.
+
+For example:
+
+```bicep
+resource api 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
+  parent: service
+  name: 'echo-v1'
+  properties: {
+    displayName: 'Echo API'
+    description: 'An echo API service.'
+    type: 'http'
+    path: 'echo'
+    serviceUrl: 'https://echo.contoso.com'
+    protocols: [
+      'https'
+    ]
+    apiVersion: 'v1'
+    apiVersionSetId: version.id
+    subscriptionRequired: true
+  }
+}
+```
+
+<!-- external:avm avm/res/api-management/service apis -->
+
 ## 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#encrypt-data-in-transit)
 - [Import and publish a back-end API](https://learn.microsoft.com/azure/api-management/import-api-from-oas#-import-and-publish-a-back-end-api)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service/apis)

docs/en/rules/Azure.AppService.UseHTTPS.md

@@ -7,11 +7,11 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.AppSer
 ms-content-id: b26053bc-db4a-487a-8fb1-11c438c8d493
 ---
 
-# Enforce encrypted App Service connections
+# App Service allows unencrypted traffic
 
 ## SYNOPSIS
 
-Azure App Service apps should only accept encrypted connections.
+Unencrypted communication could allow disclosure of information to an untrusted party.
 
 ## DESCRIPTION
 
@@ -112,7 +112,7 @@ resource web 'Microsoft.Web/sites@2023-01-01' = {
 
 ## LINKS
 
-- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#data-in-transit)
+- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#encrypt-data-in-transit)
 - [DP-3: Encrypt sensitive data in transit](https://learn.microsoft.com/security/benchmark/azure/baselines/app-service-security-baseline#dp-3-encrypt-sensitive-data-in-transit)
 - [Enforce HTTPS](https://learn.microsoft.com/azure/app-service/configure-ssl-bindings#enforce-https)
 - [Azure Policy built-in definitions for Azure App Service](https://learn.microsoft.com/azure/app-service/policy-reference)

docs/en/rules/Azure.CDN.HTTP.md

@@ -1,16 +1,16 @@
 ---
 severity: Important
 pillar: Security
-category: Data protection
+category: SE:07 Encryption
 resource: Content Delivery Network
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.CDN.HTTP/
 ---
 
-# Use HTTPS client connections
+# CDN endpoint allows unencrypted traffic
 
 ## SYNOPSIS
 
-Enforce HTTPS for client connections.
+Unencrypted communication could allow disclosure of information to an untrusted party.
 
 ## DESCRIPTION
 
@@ -24,5 +24,6 @@ Consider disabling HTTP support on the CDN endpoint origin.
 
 ## LINKS
 
-- [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit)
-- [Configure HTTPS on an Azure CDN custom domain](https://learn.microsoft.com/azure/cdn/cdn-custom-ssl?tabs=option-1-default-enable-https-with-a-cdn-managed-certificate)
+- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#encrypt-data-in-transit)
+- [Configure HTTPS on an Azure CDN custom domain](https://learn.microsoft.com/azure/cdn/cdn-custom-ssl)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.cdn/profiles/endpoints)

docs/en/rules/Azure.CDN.MinTLS.md

@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Security
-category: Encryption
+category: SE:07 Encryption
 resource: Content Delivery Network
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.CDN.MinTLS/
 ---
@@ -28,7 +28,7 @@ Consider configuring a custom domain and setting the minimum supported TLS versi
 
 ## 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)
 - [Preparing for TLS 1.2 in Microsoft Azure](https://azure.microsoft.com/updates/azuretls12/)
 - [REST API Custom Domains - Enable Custom Https](https://learn.microsoft.com/rest/api/cdn/customdomains/enablecustomhttps#minimumtlsversion)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.cdn/profiles/endpoints)

docs/en/rules/Azure.CDN.UseFrontDoor.md

@@ -16,11 +16,16 @@ Use Azure Front Door Standard or Premium SKU to improve the performance of web p
 
 Using a CDN is a good way to minimize the load on your application, and maximize availability and performance.
 
-Standard content delivery network (CDN) capability includes the ability to cache files closer to end users to speed up delivery of static files. However, with dynamic web applications, caching that content in edge locations isn't possible because the server generates the content in response to user behavior. Speeding up the delivery of such content is more complex than traditional edge caching and requires an end-to-end solution that finely tunes each element along the entire data path from inception to delivery. With Azure CDN dynamic site acceleration (DSA) optimization, the performance of web pages with dynamic content is measurably improved.
+Standard content delivery network (CDN) capability includes the ability to cache files closer to end users to speed up delivery of static files.
+However, with dynamic web applications, caching that content in edge locations isn't possible because the server generates the content in response to user behavior.
+Speeding up the delivery of such content is more complex than traditional edge caching and requires an end-to-end solution that finely tunes each element along the entire data path from inception to delivery.
+With Azure CDN dynamic site acceleration (DSA) optimization, the performance of web pages with dynamic content is measurably improved.
 
 Azure Front Door Standard or Premium SKU offers modern cloud Content Delivery Network (CDN).
 These SKUs in particular provides fast, reliable, and secure access between users and dynamic web content across the globe.
 
+Azure CDN Standard from Microsoft (classic) will be retired on September 30, 2027.
+
 ## RECOMMENDATION
 
 Consider using Front Door Standard or Premium SKU to improve performance.