Filtering data events by using advanced event selectors

This section describes how you can use advanced event selectors to create fine-grained selectors, which help you control costs by only logging the specific data events of interest.

For example:

The following table provides additional information about the configurable fields for advanced event selectors.

To log data events using the CloudTrail console, you choose the Data events option and then select the Resource type of interest when you are creating or updating a trail or event data store. The Data events table shows the possible resource types you can choose on the CloudTrail console.

To log data events with the AWS CLI, configure the --advanced-event-selector parameter to set the eventCategory equal to Data and the resources.type value equal to the resource type value for which you want to log data events. The Data events table lists the available resource types.

For example, if you wanted to log data events for all Cognito Identity pools, you’d configure the --advanced-event-selectors parameter to look like this:

--advanced-event-selectors '[
    {
       "Name": "Log Cognito data events on Identity pools",
       "FieldSelectors": [
         { "Field": "eventCategory", "Equals": ["Data"] },
         { "Field": "resources.type", "Equals": ["AWS::Cognito::IdentityPool"] }
       ]
     }
]'

The preceding example logs all Cognito data events on Identity pools. You can further refine the advanced event selectors to filter on the eventName, readOnly, and resources.ARN fields to log specific events of interest or exclude events that aren’t of interest.

You can configure advanced event selectors to filter data events based on multiple fields. For example, you can configure advanced event selectors to log all Amazon S3 PutObject and DeleteObject API calls but exclude event logging for a specific S3 bucket as shown in the following example. Replace amzn-s3-demo-bucket with the name of your bucket.

--advanced-event-selectors
'[
  {
    "Name": "Log PutObject and DeleteObject events for all but one bucket",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventName", "Equals": ["PutObject","DeleteObject"] },
      { "Field": "resources.ARN", "NotStartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] }
    ]
  }
]'

You can also include multiple conditions for a field. For information on how multiple conditions are evaluated, see How CloudTrail evaluates multiple conditions for a field.

You can use advanced event selectors to log both management and data events. To log data events for multiple resource types, add a field selector statement for each resource type that you want to log data events for.

How CloudTrail evaluates multiple conditions for a field

For advanced event selectors, CloudTrail evaluates multiple conditions for a field as follows:

Example showing multiple conditions for the resources.ARN field

The following example event selector statement collects data events for the AWS::S3::Object resource type and applies multiple conditions on the resources.ARN field.

{
    "Name": "S3Select",
    "FieldSelectors": [
      {
        "Field": "eventCategory",
        "Equals": [
          "Data"
        ]
      },
      {
        "Field": "resources.type",
        "Equals": [
          "AWS::S3::Object"
        ]
      },
      {
        "Field": "resources.ARN",
        "Equals": [
          "arn:aws:s3:::amzn-s3-demo-bucket/object1"
        ],
        "StartsWith": [
          "arn:aws:s3:::amzn-s3-demo-bucket/"
        ],
        "EndsWith": [
          "object3"
        ],
        "NotStartsWith": [
          "arn:aws:s3:::amzn-s3-demo-bucket/deselect"
        ],
        "NotEndsWith": [
          "object5"
        ],
        "NotEquals": [
          "arn:aws:s3:::amzn-s3-demo-bucket/object6"
        ]
      }
    ]
  }

In the preceding example, Amazon S3 data events for the AWS::S3::Object resource will be delivered if:

Based on the evaluation logic:

Filtering data events by eventName

Using advanced event selectors, you can include or exclude events based on the value of the eventName field. Filtering on the eventName can help control costs, because you avoid incurring costs when the AWS service you're logging data events for adds support for new data APIs.

You can use any operator with the eventName field. You can use it to filter in or filter out any data event logged to CloudTrail, such as PutBucket or GetSnapshotBlock.

Filtering data events by eventName using the AWS Management Console

Take the following steps to filter on the eventName field using the CloudTrail console.

Filtering data events by eventName using the AWS CLI

Using the AWS CLI, you can filter on the eventName field to include or exclude specific events.

If you’re updating an existing trail or event data store to log additional event selectors, get the current event selectors by running the get-event-selectors command for a trail, or the get-event-data-store command for an event data store. Then, update your event selectors to add a field selector for each data resource type that you want to log.

The following example logs S3 data events on a trail. The --advanced-event-selectors are configured to only log data events for the GetObject, PutObject, and DeleteObject API calls.

