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).
Custom control parameters
Some Security Hub controls use parameters that affect how the control is evaluated. Typically, such controls are evaluated
against the default parameter values that Security Hub defines. However, for a subset of these controls, you can customize the parameter values. When you customize a parameter value for a control,
Security Hub starts evaluating the control against the value that you specify. If the resource underlying the control satisfies the custom value, Security Hub generates a PASSED
finding.
If the resource doesn't satisfy the custom value, Security Hub generates a FAILED
finding.
By customizing control parameters, you can refine the security best practices recommended and monitored by Security Hub
to align with your business requirements and security expectations. Instead of suppressing findings for a control, you can customize one or more of its
parameters to get findings that suit your security needs.
Here are some sample use cases for custom control parameters:
[CloudWatch.16] – CloudWatch log groups should be retained for a specified time period
You can specify the retention time period.
[IAM.7] – Password policies for IAM users should have strong configurations
You can specify parameters related to password strength.
-
[EC2.18] – Security groups should only allow unrestricted incoming traffic for authorized ports
You can specify which ports are authorized to permit unrestricted incoming traffic.
-
[Lambda.5] – VPC Lambda functions should operate in multiple Availability Zones
You can specify the minimum number of Availability Zones that produces a passed finding.
This section explains how to customize and manage control parameters.
How custom control parameters work
A control can have one or more customizable parameters. Possible data types for individual control parameters include the following:
Boolean
Double
Enum
EnumList
Integer
IntegerList
String
StringList
For some controls, acceptable parameter values must also fall into a
specified range to be valid. In these cases, Security Hub provides the acceptable range.
Security Hub chooses default parameter values and might occasionally update them. After you customize a control
parameter, its value continues to be the value that you specified for the parameter unless your change it. That is to say,
the parameter stops tracking updates to the default Security Hub value,
even if the custom value of the parameter matches the current, default value defined by Security Hub.
Here's an example for the control [ACM.1] – Imported and ACM-issued certificates should be renewed
after a specified time period:
{
"SecurityControlId": "ACM.1",
"Parameters": {
"daysToExpiration": {
"ValueType": "CUSTOM",
"Value": {
"Integer": 30
}
}
}
}
In the preceding example, the daysToExpiration
parameter has a custom value of 30
. The current
default value for this parameter is also 30
. If Security Hub changes the default value to 14
, the parameter in this
example won't track that change. It will retain a value of 30
.
If you want to track updates to the default Security Hub value for a parameter, set the ValueType
field to DEFAULT
instead of CUSTOM
. For more information, see
Reverting to default parameter values in a single
account and Region.
When you change a parameter value, you also trigger a new security check that evaluates the control based on the
new value. Security Hub then generates new control findings based on the new value. During periodic updates to control findings,
Security Hub also uses the new parameter value. If you change parameter values for a control, but haven't enabled any standards that include the control, Security Hub doesn't conduct
any security checks using the new values. You have to enable at least one relevant standard for Security Hub to evaluate the control based
on the new parameter value.
Custom parameter values apply across your enabled standards. You can't customize the parameters for a control that's
not supported in your current Region. For a list of Regional limits for individual controls, see Regional limits on controls.
Customizing control parameters
The instructions for customizing control parameters vary based on whether you use central configuration. Central
configuration is a feature that the delegated Security Hub administrator can use to manage Security Hub capabilities across Amazon Web Services Regions, accounts,
and organizational units (OUs) in their organization.
If your organization uses central configuration, the delegated administrator can create configuration policies that include custom
control parameters. These policies can be associated with centrally managed member accounts and OUs, and they take effect
in your home Region and all linked Regions. The delegated administrator can also designate one or more accounts
as self-managed, which allows the account owner to configure its own parameters separately in each Region. If your organization
doesn't use central configuration, you must customize control parameters separately in each account and Region.
Customizing control parameters across multiple accounts and Regions
When you use central configuration, you can customize control parameters for centrally managed accounts and OUs across multiple accounts and Regions.
We recommend using central configuration because it allows you to align control parameter values across different parts of your
organization. For example, all of your test accounts might use certain parameter values, and all production accounts might use different values.
If you're the delegated Security Hub administrator for an organization that uses central configuration, choose your
preferred method, and follow the steps to customize control parameters across multiple accounts and Regions.
- Security Hub console
-
To customize control parameters in multiple accounts and Regions
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
Ensure that you're signed in to the home Region.
-
In the navigation pane, choose Settings and Configuration.
-
Choose the Policies tab.
-
To create a new configuration policy that includes custom parameters, choose Create policy.
To specify custom parameters in an existing configuration policy, select the policy, and then choose Edit.
To create a new configuration policy with custom parameters
In the Custom policy section, choose the security standards and
controls that you want to enable.
Select Customize control parameters.
Select a control, and then specify custom values for one or more parameters.
To customize parameters for more controls, choose Customize additional control.
In the Accounts section, select the accounts or OUs that you want to apply the policy to.
Choose Next.
Choose Create policy and apply. In your home Region and all linked Regions, this action overrides the existing configuration settings
of accounts and OUs that are associated with this configuration policy. Accounts and OUs can be associated with a configuration policy
through direct application or inheritance from a parent.
To add or edit custom parameters in an existing configuration policy
In the Controls section, under Custom policy, specify
the new custom parameter values that you want.
If this is your first time customizing control parameters in this policy, select
Customize control parameters, and then select a control to customize. To
customize parameters for more controls, choose Customize additional control.
In the Accounts section, verify the accounts or OUs that you want to apply the policy to.
-
Choose Next.
-
Review your changes, and verify that they're correct. When you finish, choose Save policy and apply. In your home Region and all linked Regions, this action overrides the existing configuration settings
of accounts and OUs that are associated with this configuration policy. Accounts and OUs can be associated with a configuration policy
through direct application or inheritance from a parent.
- Security Hub API
-
To customize control parameters in multiple accounts and Regions
To create a new configuration policy with custom parameters
Invoke the CreateConfigurationPolicy API from the delegated administrator account in the home Region.
For the SecurityControlCustomParameters
object, provide the identifier of each control that you want to customize.
For the Parameters
object, provide the name of each parameter that you
want to customize. For each parameter that you customize, provide CUSTOM
for ValueType
.
For Value
, provide the data type of the parameter and the custom value. The Value
field
can't be empty when ValueType
is CUSTOM
. If your request
omits a parameter that the control supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by invoking the
GetSecurityControlDefinition API.
To add or edit custom parameters in an existing configuration policy
Invoke the UpdateConfigurationPolicy API from the delegated administrator account in the home Region.
For the Identifier
field, provide the Amazon Resource Name (ARN) or ID of the configuration policy that you want to update.
For the SecurityControlCustomParameters
object, provide the identifier of each control that you want to customize.
For the Parameters
object, provide the name of each parameter that you
want to customize. For each parameter that you customize, provide CUSTOM
for ValueType
.
For Value
, provide the data type of the parameter and the custom value. If your request
omits a parameter that the control supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by invoking the
GetSecurityControlDefinition API.
Example API request to create a new configuration policy:
{
"Name": "SampleConfigurationPolicy",
"Description": "Configuration policy for production accounts",
"ConfigurationPolicy": {
"SecurityHub": {
"ServiceEnabled": true,
"EnabledStandardIdentifiers": [
"arn:aws-cn:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0"},
"arn:aws-cn:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0"}
],
"SecurityControlsConfiguration": {
"DisabledSecurityControlIdentifiers": [
"CloudTrail.2"
],
"SecurityControlCustomParameters": [
{
"SecurityControlId": "ACM.1",
"Parameters": {
"daysToExpiration": {
"ValueType": "CUSTOM",
"Value": {
"Integer": 15
}
}
}
}
]
}
}
}
}
- Amazon CLI
-
To customize control parameters in multiple accounts and Regions
To create a new configuration policy with custom parameters
Run the create-configuration-policy command from the delegated administrator account in the
home Region.
For the SecurityControlCustomParameters
object, provide the identifier of each control that you want to customize.
For the Parameters
object, provide the name of each parameter that you
want to customize. For each parameter that you customize, provide CUSTOM
for ValueType
.
For Value
, provide the data type of the parameter and the custom value. The Value
field
can't be empty when ValueType
is CUSTOM
. If your request
omits a parameter that the control supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by running the
get-security-control-definition command.
To add or edit parameters in an existing configuration policy
To add or update custom input parameters in an existing configuration policy, run the
update-configuration-policy command from the delegated administrator account in the home Region.
For the identifier
field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.
For the SecurityControlCustomParameters
object, provide the identifier of each control that you want to customize.
For the Parameters
object, provide the name of each parameter that you
want to customize. For each parameter that you customize, provide CUSTOM
for ValueType
.
For Value
, provide the data type of the parameter and the custom value. If your request
omits a parameter that the control supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by running the
get-security-control-definition command.
Example command to create a new configuration policy:
$
aws securityhub create-configuration-policy \
--region us-east-1
\
--name "SampleConfigurationPolicy"
\
--description "Configuration policy for production accounts"
\
--configuration-policy '{"SecurityHub": {"ServiceEnabled": true
, "EnabledStandardIdentifiers": ["arn:aws-cn:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0","arn:aws-cn:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0"
],"SecurityControlsConfiguration":{"DisabledSecurityControlIdentifiers": ["CloudTrail.2"
], "SecurityControlCustomParameters": [{"SecurityControlId": "ACM.1"
, "Parameters": {"daysToExpiration": {"ValueType": "CUSTOM"
, "Value": "Integer": 15
}}}]}}}'
Customizing control parameters in a single account and Region
If you don't use central configuration or have a self-managed account,
you can customize control parameters for your account in one
Region at a time
Choose your preferred method, and follow the steps to customize control parameters. Your changes apply only to your
account in the current Region. To customize the control parameters in additional Regions, repeat the following steps in
each additional account and Region in which you want to customize parameters. The same control can use different parameter values
in different Regions.
- Security Hub console
-
To customize control parameters in one account and Region
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
-
In the navigation pane, choose Controls. In the table, choose a control that supports custom
parameters and you want to change the parameters for. The Custom parameters column indicates which controls support custom parameters.
-
On the details page for the control, choose the Parameters tab, and then choose
Edit.
-
Specify the parameter values that you want.
-
Optionally, in the Reason for change section, select a reason for customizing
the parameters.
-
Choose Save.
- Security Hub API
-
To customize control parameters in one account and Region
Invoke the UpdateSecurityControl API.
For SecurityControlId
, provide the ID of the control that
you want to customize.
For the Parameters
object, provide the name of each parameter that you want to
customize. For each parameter that you customize, provide
CUSTOM
for ValueType
. For
Value
, provide the data type of the parameter and
the custom value. If your request omits a parameter that the control
supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by
invoking the GetSecurityControlDefinition
API.
Optionally, for LastUpdateReason
, provide a reason for customizing the control parameters.
Example API request:
{
"SecurityControlId": "ACM.1",
"Parameters": {
"daysToExpiration": {
"ValueType": "CUSTOM",
"Value": {
"Integer": 15
}
}
},
"LastUpdateReason": "Internal compliance requirement"
}
- Amazon CLI
-
To customize control parameters in one account and Region
Run the update-security-control
command.
For security-control-id
, provide the ID of the control that
you want to customize.
For the parameters
object, provide the name of each parameter that you want to
customize. For each parameter that you customize, provide
CUSTOM
for ValueType
. For
Value
, provide the data type of the parameter and
the custom value. If your request omits a parameter that the control
supports, that parameter retains its current value. You can find
supported parameters, data types, and valid values for a control by
running the get-security-control-definition
command.
Optionally, for last-update-reason
, provide a reason for customizing the control parameters.
Example command:
$
aws securityhub update-security-control \
--region us-east-1
\
--security-control-id ACM.1
\
--parameters '{"daysToExpiration": {"ValueType": "CUSTOM"
, "Value": {"Integer": 15
}}}' \
--last-update-reason "Internal compliance requirement"
Checking the status of control parameters
It's important to validate and check the status of changes to control parameters. This helps ensure that a control works as you expect and provides the intended
security value. To verify that a parameter update was successful, you can review the details of the control on the Security Hub console. On the
console, choose the control to display its details. The Parameters tab shows the status of the parameter change.
Programmatically, if your request to update a parameter is valid, the
value of the UpdateStatus
field is UPDATING
in a response to the BatchGetSecurityControls operation.
. This means that the update was valid, but your findings might
not yet include the updated parameter values. When the value of UpdateState
changes to
READY
, your findings begin to include the updated parameter values.
The UpdateSecurityControl
operation returns an InvalidInputException
response
for invalid parameter values. The response provides additional details about the reason for failure. For example, you might have specified a
value that's outside the valid range for a parameter. Or, you specified a value that doesn't use the correct data type. Submit your request
again with valid input. If a parameter update is unsuccessful, Security Hub retains the current value for the parameter.
If an internal failure occurs when you try to update a parameter value, Security Hub automatically retries if you
have Amazon Config enabled. For more information, see Configuring Amazon Config.
Reviewing control parameters
You can review the current values for individual control parameters in your account. If you use central configuration, the
delegated Security Hub administrator can also review parameter values that are specified in a configuration policy.
Choose your preferred method, and follow the steps
to review current control parameter values.
- Security Hub console
-
To review current parameter values
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
-
In the navigation pane, choose Controls. Choose a control.
-
Choose the Parameters tab. This tab shows the current parameter values for the control.
- Security Hub API
-
To review current parameter values
Invoke the BatchGetSecurityControls API, and provide one or more security control IDs or
ARNs. The Parameters
object in the response shows the current parameter values for the specified controls.
Example API request:
{
"SecurityControlIds": ["APIGateway.1", "CloudWatch.15", "IAM.7"]
}
- Amazon CLI
-
To review current parameter values
Run the batch-get-security-controls command, and
provide one or more security control IDs or ARNs. The
Parameters
object in the response shows the current
parameter values for the specified controls.
Example command:
$
aws securityhub batch-get-security-controls \
--region us-east-1
\
--security-control-ids '["APIGateway.1", "CloudWatch.15", "IAM.7"
]'
Choose your preferred method to view the current parameter values in a central configuration policy.
- Security Hub console
-
To review current parameter values in a configuration policy
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
Sign in using the credentials of the delegated Security Hub administrator account in the home Region.
-
In the navigation pane, choose Settings and Configuration.
-
On the Policies tab, select the configuration policy, and then choose View details. The
policy details then appear, including current parameter values.
- Security Hub API
-
To review current parameter values in a configuration policy
Invoke the GetConfigurationPolicy API from the delegated administrator account in the home
Region.
Provide the ARN or ID of
the configuration policy whose details you want to see. The response includes current parameter values.
{
"Identifier": "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
- Amazon CLI
-
To review current parameter values in a configuration policy
Run the get-configuration-policy command from the delegated administrator account in the home Region.
Provide the ARN or ID of
the configuration policy whose details you want to see. The response includes current parameter values.
$
aws securityhub get-configuration-policy \
--region us-east-1
\
--identifier "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
Your control findings also show current parameter values. In the Amazon Security Finding Format (ASFF) syntax, these
values appear in the Parameters
field of the Compliance
object.
To review findings on the Security Hub console, choose Findings in the navigation pane. To review findings
programmatically, use the GetFindings
operation.
After release of the custom control parameters feature, Security Hub will update existing control findings to include the
Parameters
ASFF field. This may take up to 24 hours.
Reverting to default control parameter values
A control parameter can have a default value that Security Hub defines. We might update the default
value for a parameter to reflect evolving security best practices. If you haven't specified a custom value for a control parameter,
the control automatically tracks those updates and uses the new default value.
You can revert to using default parameter values for a control. How you do this depends on whether you use central configuration.
Not all control parameters have a default Security Hub value. In such cases, when
ValueType
is set to DEFAULT
, there isn't a specific default value that Security Hub uses. Rather,
Security Hub ignores the parameter in the absence of a custom value.
Reverting to default parameter values across multiple accounts and Regions
If you use central configuration, you can revert control parameters for centrally managed accounts and OUs across multiple accounts and Regions.
Choose your preferred method, and follow the steps to revert to default parameter values across multiple accounts and Regions using central configuration.
- Security Hub console
-
To revert to default parameter values in multiple accounts and Regions
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
Sign in using the credentials of the Security Hub delegated administrator account in the home Region.
-
In the navigation pane, choose Settings and Configuration.
-
Choose the Policies tab.
-
Select a policy, and then choose Edit.
-
Under Custom policy, the Controls section shows a
list of controls that you specified custom parameters for.
-
Find the control that has one or more parameter values to revert. Then, choose Remove to revert to the default values.
In the Accounts section, verify the accounts or OUs that you want to apply the policy to.
-
Choose Next.
-
Review your changes, and verify that they're correct. When you finish, choose Save policy and apply. In your home Region and all linked Regions, this action overrides the existing configuration settings
of accounts and OUs that are associated with this configuration policy. Accounts and OUs can be associated with a configuration policy
through direct application or inheritance from a parent.
- Security Hub API
-
To revert to default parameter values in multiple accounts and Regions
Invoke the UpdateConfigurationPolicy API from the delegated administrator account in the
home Region.
For the Identifier
field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.
For the SecurityControlCustomParameters
object, provide the identifier of each control for which you want to revert one or more parameters.
In the Parameters
object, for each parameter that you want to revert, provide DEFAULT
for the
ValueType
field. When ValueType
is set to DEFAULT
, you don't need to provide a value for the Value
field.
If a value is included in your request, Security Hub ignores it. If your request
omits a parameter that the control supports, that parameter retains its current value.
If you omit a control object from the SecurityControlCustomParameters
field, Security Hub reverts all custom parameters for the control to their default values. A
completely empty list for SecurityControlCustomParameters
reverts custom parameters for all controls to their default values.
Example API request:
{
"Identifier": "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"Name": "TestConfigurationPolicy",
"Description": "Updated configuration policy",
"UpdatedReason": "Revert ACM.1 parameter to default value",
"ConfigurationPolicy": {
"SecurityHub": {
"ServiceEnabled": true,
"EnabledStandardIdentifiers": [
"arn:aws-cn:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0"},
"arn:aws-cn:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0"}
],
"SecurityControlsConfiguration": {
"DisbledSecurityControlIdentifiers": [
"CloudTrail.2"
],
"SecurityControlCustomParameters": [
{
"SecurityControlId": "ACM.1",
"Parameters": {
"daysToExpiration": {
"ValueType": "DEFAULT"
}
}
}
]
}
}
}
}
- Amazon CLI
-
To revert to default parameter values in multiple accounts and Regions
Run the update-configuration-policy command from the delegated administrator account in the home Region.
For the identifier
field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.
For the SecurityControlCustomParameters
object, provide the identifier of each control for which you want to revert one or more parameters.
In the Parameters
object, for each parameter that you want to revert, provide DEFAULT
for the
ValueType
field. When ValueType
is set to DEFAULT
, you don't need to provide a value for the Value
field.
If a value is included in your request, Security Hub ignores it. If your request
omits a parameter that the control supports, that parameter retains its current value.
If you omit a control object from the SecurityControlCustomParameters
field, Security Hub reverts all custom parameters for the control to their default values. A
completely empty list for SecurityControlCustomParameters
reverts custom parameters for all controls to their default values.
Example command:
$
aws securityhub create-configuration-policy \
--region us-east-1
\
--identifier "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
" \
--name "TestConfigurationPolicy"
\
--description "Updated configuration policy"
\
--updated-reason "Revert ACM.1 parameter to default value"
--configuration-policy '{"SecurityHub": {"ServiceEnabled": true
, "EnabledStandardIdentifiers": ["arn:aws-cn:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0
","arn:aws-cn:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0
"],"SecurityControlsConfiguration":{"DisabledSecurityControlIdentifiers": ["CloudTrail.2"]
, "SecurityControlCustomParameters": [{"SecurityControlId": "ACM.1"
, "Parameters": {"daysToExpiration
": {"ValueType": "DEFAULT"
}}}]}}}'
Reverting to default parameter values in a single
account and Region
If you don't use central configuration or have a self-managed account, you can revert to using default parameter values
for your account in one Region at a time.
Choose your preferred method, and follow the steps to revert to default parameter values for your account in a
single Region. To revert to default parameter values in additional Regions, repeat these steps in each additional Region.
If you disable Security Hub, your custom control parameters are reset. If you enable Security Hub again in the future, all
controls will use default parameter values to start.
- Security Hub console
-
To revert to default parameter values in one account and Region
Open the Amazon Security Hub console at https://console.amazonaws.cn/securityhub/.
-
In the navigation pane, choose Controls. Choose the control that you want to revert to
default parameter values.
-
On the Parameters
tab, choose Customized next to a control parameter. Then, choose Remove customization.
This parameter now uses the default Security Hub value and tracks future updates to the default value.
-
Repeat the preceding step for each parameter value that you want to revert.
- Security Hub API
-
To revert to default parameter values in one account and Region
Invoke the UpdateSecurityControl API.
For SecurityControlId
, provide the ARN or ID of the control whose
parameters you want to revert.
In the Parameters
object, for each parameter that you want to revert, provide DEFAULT
for the
ValueType
field. When ValueType
is set to DEFAULT
, you don't need to provide a value for the Value
field.
If a value is included in your request, Security Hub ignores it.
Optionally, for LastUpdateReason
, provide a reason for reverting to default parameter values.
Example API request:
{
"SecurityControlId": "ACM.1",
"Parameters": {
"daysToExpiration": {
"ValueType": "DEFAULT"
},
"LastUpdateReason": "New internal requirement"
}
- Amazon CLI
-
To revert to default parameter values in one account and Region
Run the update-security-control command.
For security-control-id
, provide the ARN or ID of the control whose
parameters you want to revert.
In the parameters
object, for each parameter that you want to revert, provide DEFAULT
for the
ValueType
field. When ValueType
is set to DEFAULT
, you don't need to provide a value for the Value
field.
If a value is included in your request, Security Hub ignores it.
Optionally, for last-update-reason
, provide a reason for reverting to default parameter values.
Example command:
$
aws securityhub update-security-control \
--region us-east-1
\
--security-control-id ACM.1
\
--parameters '{"daysToExpiration": {"ValueType": "DEFAULT"
}}' \
--last-update-reason "New internal requirement"
Controls that support custom parameters
For a list of security controls that support custom parameters, you can refer to the
Controls page on the Security Hub console or the Security Hub controls reference. To retrieve this list programmatically, you can use the
ListSecurityControlDefinitions operation. In the response, the CustomizableProperties
object indicates
which controls support customizable parameters.