# Using EventBridge for automated response and remediation By creating rules in Amazon EventBridge, you can respond automatically to AWS Security Hub CSPM findings. Security Hub CSPM sends findings as *events* to EventBridge in near-real time. You can write simple rules to indicate which events you are interested in and what automated actions to take when an event matches a rule. The actions that can be automatically triggered include the following: + Invoking an AWS Lambda function + Invoking the Amazon EC2 run command + Relaying the event to Amazon Kinesis Data Streams + Activating an AWS Step Functions state machine + Notifying an Amazon SNS topic or an Amazon SQS queue + Sending a finding to a third-party ticketing, chat, SIEM, or incident response and management tool Security Hub CSPM automatically sends all new findings and all updates to existing findings to EventBridge as EventBridge events. You can also create custom actions that allow you to send selected findings and insight results to EventBridge. You then configure EventBridge rules to respond to each type of event. For more information about using EventBridge, see the [https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html). **Note** As a best practice, make sure that the permissions granted to your users to access EventBridge use least-privilege AWS Identity and Access Management (IAM) policies that grant only the required permissions. For more information, see [Identity and access management in Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/auth-and-access-control-eventbridge.html). A set of templates for cross-account automated response and remediation is also available in AWS Solutions. The templates leverage EventBridge event rules and Lambda functions. You deploy the solution using CloudFormation and AWS Systems Manager. The solution can create fully automated response and remediation actions. It can also use Security Hub CSPM custom actions to create user-triggered response and remediation actions. For details on how to configure and use the solution, see the [Automated Security Response on AWS](https://aws.amazon.com/solutions/implementations/aws-security-hub-automated-response-and-remediation/) solution page. **Topics** + [ # Security Hub CSPM event types in EventBridge ](securityhub-cwe-integration-types.md) + [ # EventBridge event formats for Security Hub CSPM ](securityhub-cwe-event-formats.md) + [ # Configuring an EventBridge rule for Security Hub CSPM findings ](securityhub-cwe-all-findings.md) + [ # Using custom actions to send findings and insight results to EventBridge ](securityhub-cwe-custom-actions.md) # Security Hub CSPM event types in EventBridge Security Hub CSPM uses the following Amazon EventBridge event types to integrate with EventBridge. On the EventBridge dashboard for Security Hub CSPM, **All Events** includes all of these event types. ## All findings (Security Hub Findings - Imported) Security Hub CSPM automatically sends all new findings and all updates to existing findings to EventBridge as **Security Hub Findings - Imported** events. Each **Security Hub Findings - Imported** event contains a single finding. Every [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchImportFindings.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchImportFindings.html) and [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchUpdateFindings.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchUpdateFindings.html) request triggers a **Security Hub Findings - Imported** event. For administrator accounts, the event feed in EventBridge includes events for findings from both their account and from their member accounts. In an aggregation Region, the event feed includes events for findings from the aggregation Region and the linked Regions. Cross-Region findings are included in the event feed in near real time. For information on how to configure finding aggregation, see [Understanding cross-Region aggregation in Security Hub CSPM](finding-aggregation.md). You can define rules in EventBridge that automatically route findings to a remediation workflow, third-party tool, or [other supported EventBridge target](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html). The rules can include filters that only apply the rule if the finding has specific attribute values. You use this method to automatically send all findings, or all findings that have specific characteristics, to a response or remediation workflow. See [Configuring an EventBridge rule for Security Hub CSPM findings](securityhub-cwe-all-findings.md). ## Findings for custom actions (Security Hub Findings - Custom Action) Security Hub CSPM also sends findings that are associated with custom actions to EventBridge as **Security Hub Findings - Custom Action** events. This is useful for analysts working with the Security Hub CSPM console who want to send a specific finding, or a small set of findings, to a response or remediation workflow. You can select a custom action for up to 20 findings at a time. Each finding is sent to EventBridge as a separate EventBridge event. When you create a custom action, you assign it a custom action ID. You can use this ID to create an EventBridge rule that takes a specified action after receiving a finding that is associated with that custom action ID. See [Using custom actions to send findings and insight results to EventBridge](securityhub-cwe-custom-actions.md). For example, you can create a custom action in Security Hub CSPM called `send_to_ticketing`. Then in EventBridge, you create a rule that is triggered when EventBridge receives a finding that includes the `send_to_ticketing` custom action ID. The rule includes logic to send the finding to your ticketing system. You can then select findings within Security Hub CSPM and use the custom action in Security Hub CSPM to manually send findings to your ticketing system. For examples of how to send Security Hub CSPM findings to EventBridge for further processing, see [How to Integrate AWS Security Hub CSPM Custom Actions with PagerDuty](https://aws.amazon.com/blogs/apn/how-to-integrate-aws-security-hub-custom-actions-with-pagerduty/) and [How to Enable Custom Actions in AWS Security Hub CSPM](https://aws.amazon.com/blogs/apn/how-to-enable-custom-actions-in-aws-security-hub/) on the AWS Partner Network (APN) Blog. ## Insight results for custom actions (Security Hub Insight Results) You can also use custom actions to send sets of insight results to EventBridge as **Security Hub Insight Results** events. Insight results are the resources that match an insight. Note that when you send insight results to EventBridge, you are not sending the findings to EventBridge. You are only sending the resource identifiers that are associated with the insight results. You can send up to 100 resource identifiers at a time. Similar to custom actions for findings, you first create the custom action in Security Hub CSPM, and then create a rule in EventBridge. See [Using custom actions to send findings and insight results to EventBridge](securityhub-cwe-custom-actions.md). For example, suppose you see a particular insight result of interest that you want to share with a colleague. In that case, you can use a custom action to send that insight result to the colleague through a chat or ticketing system. # EventBridge event formats for Security Hub CSPM The **Security Hub Findings - Imported**, **Security Findings - Custom Action**, and **Security Hub Insight Results** event types use the following event formats. The event format is the format that is used when Security Hub CSPM sends an event to EventBridge. ## Security Hub Findings - Imported **Security Hub Findings - Imported** events that are sent from Security Hub CSPM to EventBridge use the following format. ``` { "version":"0", "id":"CWE-event-id", "detail-type":"Security Hub Findings - Imported", "source":"aws.securityhub", "account":"111122223333", "time":"2019-04-11T21:52:17Z", "region":"us-west-2", "resources":[ "arn:aws:securityhub:us-west-2::product/aws/macie/arn:aws:macie:us-west-2:111122223333:integtest/trigger/6294d71b927c41cbab915159a8f326a3/alert/f2893b211841" ], "detail":{ "findings": [{ }] } } ``` `` is the content, in JSON format, of the finding that is sent by the event. Each event sends a single finding. For a complete list of finding attributes, see [AWS Security Finding Format (ASFF)](securityhub-findings-format.md). For information about how to configure EventBridge rules that are triggered by these events, see [Configuring an EventBridge rule for Security Hub CSPM findings](securityhub-cwe-all-findings.md). ## Security Hub Findings - Custom Action **Security Hub Findings - Custom Action** events that are sent from Security Hub CSPM to EventBridge use the following format. Each finding is sent in a separate event. ``` { "version": "0", "id": "1a1111a1-b22b-3c33-444d-5555e5ee5555", "detail-type": "Security Hub Findings - Custom Action", "source": "aws.securityhub", "account": "111122223333", "time": "2019-04-11T18:43:48Z", "region": "us-west-1", "resources": [ "arn:aws:securityhub:us-west-1:111122223333:action/custom/custom-action-name" ], "detail": { "actionName":"custom-action-name", "actionDescription": "description of the action", "findings": [ { } ] } } ``` `` is the content, in JSON format, of the finding that is sent by the event. Each event sends a single finding. For a complete list of finding attributes, see [AWS Security Finding Format (ASFF)](securityhub-findings-format.md). For information about how to configure EventBridge rules that are triggered by these events, see [Using custom actions to send findings and insight results to EventBridge](securityhub-cwe-custom-actions.md). ## Security Hub Insight Results **Security Hub Insight Results** events that are sent from Security Hub CSPM to EventBridge use the following format. ``` { "version": "0", "id": "1a1111a1-b22b-3c33-444d-5555e5ee5555", "detail-type": "Security Hub Insight Results", "source": "aws.securityhub", "account": "111122223333", "time": "2017-12-22T18:43:48Z", "region": "us-west-1", "resources": [ "arn:aws:securityhub:us-west-1:111122223333::product/aws/macie:us-west-1:222233334444:test/trigger/1ec9cf700ef6be062b19584e0b7d84ec/alert/f2893b211841" ], "detail": { "actionName":"name of the action", "actionDescription":"description of the action", "insightArn":"ARN of the insight", "insightName":"Name of the insight", "resultType":"ResourceAwsIamAccessKeyUserName", "number of results":"number of results, max of 100", "insightResults": [ {"result 1": 5}, {"result 2": 6} ] } } ``` For information about how to create an EventBridge rule that is triggered by these events, see [Using custom actions to send findings and insight results to EventBridge](securityhub-cwe-custom-actions.md). # Configuring an EventBridge rule for Security Hub CSPM findings You can create a rule in Amazon EventBridge that defines an action to take when a **Security Hub Findings - Imported** event is received. **Security Hub Findings - Imported** events are triggered by updates from both the [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchImportFindings.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchImportFindings.html) and [https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchUpdateFindings.html](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_BatchUpdateFindings.html) operations. Each rule contains an event pattern, which identifies the events that trigger the rule. The event pattern always contains the event source (`aws.securityhub`) and the event type (**Security Hub Findings - Imported**). The event pattern can also specify filters to identify the findings that the rule applies to. The event rule then identifies the rule targets. The targets are the actions to take when EventBridge receives a **Security Hub Findings - Imported** event and the finding matches the filters. The instructions provided here use the EventBridge console. When you use the console, EventBridge automatically creates the required resource-based policy that enables EventBridge to write to Amazon CloudWatch Logs. You can also use the [https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html) operation of the EventBridge API. However, if you use the EventBridge API, then you must create the resource-based policy. For information about the required policy, see [CloudWatch Logs permissions](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#cloudwatchlogs-permissions) in the *Amazon EventBridge User Guide*. ## Format of the event pattern The format of the event pattern for **Security Hub Findings - Imported** events is as follows: ``` { "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Imported" ], "detail": { "findings": { } } } ``` + `source` identifies Security Hub CSPM as the service that generates the event. + `detail-type` identifies the type of event. + `detail` is optional and provides the filter values for the event pattern. If the event pattern does not contain a `detail` field, then all findings trigger the rule. You can filter the findings based on any finding attribute. For each attribute, you provide a comma-separated array of one or more values. ``` "": [ "", ""] ``` If you provide more than one value for an attribute, then those values are joined by `OR`. A finding matches the filter for an individual attribute if the finding has any of the listed values. For example, if you provide both `INFORMATIONAL` and `LOW` as values for `Severity.Label`, then the finding matches if it has a severity label of either `INFORMATIONAL` or `LOW`. The attributes are joined by `AND`. A finding matches if it matches the filter criteria for all of the provided attributes. When you provide an attribute value, it must reflect the location of that attribute within the AWS Security Finding Format (ASFF) structure. **Tip** When filtering control findings, we recommend using the `SecurityControlId` or `SecurityControlArn` [ASFF fields](securityhub-findings-format.md) as filters, rather than `Title` or `Description`. The latter fields can change occasionally, whereas the control ID and ARN are static identifiers. In the following example, the event pattern provides filter values for `ProductArn` and `Severity.Label`, so a finding matches if it is generated by Amazon Inspector and it has a severity label of either `INFORMATIONAL` or `LOW`. ``` { "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Findings - Imported" ], "detail": { "findings": { "ProductArn": ["arn:aws:securityhub:us-east-1::product/aws/inspector"], "Severity": { "Label": ["INFORMATIONAL", "LOW"] } } } } ``` ## Creating an event rule You can use a predefined event pattern or a custom event pattern to create a rule in EventBridge. If you select a predefined pattern, EventBridge automatically fills in `source` and `detail-type`. EventBridge also provides fields to specify filter values for the following finding attributes: + `AwsAccountId` + `Compliance.Status` + `Criticality` + `ProductArn` + `RecordState` + `ResourceId` + `ResourceType` + `Severity.Label` + `Types` + `Workflow.Status` **To create an EventBridge rule (console)** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. Using the following values, create an EventBridge rule that monitors finding events: + For **Rule type**, choose **Rule with an event pattern**. + Choose how to build the event pattern. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-cwe-all-findings.html) + For **Target types**, choose **AWS service**, and for **Select a target**, choose a target such as an Amazon SNS topic or AWS Lambda function. The target is triggered when an event is received that matches the event pattern defined in the rule. For details about creating rules, see [Creating Amazon EventBridge rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) in the *Amazon EventBridge User Guide*. # Using custom actions to send findings and insight results to EventBridge To use AWS Security Hub CSPM custom actions to send findings or insight results to Amazon EventBridge, you first create the custom action in Security Hub CSPM. Then, you can define rules in EventBridge that apply to your custom actions. You can create up to 50 custom actions. If you enable cross-Region aggregation, and manage findings from the aggregation Region, then create custom actions in the aggregation Region. The rule in EventBridge uses the Amazon Resource Name (ARN) from the custom action. # Creating a custom action When you create a custom action in AWS Security Hub CSPM, you specify its name, description, and a unique identifier. A custom action specifies which actions to take when an EventBridge event matches an EventBridge rule. Security Hub CSPM sends each finding to EventBridge as an event. Choose your preferred method, and follow the steps to create a custom action. ------ #### [ Console ] **To create a custom action in Security Hub CSPM (console)** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. In the navigation pane, choose **Settings** and then choose **Custom actions**. 1. Choose **Create custom action**. 1. 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. 1. Choose **Create custom action**. 1. 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. ------ #### [ API ] **To create a custom action (API)** Use the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateActionTarget.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_CreateActionTarget.html) operation. If you're using the AWS CLI, run the [create-action-target](https://docs.aws.amazon.com/cli/latest/reference/securityhub/create-action-target.html) command. The following example creates a custom action to send findings to a remediation tool. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ 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 trigger a custom action in Amazon EventBridge, you must create a corresponding rule in EventBridge. The rule definition includes the Amazon Resource Name (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": [ "" ] } ``` The event pattern for a **Security Hub Insight Results** event has the following format: ``` { "source": [ "aws.securityhub" ], "detail-type": [ "Security Hub Insight Results" ], "resources": [ "" ] } ``` In both patterns, `` 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 [https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html) 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#cloudwatchlogs-permissions) in the *Amazon EventBridge User Guide*. **To define a rule in EventBridge (EventBridge console)** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Rules**. 1. Choose **Create rule**. 1. Enter a name and description for the rule. 1. 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 AWS service in your account emits an event, it always goes to your account’s default event bus. 1. For **Rule type**, choose **Rule with an event pattern**. 1. Choose **Next**. 1. For **Event source**, choose **AWS events**. 1. For **Event pattern**, choose **Event pattern form**. 1. For **Event source**, choose **AWS services**. 1. For **AWS service**, choose **Security Hub**. 1. 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**. 1. 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. 1. Choose **Next**. 1. Under **Select targets**, choose and configure the target to invoke when this rule is matched. 1. Choose **Next**. 1. (Optional) Enter one or more tags for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*. 1. Choose **Next**. 1. 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 AWS Security Hub CSPM custom actions and Amazon EventBridge rules, you can send findings and insight results to EventBridge for automatic 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 (console)** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. Display a list of findings: + From **Findings**, you can view findings from all of the enabled product integrations and controls. + From **Security standards**, you can navigate to a list of findings generated from a specific control. For more information, see [Reviewing the details of controls in Security Hub CSPM](securityhub-standards-control-details.md). + From **Integrations**, you can navigate to a list of findings generated by an enabled integration. For more information, see [Viewing findings from a Security Hub CSPM integration](securityhub-integration-view-findings.md). + From **Insights**, you can navigate to a list of findings for an insight result. For more information, see [Reviewing and acting on insights in Security Hub CSPM](securityhub-insights-view-take-action.md). 1. Select the findings to send to EventBridge. You can select up to 20 findings at a time. 1. From **Actions**, choose the custom action that aligns with the EventBridge rule to apply. Security Hub CSPM sends a separate **Security Hub Findings - Custom Action** event for each finding. **To send insight results to EventBridge (console)** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. In the navigation pane, choose **Insights**. 1. On the **Insights** page, choose the insight that includes the results to send to EventBridge. 1. Select the insight results to send to EventBridge. You can select up to 20 results at a time. 1. From **Actions**, choose the custom action that aligns with the EventBridge rule to apply.