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 per 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 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. Choose Custom pattern.

  7. Copy one of the following example patterns, and paste it into the Event pattern text area. Be sure to replace the existing brackets.

    For an event associated with a finding custom action (Security Hub Findings - Custom Action event type), use the following format. In your event pattern, replace the placeholder ARN with the Custom Action ARN for the custom action you created.

    { "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Custom Action" ], "resources": [ "arn:aws:securityhub:us-west-2:123456789012:action/custom/test-action1" ] }

    For an event associated with an insight custom action (Security Hub Insight Results event type), use the following format. In your event pattern, replace the placeholder ARN with the Custom Action ARN for the custom action you created.

    { "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Insight Results" ], "resources": [ "arn:aws:securityhub:us-west-2:123456789012:action/custom/test-action1" ] }
  8. Choose Save to save the pattern.

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

  10. 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 must 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.