Custom control parameters - AWS Security Hub

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 AWS 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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

    Ensure that you're signed in to the home Region.

  2. In the navigation pane, choose Settings and Configuration.

  3. Choose the Policies tab.

  4. 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

    1. In the Custom policy section, choose the security standards and controls that you want to enable.

    2. Select Customize control parameters.

    3. Select a control, and then specify custom values for one or more parameters.

    4. To customize parameters for more controls, choose Customize additional control.

    5. In the Accounts section, select the accounts or OUs that you want to apply the policy to.

    6. Choose Next.

    7. 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

    1. In the Controls section, under Custom policy, specify the new custom parameter values that you want.

    2. 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.

    3. In the Accounts section, verify the accounts or OUs that you want to apply the policy to.

    4. Choose Next.

    5. 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
  1. Invoke the CreateConfigurationPolicy API from the delegated administrator account in the home Region.

  2. For the SecurityControlCustomParameters object, provide the identifier of each control that you want to customize.

  3. 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
  1. Invoke the UpdateConfigurationPolicy API from the delegated administrator account in the home Region.

  2. For the Identifier field, provide the Amazon Resource Name (ARN) or ID of the configuration policy that you want to update.

  3. For the SecurityControlCustomParameters object, provide the identifier of each control that you want to customize.

  4. 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:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0"}, "arn:aws: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 } } } } ] } } } }
AWS CLI

To customize control parameters in multiple accounts and Regions

To create a new configuration policy with custom parameters
  1. Run the create-configuration-policy command from the delegated administrator account in the home Region.

  2. For the SecurityControlCustomParameters object, provide the identifier of each control that you want to customize.

  3. 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
  1. 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.

  2. For the identifier field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.

  3. For the SecurityControlCustomParameters object, provide the identifier of each control that you want to customize.

  4. 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:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0","arn:aws: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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. 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.

  3. On the details page for the control, choose the Parameters tab, and then choose Edit.

  4. Specify the parameter values that you want.

  5. Optionally, in the Reason for change section, select a reason for customizing the parameters.

  6. Choose Save.

Security Hub API
To customize control parameters in one account and Region
  1. Invoke the UpdateSecurityControl API.

  2. For SecurityControlId, provide the ID of the control that you want to customize.

  3. 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.

  4. 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" }
AWS CLI
To customize control parameters in one account and Region
  1. Run the update-security-control command.

  2. For security-control-id, provide the ID of the control that you want to customize.

  3. 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.

  4. 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 AWS Config enabled. For more information, see Configuring AWS 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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. In the navigation pane, choose Controls. Choose a control.

  3. 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"] }
AWS 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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

    Sign in using the credentials of the delegated Security Hub administrator account in the home Region.

  2. In the navigation pane, choose Settings and Configuration.

  3. 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
  1. Invoke the GetConfigurationPolicy API from the delegated administrator account in the home Region.

  2. Provide the ARN or ID of the configuration policy whose details you want to see. The response includes current parameter values.

{ "Identifier": "arn:aws:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }
AWS CLI
To review current parameter values in a configuration policy
  1. Run the get-configuration-policy command from the delegated administrator account in the home Region.

  2. 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:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

Your control findings also show current parameter values. In the AWS 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.

Note

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.

Note

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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

    Sign in using the credentials of the Security Hub delegated administrator account in the home Region.

  2. In the navigation pane, choose Settings and Configuration.

  3. Choose the Policies tab.

  4. Select a policy, and then choose Edit.

  5. Under Custom policy, the Controls section shows a list of controls that you specified custom parameters for.

  6. Find the control that has one or more parameter values to revert. Then, choose Remove to revert to the default values.

  7. In the Accounts section, verify the accounts or OUs that you want to apply the policy to.

  8. Choose Next.

  9. 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
  1. Invoke the UpdateConfigurationPolicy API from the delegated administrator account in the home Region.

  2. For the Identifier field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.

  3. For the SecurityControlCustomParameters object, provide the identifier of each control for which you want to revert one or more parameters.

  4. 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.

Warning

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: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:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0"}, "arn:aws:securityhub:::ruleset/cis-aws-foundations-benchmark/v/1.2.0"} ], "SecurityControlsConfiguration": { "DisbledSecurityControlIdentifiers": [ "CloudTrail.2" ], "SecurityControlCustomParameters": [ { "SecurityControlId": "ACM.1", "Parameters": { "daysToExpiration": { "ValueType": "DEFAULT" } } } ] } } } }
AWS CLI
To revert to default parameter values in multiple accounts and Regions
  1. Run the update-configuration-policy command from the delegated administrator account in the home Region.

  2. For the identifier field, provide the Amazon Resource Name (ARN) or ID of the policy that you want to update.

  3. For the SecurityControlCustomParameters object, provide the identifier of each control for which you want to revert one or more parameters.

  4. 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.

Warning

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: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:securityhub:us-east-1::standards/aws-foundational-security-best-practices/v/1.0.0","arn:aws: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.

Note

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
  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. In the navigation pane, choose Controls. Choose the control that you want to revert to default parameter values.

  3. 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.

  4. 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
  1. Invoke the UpdateSecurityControl API.

  2. For SecurityControlId, provide the ARN or ID of the control whose parameters you want to revert.

  3. 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.

  4. 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" }
AWS CLI
To revert to default parameter values in one account and Region
  1. Run the update-security-control command.

  2. For security-control-id, provide the ARN or ID of the control whose parameters you want to revert.

  3. 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.

  4. 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.