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

Integration use cases and required permissions

Amazon Security Hub allows Amazon customers to receive findings from APN Partners. The partner's products might run either inside or outside of the customer's Amazon account. The permission configuration in the customer's account differs based on the model that the partner product uses.

In Security Hub, the customer always controls which partners can send findings to the customer's account. Customers can revoke permissions from a partner at any time.

To enable a partner to send security findings to their account, the customer first subscribes to the partner product in Security Hub. The subscription step is necessary for all of the use cases that are outlined below. For details on how customers manage product integrations, see Managing product integrations in the Amazon Security Hub User Guide.

After a customer subscribes to a partner product, Security Hub automatically creates a managed resource policy. The policy grants the partner product permission to use the BatchImportFindings API operation to send findings to Security Hub for the customer’s account.

Here are the common cases for partner products that integrate with Security Hub. The information includes the additional permissions required for each use case.

Partner hosted: findings sent from partner account

This use case covers partners who host a product in their own Amazon account. To send security findings for an Amazon customer, the partner calls the BatchImportFindings API operation from the partner product account.

For this use case, the customer account only needs the permissions that are established when the customer subscribes to the partner product.

In the partner account, the IAM principal that calls the BatchImportFindings API operation must have an IAM policy that allows the principal to call BatchImportFindings.

Enabling a partner product to send findings to the customer in Security Hub is a two-step process:

To send security findings related to the customer’s account, the partner product uses their own credentials to call the BatchImportFindings API operation.

Here is an example of an IAM policy that grants the principal in the partner account the necessary Security Hub permissions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "securityhub:BatchImportFindings",
            "Resource": "arn:aws:securityhub:us-west-1:*:product-subscription/company-name/product-name"
        }
    ]
}

Partner hosted: findings sent from the customer account

This use case covers partners who host a product in their own Amazon account, but use a cross-account role to access the customer's account. They call the BatchImportFindings API operation from the customer’s account.

For this use case, to call the BatchImportFindings API operation, the partner account assumes a customer managed IAM role in the customer's account.

This call is made from the customer's account. Therefore, the managed resource policy must allow the product ARN for the partner product's account to be used in the call. The Security Hub managed resource policy grants permission for the partner product account and the partner product ARN. The product ARN is the partner's unique identifier as a provider. Because the call does not come from the partner product account, the customer must explicitly grant permission for the partner product to send findings to Security Hub.

The best practice for cross-account roles between partner and customer accounts is to use an external identifier that the partner provides. This external identifier is part of the cross-account policy definition in the customer’s account. The partner must provide the identifier when it assumes the role. An external identifier provides an additional layer of security when granting Amazon account access to a partner. The unique identifier ensures that the partner uses the correct customer account.

Enabling a partner product to send findings to the customer in Security Hub with a cross-account role happens in four steps:

Next, the product sends findings to Security Hub:

Here is an example of an IAM policy that grants the necessary Security Hub permissions to the partner's cross-account role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "securityhub:BatchImportFindings",
            "Resource": "arn:aws:securityhub:us-west-1:111122223333:product-subscription/company-name/product-name"
        }
    ]
}

The Resource section of the policy identifies the specific product subscription. This ensures that the partner can only send findings for the partner product that the customer is subscribed to.

Customer hosted: findings sent from customer account

This use case covers partners that have a product that is deployed in the customer’s Amazon account. The BatchImportFindings API is called from the solution that runs in the customer’s account.

For this use case, the partner product must be granted additional permissions to call the BatchImportFindings API. How this permission is granted differs based on the partner solution and how it is configured in the customer’s account.

An example of this approach is a partner product that runs on an EC2 instance in the customer’s account. This EC2 instance must have an EC2 instance role attached to it that grants that instance the ability to call the BatchImportFindings API operation. This allows the EC2 instance to send security findings to the customer’s account.

This use case is functionally equivalent to a scenario where a customer loads findings into their account for a product that they own.

The customer enables the partner product to send findings from the customer's account to the customer in Security Hub:

Now the product can send findings to Security Hub:

Here is an example of an IAM policy that grants the necessary Security Hub permissions to the partner product in the customer account.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "securityhub:BatchImportFindings",
            "Resource": "arn:aws:securityhub:us-west-2:111122223333:product-subscription/company-name/product-name"
        }
    ]
}