Understanding control parameters in Security Hub

Some controls in AWS Security Hub 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 modify the parameter values. When you modify a control parameter value, 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 modifying control parameters and setting custom values:

This section covers things to consider when you modify control parameters.

Effect of modifying control parameter values

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.

A control can have one or more customizable parameters. Possible data types for each control parameter include the following:

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 Security Hub controls.

For some controls, acceptable parameter values must 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 control parameters in a single account and Region.

Controls that support custom parameters

For a list of security controls that support custom parameters, see the Controls page of 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.