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

7 minute read
0

I want to create an Amazon EventBridge rule to initiate a custom Amazon Simple Notification Service (Amazon SNS) notification that's 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 a complete tutorial, see Tutorial: Use input transformer to customize what EventBridge passes to the event target.

For example, 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

Sample 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. In this example, the event is an Amazon Elastic Compute Cloud (Amazon EC2) state change.

The following is a sample event 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 two 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 example-instance is in example-state state"

Example 2:

"At example-timestamp, Instance example-instance changed its state to example-state. "

The preceding example templates send messages to the target in the following format:

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 in Create a rule that reacts to events. They also provide specific steps to configure the input transformer.

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 example JSON 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 example-instance is in example-state state"  
"At example-timestamp, Instance example-instance changed its state to example-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.

Sample event for Amazon EC2 security group API call

In the following sample event, use CreateSecurityGroup in a virtual private cloud (VPC) to create a security group. AWS CloudTrail captures the event, and the event publishes to Amazon 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 sample 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 example-user  has executed API call example-action from source IP example-sourceip on security group example-sgid/example-sgname that belongs to vpc example-vpcid in region example-region at time(UTC) example-time. The Request ID is example-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:

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

If your rule runs but fails to invoke the target, then a configure 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?

AWS OFFICIAL
AWS OFFICIALUpdated 7 months ago
2 Comments

I think example 1 template should look like this:

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

replied 6 days ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied 6 days ago