Documentation improvements Azure#2570 (Azure#2748)

* Documentation improvements Azure#2570

* Fix

Author: BernieWhite

data/policy-ignore.json

@@ -209,5 +209,13 @@
     ],
     "reason": "NotApplicable",
     "value": "Checking for BYOK of a storage account used for logging activity is not enforcable by code (#2725)."
+  },
+  {
+    "policyDefinitionIds": [
+      "/providers/Microsoft.Authorization/policyDefinitions/cfb11c26-f069-4c14-8e36-56c394dae5af",
+      "/providers/Microsoft.Authorization/policyDefinitions/910711a6-8aa2-4f15-ae62-1e5b2ed3ef9e"
+    ],
+    "reason": "Duplicate",
+    "value": "Azure.ServiceBus.DisableLocalAuth"
   }
 ]

docs/CHANGELOG-v1.md

@@ -32,6 +32,12 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
+What's changed since v1.34.2:
+
+- General improvements:
+  - Documentation improvements by @BernieWhite.
+    [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)
+
 ## v1.34.2
 
 What's changed since v1.34.1:

docs/en/rules/Azure.SQL.AAD.md

@@ -1,32 +1,32 @@
 ---
-reviewed: 2023-07-26
+reviewed: 2024-03-11
 severity: Critical
 pillar: Security
-category: Authentication
+category: SE:05 Identity and access management
 resource: SQL Database
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.SQL.AAD/
 ---
 
-# Use AAD authentication with SQL databases
+# Use Entra ID authentication with SQL databases
 
 ## SYNOPSIS
 
-Use Azure Active Directory (AAD) authentication with Azure SQL databases.
+Use Entra ID authentication with Azure SQL databases.
 
 ## DESCRIPTION
 
-Azure SQL Database offer two authentication models, Azure Active Directory (AAD) and SQL authentication.
-AAD authentication supports centralized identity management in addition to modern password protections.
-Some of the benefits of AAD authentication over SQL authentication including:
+Azure SQL Database offer two authentication models, Entra ID (previously known as Azure AD) and SQL authentication.
+Entra ID authentication supports centralized identity management in addition to modern password protections.
+Some of the benefits of Entra ID authentication over SQL authentication including:
 
 - Support for Azure Multi-Factor Authentication (MFA).
 - Conditional-based access with Conditional Access.
 
-It is also possible to disable SQL authentication entirely and only use AAD authentication.
+It is also possible to disable SQL authentication entirely and only use Entra ID authentication.
 
 ## RECOMMENDATION
 
-Consider using Azure Active Directory (AAD) authentication with SQL databases.
+Consider using Entra ID authentication with SQL databases.
 Additionally, consider disabling SQL authentication.
 
 ## EXAMPLES
@@ -155,17 +155,18 @@ Set-AzSqlServerActiveDirectoryAdministrator -ResourceGroupName '<resource_group>
 ## NOTES
 
 In newer API versions the `properties.administrators` property can be configured.
-Azure AD authentication can also be configured using the `Microsoft.Sql/servers/administrators` sub-resource.
+Entra ID authentication can also be configured using the `Microsoft.Sql/servers/administrators` sub-resource.
 
 If both the `properties.administrators` property and `Microsoft.Sql/servers/administrators` are set,
 the sub-resource will override the property.
 
 ## LINKS
 
