How do I create an EventBridge rule that uses the input transformer to make an Amazon SNS notification human readable?

Short description

To make Amazon SNS event notifications human readable, use the input transformer in EventBridge. The input transformer can customize text from an event before it's sent to the target of an EventBridge rule. For more information, see Tutorial: Use input transformers to transform events in EventBridge

You can configure an SNS topic as a target to receive custom event text from the input transformer. You can also create an EventBridge rule to match security group-related API calls that AWS CloudTrail captures. The rule is configured with an event pattern that matches the relevant API calls.

The following resolution includes two example events that you can use to create your own EventBridge rule to make an Amazon SNS notification human readable.

Resolution

Example event for Amazon EC2 state change

The following example configures an SNS topic as a target that receives custom event text from the input transformer. The event is an Amazon Elastic Compute Cloud (Amazon EC2) state change that's published to EventBridge event bus in JSON format:

{
  "version": "0",
  "id": "2ad63080-2526-d42c-4983-123456789",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "0123456789",
  "time": "2023-05-17T16:30:32Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:0123456789:instance/i-12345abcdefg"
  ],
  "detail": {
    "instance-id": "i-12345abcdefg",
    "state": "running"
  }
}

The input transformer has the following sections:

• Input path: Where you define variables that use a JSON path to reference values in the original event source.
• Template: A template for the information that you want to pass to your target.

Input path

To create an input path, see Input transform examples. For this example, use the following input path:

{
  "timestamp": "$.time",
  "instance": "$.detail.instance-id",
  "state": "$.detail.state"
}

Templates

For this example, use the following templates.

Example 1:

"Instance <instance> is in <state> state"

Example 2:

"At <timestamp>, Instance <instance> changed its state to <state>. "

The preceding example templates send messages to the target in the following formats.

Example 1:

"Instance i-12345abcdefg is in running state"

Example 2:

"At 2023-05-17T16:30:32Z, Instance i-12345abcdefg changed its state to running. "

Configure EventBridge to use the input transformer

To configure EventBridge to send custom messages to an SNS topic, complete the following steps:

Note: These instructions follow the steps to configure the input transformer in Creating rules that react to events in Amazon EventBridge.

1. Define an EventBridge rule for Amazon EC2 state change events.

2. Build the event pattern. In the Creation Method section, for Method, choose Custom pattern (JSON editor).

3. For Event pattern, enter the following JSON example for Amazon EC2 state change events:

   {
     "source": [
       "aws.ec2"
     ],
     "detail-type": [
       "EC2 Instance State-change Notification"
     ]
   }

4. Choose Next.

5. For Targets types, choose AWS service.

6. For Select a target, choose SNS topic. Then, select your topic from the dropdown list.

7. For Additional settings, in the Configure target input dropdown list, choose Input transformer. Then, choose Configure input transformer.

8. Under the Target input transformer section, for Input path, copy and paste the following JSON:

   {
     "timestamp": "$.time",
     "instance": "$.detail.instance-id",
     "state": "$.detail.state"
   }

9. For Input template, copy and paste the following string templates:

   "Instance <instance> is in <state> state"  "At <timestamp>, Instance <instance> changed its state to <state>. "

10. Choose Confirm, and then choose Next.

11. (Optional) Add tags to your rule, and then choose Next.

12. Review the rule's details, and then choose Create rule.

Example event for Amazon EC2 security group API call

In the following example event, use CreateSecurityGroup in a virtual private cloud (VPC) to create a security group. CloudTrail captures the event, and the event publishes to CloudWatch in the following JSON format:

