Considerations Basic policy structure Policy components Security Hub CSPM policy examples

Security Hub CSPM policy syntax and examples

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

A Security Hub CSPM policy is a plaintext file structured according to the rules of JSON. Its syntax follows the syntax for all management policy types. For a complete discussion of that general syntax, see Understanding declarative policy inheritance. This topic applies that syntax to the specific requirements of the Security Hub CSPM policy type.

Considerations

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

Both enable_in_regions and disable_in_regions lists under the cspm_enablement key are required in the policy, though they can be empty.
When processing effective policies, disable_in_regions takes precedence over enable_in_regions.
Regions that appear in neither the enable_in_regions nor the disable_in_regions list are left unmanaged by the policy.
Child policies can modify parent policies using inheritance operators unless explicitly restricted.
The ALL_SUPPORTED designation includes both current and future Regions for Security Hub CSPM.
Region names must be valid and available in Security Hub CSPM.
The cspm_standards_controls object contains a complete specification of how Security Hub CSPM standards and controls are enabled or disabled and how custom control parameters are set across the Regions and accounts in scope of the policy.
The configurations in the cspm_standards_controls object only apply in Regions where Security Hub CSPM is enabled by the same effective policy. Disabling Security Hub CSPM in a Region also disables standards and controls in that Region.
By default, the Security Hub CSPM standards and control configurations under the default block apply to all Regions where Security Hub CSPM is set to be enabled by the policy.
Each policy requires a non-empty cspm_standards_controls object containing a default object with a default_control_association_status key set to either ENABLED or DISABLED.
The default_control_association_status determines the default enablement status of controls for standards enabled by the effective policy.
When processing control status, disabled_controls takes precedence over enabled_controls. Both disabled_controls and enabled_controls take precedence over default_control_association_status.
The cspm_standards_controls block also optionally supports Region-specific configuration overrides when you don't want a uniform Security Hub CSPM configuration across your members' in-scope Regions. Region-specific configurations completely replace the settings in the default block for the target Region or Regions.
Security Hub CSPM Organizations policies are available only in the commercial AWS Regions, the AWS GovCloud (US) Regions, and China Regions.
Security Hub CSPM Organizations policies do not support configuring multi-cloud standards and controls (for example, Azure).
Security Hub CSPM Organizations policies do not support configuring service-managed standards and controls (for example, the AWS Control Tower service-managed standard).
A policy can't list enabled_controls when default_control_association_status is ENABLED, or disabled_controls when it is DISABLED.
Each control in enabled_controls and disabled_controls must belong to a standard that the same policy enables.
Deprecated control IDs are accepted and have no effect.

Basic policy structure

A Security Hub CSPM policy uses this basic structure:


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"],
        "@@operators_allowed_for_child_policies": ["@@all"]
      },
      "disable_in_regions": {
        "@@assign": [],
        "@@operators_allowed_for_child_policies": ["@@all"]
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"],
          "@@operators_allowed_for_child_policies": ["@@all"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED",
            "@@operators_allowed_for_child_policies": ["@@all"]
          }
        }
      }
    }
  }
}

The preceding policy enables Security Hub CSPM in all current and future Regions where Security Hub CSPM is available, and enables the AWS Foundational Security Best Practices v1.0.0 standard and all of its associated controls in those Regions.

Policy components

Security Hub CSPM policies contain these key components:

Inheritance operators

@@assign overwrites inherited values. @@append adds new values to existing ones. @@remove removes specific values from inherited settings.

securityhub_cspm

The top-level container for policy settings. Required for all Security Hub CSPM policies.

cspm_enablement

Intermediary field for specifying which Regions are enabled or disabled by the policy. Contains enable_in_regions and disable_in_regions keys. Regions omitted from both are left ungoverned. Required field.

enable_in_regions

List of Regions where Security Hub CSPM should be enabled. Can contain specific Region names or ALL_SUPPORTED. Required field but accepts an empty list. When using ALL_SUPPORTED, includes future Regions.

disable_in_regions

List of Regions where Security Hub CSPM should be disabled. Can contain specific Region names or ALL_SUPPORTED. Required field but accepts an empty list. Takes precedence over enable_in_regions when Regions appear in both lists.

