How do I set up human-readable EventBridge notifications for API calls using input transformer?

Short description

You can create an EventBridge rule to match security group-related API calls captured by AWS CloudTrail. That rule is configured with an event pattern that matches the relevant API calls.

Use input transformer to customize the text delivered to the target. For example, the target might be an Amazon Simple Notification Service (Amazon SNS) topic or AWS Lambda function. By doing this, the raw JSON event is converted into a human-readable notification. For more information, see Tutorial: Use input transformer to customize what EventBridge passes to the event target.

Resolution

Sample event

In the following sample event, a CloudTrail log event is captured when a user creates a security group using CreateSecurityGroup in a virtual private cloud (VPC). This event is then published to CloudWatch in JSON format as follows:

{
    "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 resolution

Use the following example resolution as a model for creating your own 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. Be sure to modify the sample event pattern for your use case. Note that while the example notification is for CreateSecurityGroup, 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 your rule's Target, choose Input Transformer under Configure input.

3.    In the first input box, configure your Input Path. Include any key-value pairs to be used in your notification. Be sure to 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"}

Note: EventBridge currently supports a maximum of 100 variables in input path maps. To extract more than 10 variables, pass the entire event to a Lambda function. You can write this function to parse all the desired variables and construct a message body in the required format for publication. Then, construct a message body in the required format for publication to Amazon SNS.

4.    In the second input box, configure the Input Template. Include a string with placeholders for values from your input path. This string is the human-readable text of your notification. Be sure to 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>."

Note: If you receive an Invalid InputTemplate error when saving a template with line breaks, be sure to close each line with double quotation marks. For example:

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

5.    Choose Configure details.

6.    Specify a name and description for the rule.

7.    Choose Create rule.

---

Related information

Creating Amazon EventBridge rules that react to events