Using custom actions to send findings and insight results to EventBridge - AWS Security Hub

Using custom actions to send findings and insight results to EventBridge

To use Security Hub custom actions to send findings or insight results to EventBridge, you first create the custom action in Security Hub. Then define the rule in EventBridge.

You can create up to 50 custom actions.

The rule in EventBridge uses the ARN from the custom action.

Creating a custom action (console)

When you create a custom action, you specify the name, description, and a unique identifier.

To create a custom action in Security Hub (console)

  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. In the navigation pane, choose Settings and then choose Custom actions.

  3. Choose Create custom action.

  4. Provide a Name, Description, and Custom action ID for the action.

    The Name must be fewer than 20 characters.

    The Custom action ID must be unique for each AWS account.

  5. Choose Create custom action.

  6. Make a note of the Custom action ARN. You need to use the ARN when you create a rule to associate with this action in EventBridge.

Creating a custom action (Security Hub API, AWS CLI)

To create a custom action, you can use an API call or the AWS Command Line Interface.

To create a custom action (Security Hub API, AWS CLI)

  • Security Hub API – Use the CreateActionTarget operation. When you create a custom action, you provide the name, description, and custom action identifier.

  • AWS CLI – At the command line, run the create-action-target command.

    create-action-target --name <customActionName> --description <customActionDescription> --id <customActionidentifier>

    Example

    aws securityhub create-action-target --name "Send to remediation" --description "Action to send the finding for remediation tracking" --id "Remediation"

Defining a rule in EventBridge

To process the custom action, you must create a corresponding rule in EventBridge. The rule definition includes the ARN of the custom action.

The event pattern for a Security Hub Findings - Custom Action event has the following format:

{ "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Custom Action" ], "resources": [ "<custom action ARN>" ] }

The event pattern for a Security Hub Insight Results event has the following format:

{ "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Insight Results" ], "resources": [ "<custom action ARN>" ] }

In both formats, <custom action ARN> is the ARN of a custom action. You can configure a rule that applies to more than one custom action.

The instructions provided here are for the EventBridge console. When you use the console, EventBridge automatically creates the required resource-based policy that enables EventBridge to write to CloudWatch Logs.

You can also use the PutRule API operation of the EventBridge API. However, if you use the EventBridge API, then you must create the resource-based policy. For details on the required policy, see CloudWatch Logs permissions in the Amazon EventBridge User Guide.

To define a rule in EventBridge

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Rules.

  3. Choose Create rule.

  4. Enter a name and description for the rule.

  5. For Event source, choose Event Pattern.

  6. For Event matching pattern, choose Pre-defined pattern by service.

  7. For Service provider, choose AWS.

  8. For Service name, choose Security Hub.

  9. For Event type, to create a rule to apply when you send findings to a custom action, choose Security Hub Findings - Custom Action.

    To create a rule to apply when you send insight results to a custom action, choose Security Hub Insight Results.

  10. For each custom action that this rule applies to, perform the following steps:

    1. Choose Specific custom action.

    2. To add a custom action ARN, enter the ARN in the field, and then choose Add.

    3. To remove a custom action ARN, choose Remove for that value.

  11. Under Select targets, choose and configure the target to invoke when this rule is matched.

  12. Choose Create.

After this rule is created in EventBridge, when you perform a custom action on findings or insight results in your account, events are generated in EventBridge.

Selecting a custom action for findings and insight results

After you create your Security Hub custom actions and EventBridge rules, you can send findings and insight results to EventBridge for further management and processing.

Events are sent to EventBridge only in the account in which they are viewed. If you view a finding using an administrator account, the event is sent to EventBridge in the administrator account.

For AWS API calls to be effective, the implementations of target code must switch roles into member accounts. This also means that the role you switch into must be deployed to each member where action is needed.

To send findings to EventBridge

  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. Display a list of findings:

  3. Select the findings to send to EventBridge. You can select up to 20 findings at a time.

  4. From Actions, choose the custom action that aligns with the EventBridge rule to apply.

To send insight results to EventBridge

  1. Open the AWS Security Hub console at https://console.aws.amazon.com/securityhub/.

  2. In the navigation pane, choose Insights.

  3. On the Insights page, choose the insight that includes the results to send to EventBridge.

  4. Select the insight results to send to EventBridge. You can select up to 20 results at a time.

  5. From Actions, choose the custom action that aligns with the EventBridge rule to apply.