aws cloudtrail put-event-selectors \
--trail-name trailName \
--advanced-event-selectors '[
  {
    "Name": "Log GetObject, PutObject and DeleteObject S3 data events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Data"] },
      { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
      { "Field": "eventName", "Equals": ["GetObject","PutObject","DeleteObject"] }
    ]
  }
]'   

The next example creates a new event data store that logs data events for EBS Direct APIs but excludes ListChangedBlocks API calls. You can use the update-event-data-store command to update an existing event data store.

aws cloudtrail create-event-data-store \
--name "eventDataStoreName"
--advanced-event-selectors '[
    {
        "Name": "Log all EBS Direct API data events except ListChangedBlocks",
        "FieldSelectors": [
            { "Field": "eventCategory", "Equals": ["Data"] },
            { "Field": "resources.type", "Equals": ["AWS::EC2::Snapshot"] },
            { "Field": "eventName", "NotEquals": ["ListChangedBlocks"] }
         ]
    }
]'        

Filtering data events by resources.ARN

Using advanced event selectors, you can filter on the value of the resources.ARN field.

You can use any operator with resources.ARN , but if you use Equals or NotEquals, the value must exactly match the ARN of a valid resource for the resources.type value you've specified. To log all data events for all objects in a specific S3 bucket, use the StartsWith operator, and include only the bucket ARN as the matching value.

For more information about the ARN formats of data event resources, see Actions, resources, and condition keys for AWS services in the Service Authorization Reference.

Filtering data events by resources.ARN using the AWS Management Console

Take the following steps to filter on the resources.ARN field using the CloudTrail console.

Filtering data events by resources.ARN using the AWS CLI

Using the AWS CLI, you can filter on the resources.ARN field to log events for a specific ARN or exclude logging for a specific ARN.

If you’re updating an existing trail or event data store to log additional event selectors, get the current event selectors by running the get-event-selectors command for a trail, or the get-event-data-store command for an event data store. Then, update your event selectors to add a field selector for each data resource type that you want to log.

The following example shows how to configure your trail to include all data events for all Amazon S3 objects in a specific S3 bucket. The value for S3 events for the resources.type field is AWS::S3::Object. Because the ARN values for S3 objects and S3 buckets are slightly different, you must add the StartsWith operator for resources.ARN to capture all events.

aws cloudtrail put-event-selectors \ 
--trail-name TrailName \ 
--region region \
--advanced-event-selectors \
'[
    {
        "Name": "S3EventSelector",
        "FieldSelectors": [
            { "Field": "eventCategory", "Equals": ["Data"] },
                { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
                { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] }
            ]
    }
]'

Filtering data events by readOnly value

Using advanced event selectors, you can filter based on the value of the readOnly field.

You can only use the Equals operator with the readOnly field. You can set the readOnly value to true or false. If you do not add this field, CloudTrail logs both read and write events. A value of true logs only read events. A value of false logs only write events.

Filtering data events by readOnly value using the AWS Management Console

Take the following steps to filter on the readOnly field using the CloudTrail console.

Filtering data events by readOnly value using the AWS CLI

Using the AWS CLI, you can filter on the readOnly field.

You can only use the Equals operator with the readOnly field. You can set the readOnly value to true or false. If you do not add this field, CloudTrail logs both read and write events. A value of true logs only read events. A value of false logs only write events.

If you’re updating an existing trail or event data store to log additional event selectors, get the current event selectors by running the get-event-selectors command for a trail, or the get-event-data-store command for an event data store. Then, update your event selectors to add a field selector for each data resource type that you want to log.

The following example shows how to configure your trail to log read-only data events for all Amazon S3 objects.

aws cloudtrail put-event-selectors \
--trail-name TrailName \
--region region \
--advanced-event-selectors '[
    {
            "Name": "Log read-only S3 data events",
            "FieldSelectors": [
                { "Field": "eventCategory", "Equals": ["Data"] },
                { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
                { "Field": "readOnly", "Equals": ["true"] }
            ]
    }
]'       

The next example creates a new event data store that logs only write-only data events for EBS Direct APIs. You can use the update-event-data-store command to update an existing event data store.

aws cloudtrail create-event-data-store \
--name "eventDataStoreName" \
--advanced-event-selectors \
'[
    {
            "Name": "Log write-only EBS Direct API data events",
            "FieldSelectors": [
                { "Field": "eventCategory", "Equals": ["Data"] },
                { "Field": "resources.type", "Equals": ["AWS::EC2::Snapshot"] },
                { "Field": "readOnly", "Equals": ["false"] }
            ]
     }
]'