Viewing Security Hub configuration policies - Amazon Security Hub
Association status of a configurationCommon reasons for association failure
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).

Viewing Security Hub configuration policies

The delegated administrator account can view Amazon Security Hub configuration policies for an organization and their details.

Choose your preferred method, and follow the steps to view your configuration policies.

Console
To view configuration policies

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

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

  3. Choose the Policies tab to view an overview of your configuration policies.

  4. Select a configuration policy, and choose View details to see additional details about it.

API

To view configuration policies

To view a summary list of all your configuration policies, invoke the ListConfigurationPolicies API from the Security Hub delegated administrator account in your home Region. You can provide optional pagination parameters

Example API request:

{
    "MaxResults": 5,
    "NextToken": "U2FsdGVkX19nUI2zoh+Pou9YyutlYJHWpn9xnG4hqSOhvw3o2JqjI23QDxdf"
}

To view details about a specific configuration policy, invoke the GetConfigurationPolicy API from the Security Hub delegated administrator account in your home Region. Provide the Amazon Resource Name (ARN) or ID of the configuration policy whose details you want to see.

Example API request:

{
    "Identifier": "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

To view a summary list of all your configuration policies and their associations, invoke the ListConfigurationPolicyAssociations API from the Security Hub delegated administrator account in your home Region. Optionally, you can provide pagination parameters or filter the results by a specific policy ID, association type, or association status.

Example API request:

{
    "AssociationType": "APPLIED"
}

To view associations for a specific account, OU, or the root, invoke the GetConfigurationPolicyAssociation or BatchGetConfigurationPolicyAssociations API from the Security Hub delegated administrator account in your home Region. For Target, provide the account number, OU ID, or root ID.

{
    "Target": {"AccountId": "123456789012"}
}
Amazon CLI

To view configuration policies

To view a summary list of all your configuration policies, run the list-configuration-policies command from the Security Hub delegated administrator account in your home Region.

Example command:

aws securityhub --region us-east-1 list-configuration-policies \
--max-items 5 \
--starting-token U2FsdGVkX19nUI2zoh+Pou9YyutlYJHWpn9xnG4hqSOhvw3o2JqjI23QDxdf

To view details about a specific configuration policy, run the get-configuration-policy command from the Security Hub delegated administrator account in your home Region. Provide the Amazon Resource Name (ARN) or ID of the configuration policy whose details you want to see.

aws securityhub --region us-east-1 get-configuration-policy \
--identifier "arn:aws-cn:securityhub:us-east-1:123456789012:configuration-policy/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

To view a summary list of all your configuration policies and their account associations, run the list-configuration-policy-associations command from the Security Hub delegated administrator account in your home Region. Optionally, you can provide pagination parameters or filter the results by a specific policy ID, association type, or association status.

aws securityhub --region us-east-1 list-configuration-policy-associations \
--association-type "APPLIED"

To view associations for a specific account, run the get-configuration-policy-association or batch-get-configuration-policy-associations command from the Security Hub delegated administrator account in your home Region. For target, provide the account number, OU ID, or root ID.

aws securityhub --region us-east-1 get-configuration-policy-association \
--target '{"AccountId": "123456789012"}'

Association status of a configuration

The following central configuration API operations return a field called AssociationStatus:

  • BatchGetConfigurationPolicyAssociations

  • GetConfigurationPolicyAssociation

  • ListConfigurationPolicyAssociations

  • StartConfigurationPolicyAssociation

This field is returned both when the underlying configuration is a configuration policy and when it's self-managed behavior.

The value of AssociationStatus tells you whether a policy association is pending or in a state of success or failure. It can take up to 24 hours for the status to change from PENDING to SUCCESS or FAILURE. The association status of a parent OU or the root depends on the status of its children. If the association status of all the children is SUCCESS, the association status of the parent is SUCCESS. If the association status of one or more children is FAILED, the association status of the parent is FAILED.

The value of AssociationStatus also depends on all Regions. If the association succeeds in the home Region and all linked Regions, the value of AssociationStatus is SUCCESS. If the association fails in one or more of these Regions, the value of AssociationStatus is FAILED.

The following behavior also impacts the value of AssociationStatus:

  • If the target is a parent OU or the root, it has an AssociationStatus of SUCCESS or FAILED only when all of the children have a SUCCESS or FAILED status. If the association status of a child account or OU changes (for example, when a linked Region is added or removed) after you first associate the parent with a configuration, the change doesn't update the association status of the parent unless you invoke the StartConfigurationPolicyAssociation API again.

  • If the target is an account, it has an AssociationStatus of SUCCESS or FAILED only if the association has a result of SUCCESS or FAILED in the home Region and all linked Regions. If the association status of a target account changes (for example, when a linked Region is added or removed) after you first associate it with a configuration, its association status is updated. However, the change doesn't update the association status of the parent unless you invoke the StartConfigurationPolicyAssociation API again.

If you add a new linked Region, Security Hub replicates your existing associations that are in a PENDING, SUCCESS, or FAILED state in the new Region.

Common reasons for association failure

A configuration policy association might fail for the following common reasons:

  • Organizations management account isn't a member – If you want to associate a configuration policy with the Organizations management account, that account must already have Security Hub enabled. This makes the management account a member account in the organization.

  • Amazon Config isn't enabled or properly configured – To enable standards in a configuration policy, Amazon Config must be enabled and configured to record relevant resources.

  • Must associate from delegated administrator account – You can only associate a policy with target accounts and OUs when you're signed in to the delegated administrator account.

  • Must associate from home Region – You can only associate a policy with target accounts and OUs when you're signed in to the home Region.

  • Opt-in Region not enabled – Policy association fails for a member account or OU in a linked Region if it's an opt-in Region that the delegated administrator hasn't enabled. You can retry after enabling the Region from the delegated administrator account.

  • Member account suspended – Policy association fails if you try to associate a policy with a suspended member account.