AWS organizations documentation change
Summary
Added documentation for managing Security Hub features (like network scanning) in organization policies, including new syntax, key points, and multiple usage examples.
Security assessment
The changes document new policy capabilities for Security Hub's network scanning feature, which is a security-related functionality. However, there's no evidence of a specific security vulnerability being addressed; this is routine documentation for a new security feature.
Diff
diff --git a/organizations/latest/userguide/orgs_manage_policies_security_hub_syntax.md b/organizations/latest/userguide/orgs_manage_policies_security_hub_syntax.md index 11e9f0a39..47275f34c 100644 --- a//organizations/latest/userguide/orgs_manage_policies_security_hub_syntax.md +++ b//organizations/latest/userguide/orgs_manage_policies_security_hub_syntax.md @@ -17 +17 @@ Before creating Security Hub policies, understand these key points about policy - * Both `enable_in_regions` and `disable_in_regions` lists are required in the policy, though they can be empty + * Both `enable_in_regions` and `disable_in_regions` lists are required in the policy, though they can be empty. @@ -19 +19 @@ Before creating Security Hub policies, understand these key points about policy - * When processing effective policies, `disable_in_regions` takes precedence over `enable_in_regions` + * When processing effective policies, `disable_in_regions` takes precedence over `enable_in_regions`. @@ -21 +21 @@ Before creating Security Hub policies, understand these key points about policy - * Child policies can modify parent policies using inheritance operators unless explicitly restricted + * Child policies can modify parent policies using inheritance operators unless explicitly restricted. @@ -23 +23 @@ Before creating Security Hub policies, understand these key points about policy - * The `ALL_SUPPORTED` designation includes both current and future regions + * The `ALL_SUPPORTED` designation includes both current and future Regions. @@ -25 +25,13 @@ Before creating Security Hub policies, understand these key points about policy - * Region names must be valid and available in Security Hub + * Region names must be valid and available in Security Hub. + + * The `features` map is optional and is available only in commercial AWS Regions (Regions other than the AWS GovCloud (US) Regions and the China Regions). It is not available in the AWS GovCloud (US) Regions or China Regions. + + * Both `enable_in_regions` and `disable_in_regions` lists within a feature are required, though they can be empty. + + * When processing effective policies, `disable_in_regions` takes precedence over `enable_in_regions` for a feature, the same as for the top-level lists. + + * A feature is configured only in Regions where Security Hub is enabled by the same effective policy. Disabling Security Hub in a Region also disables its features in that Region. + + * Regions that appear in neither the `enable_in_regions` nor the `disable_in_regions` list for a feature are left unmanaged by the policy. + + * When the `features` map, or a feature within it, is omitted, that feature is left unmanaged by the policy. @@ -47,0 +60,28 @@ A Security Hub policy uses this basic structure: +A Security Hub policy can also include an optional `features` map to manage opt-in Security Hub features, such as network scanning, across your organization. The `features` map is available only in commercial AWS Regions. + + + { + "securityhub": { + "enable_in_regions": { + "@@assign": ["ALL_SUPPORTED"], + "@@operators_allowed_for_child_policies": ["@@all"] + }, + "disable_in_regions": { + "@@assign": [], + "@@operators_allowed_for_child_policies": ["@@all"] + }, + "features": { + "network_scanning": { + "enable_in_regions": { + "@@assign": ["us-east-1", "us-west-2"], + "@@operators_allowed_for_child_policies": ["@@all"] + }, + "disable_in_regions": { + "@@assign": [], + "@@operators_allowed_for_child_policies": ["@@all"] + } + } + } + } + } + @@ -55 +95 @@ Security Hub policies contain these key components: -The top-level container for policy settings +The top-level container for policy settings. @@ -57 +97 @@ The top-level container for policy settings -Required for all Security Hub policies +Required for all Security Hub policies. @@ -62 +102 @@ Required for all Security Hub policies -List of regions where Security Hub should be enabled +List of Regions where Security Hub should be enabled. @@ -64 +104 @@ List of regions where Security Hub should be enabled -Can contain specific region names or `ALL_SUPPORTED` +Can contain specific Region names or `ALL_SUPPORTED`. @@ -66 +106 @@ Can contain specific region names or `ALL_SUPPORTED` -Required field but can be empty +Required field but can be empty. @@ -68 +108 @@ Required field but can be empty -When using `ALL_SUPPORTED`, includes future regions +When using `ALL_SUPPORTED`, includes future Regions. @@ -73 +113 @@ When using `ALL_SUPPORTED`, includes future regions -List of regions where Security Hub should be disabled +List of Regions where Security Hub should be disabled. @@ -75 +115 @@ List of regions where Security Hub should be disabled -Can contain specific region names or `ALL_SUPPORTED` +Can contain specific Region names or `ALL_SUPPORTED`. @@ -77 +117 @@ Can contain specific region names or `ALL_SUPPORTED` -Required field but can be empty +Required field but can be empty. @@ -79 +119 @@ Required field but can be empty -Takes precedence over `enable_in_regions` when regions appear in both lists +Takes precedence over `enable_in_regions` when Regions appear in both lists. @@ -84 +124 @@ Inheritance operators -@@assign - Overwrites inherited values +@@assign - Overwrites inherited values. @@ -86 +126 @@ Inheritance operators -@@append - Adds new values to existing ones +@@append - Adds new values to existing ones. @@ -88 +128,45 @@ Inheritance operators -@@remove - Removes specific values from inherited settings +@@remove - Removes specific values from inherited settings. + +`features` + + +The container for opt-in Security Hub feature settings. + +Optional, and available only in commercial AWS Regions. + +When omitted, all features are left unmanaged by the policy. + +Each feature is configured by its own child block, such as `network_scanning`. + +`network_scanning` + + +Controls the network scanning feature within the `features` map. + +Optional. When omitted, network scanning is left unmanaged by the policy. + +Contains its own `enable_in_regions` and `disable_in_regions` lists. + +`enable_in_regions` (within `network_scanning`) + + +List of Regions where network scanning should be enabled. + +Can contain specific Region names or `ALL_SUPPORTED`. + +Required field but can be empty. + +When using `ALL_SUPPORTED`, includes all Regions where Security Hub is enabled by this policy. + +Network scanning is enabled only in Regions where Security Hub is also enabled by this policy. + +`disable_in_regions` (within `network_scanning`) + + +List of Regions where network scanning should be disabled. + +Can contain specific Region names or `ALL_SUPPORTED`. + +Required field but can be empty. + +Takes precedence over `enable_in_regions` when Regions appear in both lists. @@ -94 +178 @@ The following examples demonstrate common Security Hub policy configurations. -The example below enables Security Hub in all current and future regions. By using `ALL_SUPPORTED` in the `enable_in_regions` list and leaving `disable_in_regions` empty, this policy ensures comprehensive security coverage as new regions become available. +The example below enables Security Hub in all current and future Regions. By using `ALL_SUPPORTED` in the `enable_in_regions` list and leaving `disable_in_regions` empty, this policy ensures comprehensive security coverage as new Regions become available. @@ -112 +196 @@ The example below enables Security Hub in all current and future regions. By usi -This example disables Security Hub in all regions including any future regions since `disable_in_regions` list takes precedence over `enable_in_regions`. +This example disables Security Hub in all Regions including any future Regions since `disable_in_regions` list takes precedence over `enable_in_regions`. @@ -131 +215 @@ This example disables Security Hub in all regions including any future regions s -The following example demonstrates how child policies can modify parent policy settings using inheritance operators. This approach allows for granular control while maintaining the overall policy structure. The child policy adds a new region to `enable_in_regions` and removes a region from `disable_in_regions`. +The following example demonstrates how child policies can modify parent policy settings using inheritance operators. This approach allows for granular control while maintaining the overall policy structure. The child policy adds a new Region to `enable_in_regions` and removes a Region from `disable_in_regions`. @@ -149 +233 @@ The following example demonstrates how child policies can modify parent policy s -This example shows how to enable Security Hub in multiple specific regions without using `ALL_SUPPORTED`. This provides precise control over which regions have Security Hub enabled, while leaving unspecified regions unmanaged by the policy. +This example shows how to enable Security Hub in multiple specific Regions without using `ALL_SUPPORTED`. This provides precise control over which Regions have Security Hub enabled, while leaving unspecified Regions unmanaged by the policy. @@ -170 +254 @@ This example shows how to enable Security Hub in multiple specific regions witho -The following example demonstrates how to handle regional compliance requirements by enabling Security Hub in most regions while explicitly disabling it in specific locations. The `disable_in_regions` list takes precedence, ensuring Security Hub remains disabled in those regions regardless of other policy settings. +The following example demonstrates how to handle regional compliance requirements by enabling Security Hub in most Regions while explicitly disabling it in specific locations. The `disable_in_regions` list takes precedence, ensuring Security Hub remains disabled in those Regions regardless of other policy settings. @@ -188,0 +273,183 @@ The following example demonstrates how to handle regional compliance requirement +The following example enables Security Hub in two Regions and enables network scanning in those same Regions. The `features` map is available only in commercial AWS Regions. + + + { + "securityhub":{ + "enable_in_regions":{ + "@@assign":[ + "us-east-1", + "us-west-2" + ] + }, + "disable_in_regions":{ + "@@assign":[ + + ] + }, + "features":{ + "network_scanning":{ + "enable_in_regions":{ + "@@assign":[ + "us-east-1", + "us-west-2" + ] + }, + "disable_in_regions":{ + "@@assign":[ + + ] + } + } + } + } + } + +This example enables Security Hub in three Regions but enables network scanning in only two of them. In `eu-west-1`, Security Hub is enabled while network scanning is left unmanaged by the policy because that Region is in neither feature list. + + + { + "securityhub":{ + "enable_in_regions":{ + "@@assign":[