cspm_standards_controls

Intermediary field for specifying the Security Hub CSPM resource configurations for in-scope enabled Regions. Contains a complete specification of enabled or disabled standards and controls, and custom control parameters. Required field.

default

Container for the default Security Hub CSPM standards and control configuration applied to all policy-enabled Regions defined in the cspm_enablement object. Can be overridden per Region by a sibling Region key (for example, us-east-1) under the cspm_standards_controls object. Required field.

Region name (for example, us-east-1)

Optional Region-specific configuration block with the same structure as default. Fully replaces the default configuration for that Region. Has no effect in a Region where the policy doesn't enable Security Hub CSPM.

enabled_standards

List of standards to enable. Standards omitted from this list are governed as disabled. Pertains only to Security Hub CSPM managed standards for AWS (excludes multi-cloud standards such as Azure). Optional. If omitted, all standards are governed as disabled.

controls_configuration

Intermediary field for specifying configurations pertaining to controls enablement. Required field.

custom_control_parameters

Intermediary field for specifying custom control parameters. Contains a mapping of SecurityControlIds to a parameters object that maps ParameterNames to ParameterValues. Optional. If omitted, customizable control parameters are set to their defaults.

default_control_association_status

The default standards control association enablement status for the controls associated with the standards specified in enabled_standards. Also dictates the AutoEnableControls Hub setting. Valid values are ENABLED or DISABLED. Required field.

enabled_controls

List of controls for Security Hub CSPM to enable (by SecurityControlId). Takes precedence over default_control_association_status.

Only allowed when default_control_association_status is DISABLED.

disabled_controls

List of controls for Security Hub CSPM to disable (by SecurityControlId). Takes precedence over default_control_association_status. Takes precedence over enabled_controls when controls appear in both lists.

Only allowed when default_control_association_status is ENABLED.

Security Hub CSPM policy examples

The following examples demonstrate common Security Hub CSPM policy configurations.

This first example enables Security Hub CSPM 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. In each Region where Security Hub CSPM is enabled, the AWS Foundational Security Best Practices standard and all of its regionally available controls are also enabled.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"]
      },
      "disable_in_regions": {
        "@@assign": []
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          }
        }
      }
    }
  }
}

This example disables Security Hub CSPM in all Regions, including any future Regions, because the disable_in_regions list takes precedence over enable_in_regions. The configurations under default in cspm_standards_controls do not apply to any Region, because no Region has Security Hub CSPM enabled by the policy.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["us-east-1", "us-west-2"]
      },
      "disable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"]
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          }
        }
      }
    }
  }
}

This example enables Security Hub CSPM in multiple specific Regions without using ALL_SUPPORTED. This provides precise control over which Regions have Security Hub CSPM enabled, while leaving unspecified Regions unmanaged by the policy. In this case, four Regions (us-east-1, us-east-2, us-west-1, and eu-central-1) have the AWS Foundational Security Best Practices standard enabled, and all other Regions are left ungoverned.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["us-east-1", "us-east-2", "us-west-1", "eu-central-1"]
      },
      "disable_in_regions": {
        "@@assign": []
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          }
        }
      }
    }
  }
}

This example shows how to enable specific controls in Security Hub CSPM. This provides precise control over which controls are enabled and generate Security Hub CSPM findings. In this example, Security Hub CSPM is enabled in us-east-1, us-east-2, us-west-1, and eu-central-1. The default_control_association_status is set to DISABLED, and only the controls ACM.1, Account.1, Config.1, IAM.7, and EC2.20 are enabled.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["us-east-1", "us-east-2", "us-west-1", "eu-central-1"]
      },
      "disable_in_regions": {
        "@@assign": []
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "enabled_controls": {
            "@@assign": ["ACM.1", "Account.1", "Config.1", "IAM.7", "EC2.20"]
          },
          "default_control_association_status": {
            "@@assign": "DISABLED"
          }
        }
      }
    }
  }
}

