Using custom actions to send findings and insight results to EventBridge - Amazon Security Hub
Creating a custom action (console)Creating a custom action (Security Hub API, Amazon CLI)Defining a rule in EventBridgeSelecting a custom action for findings and insight results
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).

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 rules in EventBridge that apply to your custom actions.

You can create up to 50 custom actions.

If you enabled cross-Region aggregation, and manage findings from the aggregation Region, then create custom actions in the aggregation Region.

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 Amazon Security Hub console at https://console.amazonaws.cn/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 Amazon 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, Amazon CLI)

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

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

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

  • Amazon 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 patterns, <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.amazonaws.cn/events/.

  2. In the navigation pane, choose Rules.

  3. Choose Create rule.

  4. Enter a name and description for the rule.

  5. For Event bus, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select default. When an Amazon service in your account emits an event, it always goes to your account’s default event bus.

  6. For Rule type, choose Rule with an event pattern.

  7. Choose Next.

  8. For Event source, choose Amazon events.

  9. For Event pattern, choose Event pattern form.

  10. For Event source, choose Amazon services.

  11. For Amazon service, choose Security Hub.

  12. For Event type, do one of the following:

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

  13. Choose Specific custom action ARNs, add a custom action ARN.

    If the rule applies to multiple custom actions, choose Add to add more custom action ARNs.

  14. Choose Next.

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

  16. Choose Next.

  17. (Optional) Enter one or more tags for the rule. For more information, see Amazon EventBridge tags in the Amazon EventBridge User Guide.

  18. Choose Next.

  19. Review the details of the rule and choose Create rule.

    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 Amazon 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 Amazon Security Hub console at https://console.amazonaws.cn/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.

    Security Hub sends a separate Security Hub Findings - Custom Action event for each finding.

To send insight results to EventBridge

  1. Open the Amazon Security Hub console at https://console.amazonaws.cn/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.