Content filtering in Amazon EventBridge event patterns

Amazon EventBridge supports declarative content filtering using event patterns. With content filtering, you can write complex event patterns that only match events under very specific conditions. For example, you can create an event pattern that matches an event when:

• A field of the event is within a specific numeric range.

• The event comes from a specific IP address.

• A specific field doesn't exist in the event JSON.

Important

In EventBridge, it is possible to create rules that can lead to higher-than-expected charges and throttling. For example, you can inadvertently create a rule that leads to an infinite loop, where a rule is fired recursively without end. Suppose you created a rule to detect that ACLs have changed on an Amazon S3 bucket, and trigger software to change them to the desired state. If the rule is not written carefully, the subsequent change to the ACLs fires the rule again, creating an infinite loop.

For guidance on how to write precise rules and event patterns to minimize such unexpected results, see Best practices when defining Amazon EventBridge rules and Best practices when defining Amazon EventBridge event patterns.

Prefix matching

You can match an event depending on the prefix of a value in the event source. You can use prefix matching for string values.

For example, the following event pattern would match any event where the "time" field started with "2017-10-02" such as "time": "2017-10-02T18:43:48Z".

{
  "time": [ { "prefix": "2017-10-02" } ]
}

Suffix matching

You can match an event depending on the suffix of a value in the event source. You can use suffix matching for string values.

For example, the following event pattern would match any event where the "FileName" field ends with the .png file extension.

{
  "FileName": [ { "suffix": ".png" } ]
}

Anything-but matching

Anything-but matching matches anything except what's provided in the rule.

You can use anything-but matching with strings and numeric values, including lists that contain only strings, or only numbers.

The following event pattern shows anything-but matching with strings and numbers.

{
  "detail": {
    "state": [ { "anything-but": "initializing" } ]
  }
}

{
  "detail": {
    "x-limit": [ { "anything-but": 123 } ]
  }
}

The following event pattern shows anything-but matching with a list of strings.

{
  "detail": {
    "state": [ { "anything-but": [ "stopped", "overloaded" ] } ]
  }
}

The following event pattern shows anything-but matching with a list of numbers.

{
  "detail": {
    "x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
  }
}

The following event pattern shows anything-but matching that matches any event that doesn't have the prefix "init" in the "state" field.

Note

Anything-but matching only works with a single prefix, not a list.

{
  "detail": {
    "state": [ { "anything-but": { "prefix": "init" } } ]
  }
}

Numeric matching

Numeric matching works with values that are JSON numbers. It is limited to values between -5.0e9 and +5.0e9 inclusive, with 15 digits of precision, or six digits to the right of the decimal point.

The following shows numeric matching for an event pattern that only matches events that are true for all fields.

{
  "detail": {
    "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
    "d-count": [ { "numeric": [ "<", 10 ] } ],
    "x-limit": [ { "numeric": [ "=", 3.018e2 ] } ]
  }
}

IP address matching

You can use IP address matching for IPv4 and IPv6 addresses. The following event pattern shows IP address matching to IP addresses that start with 10.0.0 and end with a number between 0 and 255.

{
  "detail": {
    "sourceIPAddress": [ { "cidr": "10.0.0.0/24" } ]
  }
}

Exists matching

Exists matching works on the presence or absence of a field in the JSON of the event.

Exists matching only works on leaf nodes. It does not work on intermediate nodes.

The following event pattern matches any event that has a detail.state field.

{
  "detail": {
    "state": [ { "exists": true  } ]
  }
}

The preceding event pattern matches the following event.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2015-11-11T21:29:54Z",
  "region": "us-east-1",
  "resources": ["arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"],
  "detail": {
    "instance-id": "i-abcd1111",
    "state": "pending"
  }
}

The preceding event pattern does NOT match the following event because it doesn't have a detail.state field.

{
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
  "detail": {
    "c-count" : {
       "c1" : 100
    }
  }
}

Equals-ignore-case matching

Equals-ignore-case matching works on string values regardless of case.

The following event pattern matches any event that has a detail-type field that matches the specified string, regardless of case.