The following example enables Security Hub CSPM in all current and future Regions. By default, every Region has only the AWS Foundational Security Best Practices v1.0.0 standard and all its controls enabled. However, in us-east-1 and us-west-2, both the AWS Foundational Security Best Practices v1.0.0 standard and the NIST Special Publication 800-171 Revision 2 standard are enabled, with all of their regionally available controls except ACM.1, which is explicitly disabled.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"]
      },
      "disable_in_regions": {
        "@@assign": []
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          }
        }
      },
      "us-east-1": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0", "nist-800-171/v/2.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          },
          "disabled_controls": {
            "@@assign": ["ACM.1"]
          }
        }
      },
      "us-west-2": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0", "nist-800-171/v/2.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          },
          "disabled_controls": {
            "@@assign": ["ACM.1"]
          }
        }
      }
    }
  }
}

This example uses the custom_control_parameters field to set custom control parameters in the Security Hub CSPM policy. By using ALL_SUPPORTED, this policy ensures comprehensive security coverage as new Regions become available. In each Region where Security Hub CSPM is enabled, the AWS Foundational Security Best Practices standard and all of its regionally available controls are enabled.

In addition, the policy sets the daysToExpiration customizable parameter for the ACM.1 control to 30 days instead of its default value. Parameters that aren't listed use their default values.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"]
      },
      "disable_in_regions": {
        "@@assign": []
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED"
          }
        },
        "custom_control_parameters": {
          "ACM.1": {
            "daysToExpiration": {
              "@@assign": 30
            }
          }
        }
      }
    }
  }
}

The following example enables Security Hub CSPM in most Regions and explicitly disables it in two Regions. Because disable_in_regions takes precedence, Security Hub CSPM stays disabled in those Regions regardless of other policy settings.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": { "@@assign": ["ALL_SUPPORTED"] },
      "disable_in_regions": { "@@assign": ["ap-east-1", "me-south-1"] }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": { "@@assign": "ENABLED" }
        }
      }
    }
  }
}

Security Hub CSPM policies don't have a home Region. The following example enables the AWS Foundational Security Best Practices standard in every Region, but disables controls that evaluate global IAM resources in every Region except us-east-1. This avoids duplicate findings for the same global resources.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": { "@@assign": ["ALL_SUPPORTED"] },
      "disable_in_regions": { "@@assign": [] }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": { "@@assign": "ENABLED" },
          "disabled_controls": {
            "@@assign": ["IAM.1", "IAM.2", "IAM.3", "IAM.4", "IAM.6"]
          }
        }
      },
      "us-east-1": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"]
        },
        "controls_configuration": {
          "default_control_association_status": { "@@assign": "ENABLED" }
        }
      }
    }
  }
}

The following example shows how a child policy can extend a parent policy with inheritance operators. The parent policy, attached to the organization root, sets the baseline and prevents child policies from disabling Security Hub CSPM in any Region.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": {
        "@@assign": ["ALL_SUPPORTED"],
        "@@operators_allowed_for_child_policies": ["@@none"]
      },
      "disable_in_regions": {
        "@@assign": [],
        "@@operators_allowed_for_child_policies": ["@@none"]
      }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@assign": ["aws-foundational-security-best-practices/v/1.0.0"],
          "@@operators_allowed_for_child_policies": ["@@append"]
        },
        "controls_configuration": {
          "default_control_association_status": {
            "@@assign": "ENABLED",
            "@@operators_allowed_for_child_policies": ["@@none"]
          }
        }
      }
    }
  }
}

The child policy, attached to an OU for payment workloads, adds the PCI DSS v4.0.1 standard with @@append. Accounts in that OU run both standards. All other accounts run only the baseline standard.


{
  "securityhub_cspm": {
    "cspm_enablement": {
      "enable_in_regions": { "@@append": [] },
      "disable_in_regions": { "@@append": [] }
    },
    "cspm_standards_controls": {
      "default": {
        "enabled_standards": {
          "@@append": ["pci-dss/v/4.0.1"]
        },
        "controls_configuration": {
          "default_control_association_status": { "@@assign": "ENABLED" }
        }
      }
    }
  }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Best practices

Amazon Bedrock policies