View a markdown version of this page

Security Hub policy syntax and examples - Amazon Organizations
ConsiderationsBasic policy structurePolicy componentsSecurity Hub policy examples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Security Hub policy syntax and examples

Security Hub policies follow a standardized JSON syntax that defines how Security Hub is enabled and configured across your organization. Understanding the policy structure helps you create effective policies for your security requirements.

Considerations

Before creating Security Hub policies, understand these key points about policy syntax:

  • Both enable_in_regions and disable_in_regions lists are required in the policy, though they can be empty.

  • When processing effective policies, disable_in_regions takes precedence over enable_in_regions.

  • Child policies can modify parent policies using inheritance operators unless explicitly restricted.

  • The ALL_SUPPORTED designation includes both current and future Regions.

  • Region names must be valid and available in Security Hub.

  • The features map is optional and is available only in commercial Amazon Regions (Regions other than the Amazon GovCloud (US) Regions and the China Regions). It is not available in the Amazon 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.

Basic policy structure

A Security Hub policy uses this basic structure:

{
  "securityhub": {
    "enable_in_regions": {
      "@@append": ["ALL_SUPPORTED"],
      "@@operators_allowed_for_child_policies": ["@@all"]
    },
    "disable_in_regions": {
      "@@append": [],
      "@@operators_allowed_for_child_policies": ["@@all"]
    }
  }
}

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 Amazon 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"]
        }
      }
    }
  }
}

Policy components

Security Hub policies contain these key components:

securityhub

The top-level container for policy settings.

Required for all Security Hub policies.

enable_in_regions

List of Regions where Security Hub should be enabled.

Can contain specific Region names or ALL_SUPPORTED.

Required field but can be empty.

When using ALL_SUPPORTED, includes future Regions.

disable_in_regions

List of Regions where Security Hub 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.

Inheritance operators

@@assign - Overwrites inherited values.

@@append - Adds new values to existing ones.

@@remove - Removes specific values from inherited settings.

features

The container for opt-in Security Hub feature settings.

Optional, and available only in commercial Amazon 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.

Security Hub policy examples

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.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            
         ]
      }
   }
}

This example disables Security Hub in all Regions including any future Regions since disable_in_regions list takes precedence over enable_in_regions.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "us-east-1",
            "us-west-2"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      }
   }
}

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.

{
   "securityhub":{
      "enable_in_regions":{
         "@@append":[
            "eu-central-1"
         ]
      },
      "disable_in_regions":{
         "@@remove":[
            "us-west-2"
         ]
      }
   }
}

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.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "us-east-1",
            "us-west-2",
            "eu-west-1",
            "ap-southeast-1"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            
         ]
      }
   }
}

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.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            "ap-east-1",
            "me-south-1"
         ]
      }
   }
}

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 Amazon 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":[
            "us-east-1",
            "us-west-2",
            "eu-west-1"
         ]
      },
      "disable_in_regions":{
         "@@assign":[

         ]
      },
      "features":{
         "network_scanning":{
            "enable_in_regions":{
               "@@assign":[
                  "us-east-1",
                  "us-west-2"
               ]
            },
            "disable_in_regions":{
               "@@assign":[

               ]
            }
         }
      }
   }
}

The following example enables network scanning in us-east-1 and disables it in us-west-2. Because disable_in_regions takes precedence, network scanning remains disabled in us-west-2 even when a Region appears in both lists.

{
   "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"
               ]
            },
            "disable_in_regions":{
               "@@assign":[
                  "us-west-2"
               ]
            }
         }
      }
   }
}

This example keeps Security Hub enabled in all current and future Regions while disabling network scanning in all of them, since the disable_in_regions list takes precedence.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[

         ]
      },
      "features":{
         "network_scanning":{
            "enable_in_regions":{
               "@@assign":[

               ]
            },
            "disable_in_regions":{
               "@@assign":[
                  "ALL_SUPPORTED"
               ]
            }
         }
      }
   }
}

This example enables Security Hub in all current and future Regions and leaves network scanning unmanaged by the policy by using empty feature lists. This has the same effect as omitting the features map.

{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[

         ]
      },
      "features":{
         "network_scanning":{
            "enable_in_regions":{
               "@@assign":[

               ]
            },
            "disable_in_regions":{
               "@@assign":[

               ]
            }
         }
      }
   }
}

The following example demonstrates how a child policy can extend a parent policy's network scanning Regions using inheritance operators. The child policy adds a Region to the inherited enable_in_regions list with @@append, the same way inheritance works on the top-level Region lists.

{
   "securityhub":{
      "features":{
         "network_scanning":{
            "enable_in_regions":{
               "@@append":[
                  "us-west-2"
               ]
            }
         }
      }
   }
}