{
  "detail-type": [ { "equals-ignore-case": "ec2 instance state-change notification" } ]
}

The preceding event pattern matches the following event.

{
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
  "detail": {
    "c-count" : {
       "c1" : 100
    }
  }
}

Matching using wildcards

You can use the wildcard character (*) to match string values in event patterns.

Note

Currently the wildcard character is supported in event bus rules only.

Considerations when using wildcards in your event patterns:

• You can specify any number of wildcard characters in a given string value; however, consecutive wildcard characters are not supported.

• EventBridge supports using the backslash character (\) to specify the literal * and \ characters in wildcard filters:

  • The string \* represents the literal * character

  • The string \\ represents the literal \ character

  Using the backslash to escape other characters is not supported.

Wildcards and event pattern complexity

There is a limit to how complex a rule using wildcards can be. If a rule is too complex, EventBridge returns an InvalidEventPatternException when attempting to create the rule. If your rule generates such an error, consider using the guidance below to reduce the complexity of the event pattern:

• Reduce the number of wildcard characters used

  Only use wildcard characters where you truly need to match against multiple possible values. For example, consider the following event pattern, where you want to match against event buses in the same Region:

  {
  "EventBusArn": [ { "wildcard": "*:*:*:*:*:event-bus/*" } ]
  }

  In the above case, many of the sections of the ARN will be directly based on the Region in which your event buses reside. So if you are using the us-east-1 Region, a less complex pattern that still matches the desired values might be the following example:

  {
  "EventBusArn": [ { "wildcard": "arn:aws:events:us-east-1:*:event-bus/*" } ]
  }

• Reduce repeating character sequences that occur after a wildcard character

  Having the same character sequence appear multiple times after the use of a wildcard increases the complexity of processing the event pattern. Recast your event pattern to minimize repeated sequences. For example, consider the following example, that matches on the file name doc.txt file for any user:

  {
  "FileName": [ { "wildcard": "/Users/*/dir/dir/dir/dir/dir/doc.txt" } ]
  }

  If you knew that the doc.txt file would only occur in the specified path, you could reduce the repeated character sequence in this way:

  {
  "FileName": [ { "wildcard": "/Users/*/doc.txt" } ]
  }

Complex example with multiple matching

You can combine multiple matching rules into a more complex event pattern. For example, the following event pattern combines anything-but and numeric.

{
  "time": [ { "prefix": "2017-10-02" } ],
  "detail": {
    "state": [ { "anything-but": "initializing" } ],
    "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
    "d-count": [ { "numeric": [ "<", 10 ] } ],
    "x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
  }
}

Note

When building event patterns, if you include a key more than once the last reference will be the one used to evaluate events. For example, for the following pattern:

{
  "detail": {
    "location": [ { "prefix": "us-" } ],
    "location": [ { "anything-but": "us-east" } ]
  }
}

only { "anything-but": "us-east" } will be taken into account when evaluating the location.

Complex example with $or matching

You can also create complex event patterns that check to see if any field values match, across multiple fields. Use $or to create an event pattern that matches if any of the values for multiple fields are matched.

Note that you can include other filter types, such as numeric matching and arrays, in your pattern matching for individual fields in your $or construct.

The following event pattern matches if any of the following conditions are met:

• The c-count field is greater than 0 or less than or equal to 5.

• The d-count field is less than 10.

• The x-limit field equals 3.018e2.

{
  "detail": {
    "$or": [
      { "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ] },
      { "d-count": [ { "numeric": [ "<", 10 ] } ] },
      { "x-limit": [ { "numeric": [ "=", 3.018e2 ] } ] }
    ]
  }
}

Note

APIs that accept an event pattern (such as PutRule, CreateArchive, UpdateArchive, and TestEventPattern) will throw an InvalidEventPatternException if the use of $or results in over 1000 rule combinations.

To determine the number of rule combinations in an event pattern, multiply the total number of arguments from each $or array in the event pattern. For example, the above pattern contains a single $or array with three arguments, so the total number of rule combinations is also three. If you added another $or array with two arguments, the total rule combinations would then be six.