Rule documentation quality updates #3102 (#3171)

Azure · Nov 7, 2024 · c9d6d8f · c9d6d8f
1 parent 65ac21d
commit c9d6d8f
Show file tree

Hide file tree

Showing 9 changed files with 39 additions and 20 deletions.
diff --git a/docs/CHANGELOG-v1.md b/docs/CHANGELOG-v1.md
@@ -36,6 +36,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
     - This feature adds support so that JSON parameter files with the `.jsonc` extension are also discovered and expanded.
     - No additional configuration is required if expansion of JSON parameter files is enabled.
     - To enable parameter file expansion set the `AZURE_PARAMETER_FILE_EXPANSION` configuration option to `true`.
+- General improvements:
+  - Additional quality updates to documentation by @BernieWhite.
+    [#3102](https://github.com/Azure/PSRule.Rules.Azure/issues/3102)
 - Bug fixes:
   - Fixed projection of default role authorization property `principalType` by @BernieWhite.
     [#3163](https://github.com/Azure/PSRule.Rules.Azure/issues/3163)

diff --git a/docs/en/rules/Azure.Defender.SecurityContact.md b/docs/en/rules/Azure.Defender.SecurityContact.md
@@ -102,7 +102,7 @@ resource securityContact 'Microsoft.Security/securityContacts@2023-12-01-preview
 az security contact update -n 'default' --emails '[email protected]'
 ```
 
-## LINK
+## LINKS
 
 - [SE:12 Incident response](https://learn.microsoft.com/azure/well-architected/security/incident-response)
 - [Quickstart: Configure email notifications for security alerts](https://learn.microsoft.com/azure/defender-for-cloud/configure-email-notifications)

diff --git a/docs/en/rules/Azure.MySQL.FirewallIPRange.md b/docs/en/rules/Azure.MySQL.FirewallIPRange.md
@@ -7,7 +7,7 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.MySQL.
 ms-content-id: d8bf9741-541c-4229-86cb-2e2dad32d9a9
 ---
 
-# Limit MySQL server firewall rule range
+# MySQL service firewall exposes a broad range of addresses
 
 ## SYNOPSIS
 

diff --git a/docs/en/rules/Azure.NSG.DenyAllInbound.md b/docs/en/rules/Azure.NSG.DenyAllInbound.md
@@ -1,20 +1,21 @@
 ---
 severity: Important
-pillar: Operational Excellence
-category: Configuration
+pillar: Reliability
+category: RE:01 Simplicity and efficiency
 resource: Network Security Group
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.NSG.DenyAllInbound/
 ---
 
-# Avoid denying all inbound traffic
+# Network Security Group denies all inbound traffic
 
 ## SYNOPSIS
 
-Avoid denying all inbound traffic.
+When all inbound traffic is denied, some functions that affect the reliability of your service may not work as expected.
 
 ## DESCRIPTION
 
-Network Security Groups (NSGs) are configured to block all inbound network traffic by default.
+Network Security Groups (NSGs) are can be configured to block or allow network traffic by defining security rules.
+Each security rule is processed in order from lowest priority to highest priority until the first match is found.
 Blocking all inbound traffic will fail load balancer health probes and other required traffic.
 
 When using a custom deny all inbound rule, also add rules to allow permitted traffic.
@@ -24,7 +25,7 @@ Rules with a lower priority number will be processed first.
 
 ## RECOMMENDATION
 
-Consider using a higher priority number for deny all rules to allow permitted traffic rules to be added.
+Consider using a higher priority number for deny all rules to allow permitted traffic rules to be added and processed first.
 Consider enabling Flow Logs on all critical subnets in your subscription as an auditability and security best practice.
 
 ## EXAMPLES
@@ -189,6 +190,7 @@ resource nsg 'Microsoft.Network/networkSecurityGroups@2022-01-01' = {
 
 ## LINKS
 
+- [RE:01 Simplicity and efficiency](https://learn.microsoft.com/azure/well-architected/reliability/simplify)
 - [Network security groups](https://learn.microsoft.com/azure/virtual-network/security-overview)
 - [Introduction to flow logging for network security groups](https://learn.microsoft.com/azure/network-watcher/network-watcher-nsg-flow-logging-overview)
 - [Virtual network service tags](https://learn.microsoft.com/azure/virtual-network/service-tags-overview)

diff --git a/docs/en/rules/Azure.SQL.DefenderCloud.md b/docs/en/rules/Azure.SQL.DefenderCloud.md
@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Security
-category: Security operations
+category: SE:10 Monitoring and threat detection
 resource: SQL Database
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.SQL.DefenderCloud/
 ms-content-id: 720e560d-4ad3-41ca-93dd-69c5783b9dbe
@@ -68,6 +68,7 @@ Set-AzSqlDatabaseThreatDetectionPolicy -ResourceGroupName '<resource_group>' -Se
 
 ## LINKS
 
-- [Advanced Threat Protection for Azure SQL Database](https://learn.microsoft.com/azure/sql-database/sql-database-threat-detection-overview)
+- [SE:10 Monitoring and threat detection](https://learn.microsoft.com/azure/well-architected/security/monitor-threats)
+- [SQL Advanced Threat Protection](https://learn.microsoft.com/azure/azure-sql/database/threat-detection-overview)
 - [Microsoft Defender for SQL](https://learn.microsoft.com/azure/azure-sql/database/azure-defender-for-sql)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.sql/servers/securityalertpolicies)
diff --git a/docs/en/rules/Azure.SQL.FirewallIPRange.md b/docs/en/rules/Azure.SQL.FirewallIPRange.md
@@ -7,26 +7,34 @@ online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.SQL.Fi
 ms-content-id: a25b1927-f04c-4a6a-8a3d-42d59d4722ff
 ---
 
-# Limit SQL logical server firewall rule range
+# SQL Database service firewall exposes a broad range of addresses
 
 ## SYNOPSIS
 
-Determine if there is an excessive number of permitted IP addresses set in the allowed IP list (CIDR range).
+Each IP address in the permitted IP list is allowed network access to any databases hosted on the same logical server.
 
 ## DESCRIPTION
 
-Typically the number of IP address rules permitted through the firewall is minimal, with management connectivity from
-on-premises and cloud application connectivity the most common. This rule assesses the combined IP addresses from each
-Allowed IP firewall entry to check that the total allowed addresses is less than (10).
+The Azure SQL database service firewall is an important security control, that help restrict network access to data.
+Access to a database still requires an identity with permissions to read the data in addition to network access.
+Combining network and identity controls together further harden your environment against,
+use of compromised identities during lateral traversal and misuse of credentials.
+
+Typically the number of IP address rules permitted through the firewall is minimal,
+with management connectivity from on-premises and cloud application connectivity the most common.
+Excessive access from many IP addresses may indicate weak network security controls.
 
 ## RECOMMENDATION
 
-Reduce the size or count of the IP ranges set in the Firewall rules so that the total Allowed IPs are less than (10).
+Consider reducing the size or count of the IP ranges in the Firewall rules so that the total Allowed IPs are less than (10).
+
+## NOTES
 
-## Example
+This rule assesses the combined IP addresses from each Allowed IP firewall entry to check that the total allowed addresses is less than (10).
 
 ## LINKS
 
+- [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)
 - [Azure SQL Database and Azure Synapse IP firewall rules](https://learn.microsoft.com/azure/azure-sql/database/firewall-configure?view=azuresql)
 - [Create and manage IP firewall rules](https://learn.microsoft.com/azure/azure-sql/database/firewall-configure?view=azuresql#create-and-manage-ip-firewall-rules)
 - [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.sql/servers/firewallrules)
diff --git a/docs/en/rules/Azure.VM.AcceleratedNetworking.md b/docs/en/rules/Azure.VM.AcceleratedNetworking.md
@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Performance Efficiency
-category: Performance
+category: PE:07 Code and infrastructure
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.AcceleratedNetworking/
 ms-content-id: c2b60867-f911-45d6-8d9a-a22bf0a7e729
@@ -27,5 +27,6 @@ Consider enabling accelerated networking for supported operating systems and VM
 
 ## LINKS
 
+- [PE:07 Code and infrastructure](https://learn.microsoft.com/azure/well-architected/performance-efficiency/optimize-code-infrastructure)
 - [Create a Linux virtual machine with Accelerated Networking using Azure CLI](https://learn.microsoft.com/azure/virtual-network/create-vm-accelerated-networking-cli)
 - [Create a Windows VM with accelerated networking using Azure PowerShell](https://learn.microsoft.com/azure/virtual-network/create-vm-accelerated-networking-powershell)
diff --git a/docs/en/rules/Azure.VM.DiskCaching.md b/docs/en/rules/Azure.VM.DiskCaching.md
@@ -1,7 +1,7 @@
 ---
 severity: Important
 pillar: Performance Efficiency
-category: Performance
+category: PE:07 Code and infrastructure
 resource: Virtual Machine
 online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.VM.DiskCaching/
 ms-content-id: d28da16e-4639-466f-95e5-4ab6bf61aec7
@@ -20,3 +20,7 @@ Check disk caching is configured correctly for the workload.
 ## RECOMMENDATION
 
 Check disk caching is configured correctly for the workload.
+
+## LINKS
+
+- [PE:07 Code and infrastructure](https://learn.microsoft.com/azure/well-architected/performance-efficiency/optimize-code-infrastructure)
diff --git a/src/PSRule.Rules.Azure/rules/Azure.NSG.Rule.ps1 b/src/PSRule.Rules.Azure/rules/Azure.NSG.Rule.ps1
@@ -18,7 +18,7 @@ Rule 'Azure.NSG.AnyInboundSource' -Ref 'AZR-000137' -Type 'Microsoft.Network/net
 }
 
 # Synopsis: Avoid blocking all inbound network traffic
-Rule 'Azure.NSG.DenyAllInbound' -Ref 'AZR-000138' -Type 'Microsoft.Network/networkSecurityGroups' -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Security'; } {
+Rule 'Azure.NSG.DenyAllInbound' -Ref 'AZR-000138' -Type 'Microsoft.Network/networkSecurityGroups' -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Reliability'; } {
     Reason $LocalizedData.AllInboundRestricted;
     $inboundRules = @(GetOrderedNSGRules -Direction Inbound);
     $denyRules = @($inboundRules | Where-Object {