From 8dd6d8fc864786d98ef040487125dae5044c1bd2 Mon Sep 17 00:00:00 2001 From: Bernie White Date: Sun, 27 Oct 2024 02:41:24 +1000 Subject: [PATCH] Rule documentation quality updates (#3152) --- docs/en/rules/Azure.APIM.HTTPBackend.md | 12 ++-- docs/en/rules/Azure.APIM.HTTPEndpoint.md | 76 ++++++++++++++++++++-- docs/en/rules/Azure.AppService.UseHTTPS.md | 6 +- docs/en/rules/Azure.CDN.HTTP.md | 11 ++-- docs/en/rules/Azure.CDN.MinTLS.md | 4 +- docs/en/rules/Azure.CDN.UseFrontDoor.md | 7 +- 6 files changed, 97 insertions(+), 19 deletions(-) diff --git a/docs/en/rules/Azure.APIM.HTTPBackend.md b/docs/en/rules/Azure.APIM.HTTPBackend.md index d4f7e0846b..c73c501bf4 100644 --- a/docs/en/rules/Azure.APIM.HTTPBackend.md +++ b/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' = { } ``` + + 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' = { } ``` + + ## 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) diff --git a/docs/en/rules/Azure.APIM.HTTPEndpoint.md b/docs/en/rules/Azure.APIM.HTTPEndpoint.md index 44a6a67a94..693ca21bfb 100644 --- a/docs/en/rules/Azure.APIM.HTTPEndpoint.md +++ b/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 + } +} +``` + + + ## 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) diff --git a/docs/en/rules/Azure.AppService.UseHTTPS.md b/docs/en/rules/Azure.AppService.UseHTTPS.md index d679b10429..83fb6f6377 100644 --- a/docs/en/rules/Azure.AppService.UseHTTPS.md +++ b/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) diff --git a/docs/en/rules/Azure.CDN.HTTP.md b/docs/en/rules/Azure.CDN.HTTP.md index 8b532e7870..2922db06b2 100644 --- a/docs/en/rules/Azure.CDN.HTTP.md +++ b/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) diff --git a/docs/en/rules/Azure.CDN.MinTLS.md b/docs/en/rules/Azure.CDN.MinTLS.md index fda52b3e86..9758d57a5c 100644 --- a/docs/en/rules/Azure.CDN.MinTLS.md +++ b/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) diff --git a/docs/en/rules/Azure.CDN.UseFrontDoor.md b/docs/en/rules/Azure.CDN.UseFrontDoor.md index 180e3167fe..12500a8af4 100644 --- a/docs/en/rules/Azure.CDN.UseFrontDoor.md +++ b/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.