-- [Use modern password protection](https://learn.microsoft.com/azure/architecture/framework/security/design-identity-authentication#use-modern-password-protection)
-- [Configure and manage Azure AD authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-aad-configure)
-- [Using multi-factor Azure Active Directory authentication](https://learn.microsoft.com/azure/azure-sql/database/authentication-mfa-ssms-overview)
+- [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/azure-sql-security-baseline#im-1-use-centralized-identity-and-authentication-system)
+- [Configure and manage Microsoft Entra authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-aad-configure)
+- [Using Microsoft Entra multi-factor authentication](https://learn.microsoft.com/azure/azure-sql/database/authentication-mfa-ssms-overview)
 - [Conditional Access with Azure SQL Database and Azure Synapse Analytics](https://learn.microsoft.com/azure/azure-sql/database/conditional-access-configure)
-- [Azure AD-only authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-azure-ad-only-authentication)
-- [Azure Policy for Azure Active Directory only authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-azure-ad-only-authentication-policy)
+- [Microsoft Entra-only authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-azure-ad-only-authentication)
+- [Azure Policy for Microsoft Entra-only authentication with Azure SQL](https://learn.microsoft.com/azure/azure-sql/database/authentication-azure-ad-only-authentication-policy)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.sql/servers)

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

@@ -1,8 +1,8 @@
 ---
-reviewed: 2022/01/22
+reviewed: 2024-03-11
 severity: Important
 pillar: Security
-category: Authentication
+category: SE:05 Identity and access management
 resource: Service Bus
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.ServiceBus.DisableLocalAuth/
 ---
@@ -11,60 +11,61 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Servic
 
 ## SYNOPSIS
 
-Authenticate Service Bus publishers and consumers with Azure AD identities.
+Authenticate Service Bus publishers and consumers with Entra ID identities.
 
 ## DESCRIPTION
 
-To publish or consume messages from Service Bus cryptographic keys, or Azure AD identities can be used.
+To publish or consume messages from Service Bus cryptographic keys, or Entra ID identities can be used.
 Cryptographic keys include Shared Access Policy keys or Shared Access Signature (SAS) tokens.
-With Azure AD authentication, the identity is validated against Azure AD.
-Using Azure AD identities centralizes identity management and auditing.
+With Entra ID authentication, the identity is validated against Entra ID.
+Using Entra ID identities centralizes identity management and auditing.
 
-Once you decide to use Azure AD authentication, you can disable authentication using keys or SAS tokens.
+Once you decide to use Entra ID authentication, you can disable authentication using keys or SAS tokens.
 
 ## RECOMMENDATION
 
-Consider only using Azure AD identities to publish or consume messages from Service Bus.
+Consider only using Entra ID identities to publish or consume messages from Service Bus.
 Then disable authentication based on access keys or SAS tokens.
 
 ## EXAMPLES
 
 ### Configure with Azure template
 
-To deploy Service Bus namespaces that pass this rule:
+To deploy namespaces that pass this rule:
 
 - Set the `properties.disableLocalAuth` property to `true`.
 
 For example:
 
 ```json
 {
-    "type": "Microsoft.ServiceBus/namespaces",
-    "apiVersion": "2021-11-01",
-    "name": "[parameters('name')]",
-    "location": "[parameters('location')]",
-    "identity": {
-        "type": "SystemAssigned"
-    },
-    "sku": {
-        "name": "Standard"
-    },
-    "properties": {
-        "disableLocalAuth": true
-    }
+  "type": "Microsoft.ServiceBus/namespaces",
+  "apiVersion": "2022-10-01-preview",
+  "name": "[parameters('name')]",
+  "location": "[parameters('location')]",
+  "identity": {
+    "type": "SystemAssigned"
+  },
+  "sku": {
+    "name": "Standard"
+  },
+  "properties": {
+    "disableLocalAuth": true,
+    "minimumTlsVersion": "1.2"
+  }
 }
 ```
 
 ### Configure with Bicep
 
-To deploy Service Bus namespaces that pass this rule:
+To deploy namespaces that pass this rule:
 
 - Set the `properties.disableLocalAuth` property to `true`.
 
 For example:
 
 ```bicep
-resource ns 'Microsoft.ServiceBus/namespaces@2021-11-01' = {
+resource ns 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' = {
   name: name
   location: location
   identity: {
@@ -75,12 +76,23 @@ resource ns 'Microsoft.ServiceBus/namespaces@2021-11-01' = {
   }
   properties: {
     disableLocalAuth: true
+    minimumTlsVersion: '1.2'
   }
 }
 ```
 
+### Configure with Azure Policy
+
+To address this issue at runtime use the following policies:
+
+- [Azure Service Bus namespaces should have local authentication methods disabled](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Service%20Bus/ServiceBus_DisableLocalAuth_AuditDeny.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/cfb11c26-f069-4c14-8e36-56c394dae5af`
+- [Configure Azure Service Bus namespaces to disable local authentication](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policyDefinitions/Service%20Bus/ServiceBus_DisableLocalAuth_Modify.json)
+  `/providers/Microsoft.Authorization/policyDefinitions/910711a6-8aa2-4f15-ae62-1e5b2ed3ef9e`
+
 ## LINKS
 
-- [Use identity-based authentication](https://learn.microsoft.com/azure/well-architected/security/design-identity-authentication#use-identity-based-authentication)
-- [Service Bus authentication and authorization](https://docs.microsoft.com/azure/service-bus-messaging/service-bus-authentication-and-authorization)
-- [Azure deployment reference](https://docs.microsoft.com/azure/templates/microsoft.servicebus/namespaces)
+- [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/service-bus-security-baseline#im-1-use-centralized-identity-and-authentication-system)
+- [Service Bus authentication and authorization](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-authentication-and-authorization)
+- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.servicebus/namespaces)

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

@@ -1,7 +1,8 @@
 ---
+reviewed: 2024-03-11
 severity: Important
 pillar: Security
-category: Information protection
+category: SE:07 Encryption
 resource: Service Bus
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.ServiceBus.MinTLS/
 ---
@@ -10,34 +11,39 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Servic
 
 ## SYNOPSIS
 
-Enforce namespaces to require that clients send and receive data with TLS 1.2 version.
+Service Bus namespaces should reject TLS versions older than 1.2.
 
 ## DESCRIPTION
 
-Communication between a client application and an Azure Service Bus namespace is encrypted using Transport Layer Security (TLS).
+Clients connect to Azure Service Bus to send and receive messages over a Transport Layer Security (TLS) encrypted connection.
+The minimum version of TLS that Service Bus accepts is configurable.
+Older TLS versions are no longer considered secure by industry standards, such as PCI DSS.
+Additionally, support for TLS 1.0 and 1.1 are on a deprecation path across Azure services.
 
-Azure Service Bus namespaces permit clients to send and receive data with TLS 1.0 and above. To enforce stricter security measures, you can configure your Service Bus namespace to require that clients send and receive data with a newer version of TLS. If a Service Bus namespace requires a minimum version of TLS, then any requests made with an older version will fail.
+Azure lets you disable outdated protocols and require connections to use a minimum of TLS 1.2.
+By default, TLS 1.0, TLS 1.1, and TLS 1.2 are accepted.
 
-**Important** If you are using a service that connects to Azure Service Bus, make sure that that service is using the appropriate version of TLS to send requests to Azure Service Bus before you set the required minimum version for a Service Bus namespace.
+When clients connect using an older version of TLS that is disabled, the connection will fail.
 
 ## RECOMMENDATION
 
-Consider namespaces to require that clients send and receive data with TLS 1.2 version.
+Consider configuring the minimum supported TLS version for Service Bus clients to be 1.2.
+Support for TLS 1.0/ 1.1 version will be removed.
 
 ## EXAMPLES
 
 ### Configure with Azure template
 
-To deploy Service Bus namespaces that pass this rule:
+To deploy namespaces that pass this rule:
 
-- Set `properties.minimumTlsVersion` to `1.2`.
+- Set the `properties.minimumTlsVersion` property to `1.2`.
 
 For example:
 
 ```json
 {
   "type": "Microsoft.ServiceBus/namespaces",
-  "apiVersion": "2022-01-01-preview",
+  "apiVersion": "2022-10-01-preview",
   "name": "[parameters('name')]",
   "location": "[parameters('location')]",
   "identity": {
@@ -55,20 +61,14 @@ For example:
 
 ### Configure with Bicep
 
-To deploy Service Bus namespaces that pass this rule:
+To deploy namespaces that pass this rule:
 
-- Set `properties.minimumTlsVersion` to `1.2`.
+- Set the `properties.minimumTlsVersion` property to `1.2`.
 
 For example:
 
 ```bicep
-@description('The name of the resource.')
-param name string
-
-@description('The location resources will be deployed.')
-param location string = resourceGroup().location
-
-resource ns 'Microsoft.ServiceBus/namespaces@2022-01-01-preview' = {
+resource ns 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' = {
   name: name
   location: location
   identity: {
@@ -84,8 +84,23 @@ resource ns 'Microsoft.ServiceBus/namespaces@2022-01-01-preview' = {
 }
 ```
 
+### Configure with Azure CLI
+
+```bash
+az servicebus namespace update -n '<name>' -g '<resource_group>' --minimum-tls-version '1.2'
+```
+
+### Configure with Azure PowerShell
+
+```powershell
+$ns = Get-AzServiceBusNamespace  -Name '<name>' -ResourceGroupName '<resource_group>'
+Set-AzServiceBusNamespace -InputObject $ns -MinimumTlsVersion '1.2'
+```
+
 ## LINKS
 
-- [Information protection and storage](https://learn.microsoft.com/azure/architecture/framework/security/storage-data-encryption)
+- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#data-in-transit)
+- [DP-3: Encrypt sensitive data in transit](https://learn.microsoft.com/security/benchmark/azure/baselines/service-bus-security-baseline#dp-3-encrypt-sensitive-data-in-transit)
 - [Enforce a minimum requires version of TLS](https://learn.microsoft.com/azure/service-bus-messaging/transport-layer-security-enforce-minimum-version)
+- [Preparing for TLS 1.2 in Microsoft Azure](https://azure.microsoft.com/updates/azuretls12/)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.servicebus/namespaces)

docs/examples-servicebus.bicep

@@ -9,8 +9,8 @@ param name string
 @description('The location resources will be deployed.')
 param location string = resourceGroup().location
 
-// An example Service Bus namespace
-resource ns 'Microsoft.ServiceBus/namespaces@2022-01-01-preview' = {
+// An example Service Bus namespace.
+resource ns 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' = {
   name: name
   location: location
   identity: {

docs/examples-servicebus.json

@@ -4,8 +4,8 @@
   "metadata": {
     "_generator": {
       "name": "bicep",
-      "version": "0.11.1.770",
-      "templateHash": "17235301402195616974"
+      "version": "0.25.53.49325",
+      "templateHash": "11141900091582778494"
     }
   },
   "parameters": {
@@ -26,7 +26,7 @@
   "resources": [
     {
       "type": "Microsoft.ServiceBus/namespaces",
-      "apiVersion": "2022-01-01-preview",
+      "apiVersion": "2022-10-01-preview",
       "name": "[parameters('name')]",
       "location": "[parameters('location')]",
       "identity": {

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

@@ -13,11 +13,6 @@ Rule 'Azure.ServiceBus.Usage' -Ref 'AZR-000177' -Type 'Microsoft.ServiceBus/name
     $Assert.GreaterOrEqual($items, '.', 1);
 }
 
-# Synopsis: Enforce namespaces to require that clients send and receive data with TLS 1.2 version.
-Rule 'Azure.ServiceBus.MinTLS' -Ref 'AZR-000315' -Type 'Microsoft.ServiceBus/namespaces' -Tag @{ release = 'GA'; ruleSet = '2022_12'; 'Azure.WAF/pillar' = 'Security'; } {
-    $Assert.HasFieldValue($TargetObject, 'Properties.minimumTlsVersion', '1.2').Reason($LocalizedData.ServiceBusMinTLS, $PSRule.TargetName)
-}
-
 # Synopsis: Ensure namespaces audit diagnostic logs are enabled.
 Rule 'Azure.ServiceBus.AuditLogs' -Ref 'AZR-000358' -Type 'Microsoft.ServiceBus/namespaces' -With 'Azure.ServiceBus.IsPremium' -Tag @{ release = 'GA'; ruleSet = '2023_03'; 'Azure.WAF/pillar' = 'Security'; } {
     $logCategoryGroups = 'audit', 'allLogs'