{
  "version": "0",
  "id": "41dff147-cfbc-492a-9a98-9dd00d082417",
  "detail-type": "AWS API Call via CloudTrail",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2017-07-14T16:36:23Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "eventVersion": "1.05",
    "userIdentity": {
      "type": "Root",
      "principalId": "123456789012",
      "arn": "arn:aws:iam::123456789012:root",
      "accountId": "123456789012",
      "accessKeyId": "ASIAIRP4G1234567891Q",
      "userName": "iamuser",
      "sessionContext": {
        "attributes": {
          "mfaAuthenticated": "false",
          "creationDate": "2017-07-14T16:27:38Z"
        }
      }
    },
    "eventTime": "2017-07-14T16:36:23Z",
    "eventSource": "ec2.amazonaws.com",
    "eventName": "CreateSecurityGroup",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "72.21.196.64",
    "userAgent": "console.ec2.amazonaws.com",
    "requestParameters": {
      "groupName": "test",
      "groupDescription": "test",
      "vpcId": "vpc-54a4232d"
    },
    "responseElements": {
      "_return": true,
      "groupId": "sg-82d531f3"
    },
    "requestID": "a4609e55-69ac-4a2d-8057-843dc8b4658b",
    "eventID": "7774b898-59c1-48a5-9c41-af1bcaa04612",
    "eventType": "AwsApiCall"
  }
}

Example of how to create a custom human-readable notification

Use the following example to create custom human-readable notifications from EventBridge in JSON format.

1. Create an EventBridge rule for security group-related API calls. For Event Pattern, choose Build custom event pattern. Modify the sample event pattern for your use case. Note that the example notification is for CreateSecurityGroup. However, the following sample event pattern includes all security group-related API call actions:

   {
     "source": [
       "aws.ec2"
     ],
     "detail-type": [
       "AWS API Call via CloudTrail"
     ],
     "detail": {
       "eventSource": [
         "ec2.amazonaws.com"
       ],
       "eventName": [
         "CreateSecurityGroup",
         "AuthorizeSecurityGroupEgress",
         "AuthorizeSecurityGroupIngress",
         "DeleteSecurityGroup",
         "RevokeSecurityGroupEgress",
         "RevokeSecurityGroupIngress",
         "DescribeStaleSecurityGroups",
         "DescribeSecurityGroups",
         "DescribeSecurityGroupReferences"
       ]
     }
   }

2. For Targets types, choose AWS service.

3. For Select a target, choose SNS topic. Then, select your topic from the dropdown list.

4. For Additional settings, in the Configure target input dropdown list, choose Input transformer. Then, choose Configure input transformer.

5. Under the Target input transformer section, for Input path, paste the following JSON. Include any key-value pairs that you want to use in your notification. Modify the following example input path for your use case:

   {
     "sgname": "$.detail.requestParameters.groupName",
     "sourceip": "$.detail.sourceIPAddress",
     "vpcid": "$.detail.requestParameters.vpcId",
     "action": "$.detail.eventName",
     "sgid": "$.detail.responseElements.groupId",
     "time": "$.detail.eventTime",
     "region": "$.detail.awsRegion",
     "user": "$.detail.userIdentity.userName",
     "reqid": "$.detail.requestID"
   }

6. For Input template, paste the following string templates. Include a string with placeholders for values from your input path. This string is the human-readable text of your notification. Modify the following sample input template for your use case:

   "User <user>  has executed API call <action> from source IP <sourceip> on security group <sgid>/<sgname> that belongs to vpc <vpcid> in region <region> at time(UTC) <time>. The Request ID is <reqid>."

7. Choose Confirm, and then choose Next.

8. (Optional) Add tags to your rule, and then choose Next.

9. Review the rule's details, and then choose Create rule.

Troubleshooting

If you receive an Invalid InputTemplate error when you save a template with line breaks, then close each line with double quotation marks. See the following examples:

"<type> <arn> has executed action API <action> on Security Group <sgid> located in AWS region <region> at <time> (UTC)."
"Request ID: <requestid>"
"Event ID: <eventid>"
"Event Source: <eventsource>"
"Event Type: <eventtype>"

If your rule runs but fails to invoke the target, then configure a dead-letter queue for EventBridge to receive errors that are related to the input transformer.

EventBridge supports a maximum of 100 variables in input path maps. To extract more than 10 variables, pass the entire event to an AWS Lambda function. Write this function to parse your variables, and construct a message body in the required format for publication. Then, construct a message body in the required format to publish to Amazon SNS. For more information, see How can I publish a message to an Amazon SNS topic using a Lambda function?