Filtering data events by using advanced event selectors - AWS CloudTrail

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:

  • You can include or exclude specific API calls by adding a filter on the eventName field.

  • You can include or exclude logging for specific resources by adding a filter on the resources.ARN field. For example, if you were logging S3 data events, you could exclude logging for the S3 bucket for your trail.

  • You can choose to log only write-only events or read-only events by adding a filter on the readOnly field.

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

Field Required Valid operators Description

eventCategory

Yes

Equals

This field is set to Data to log data events.

Supported on trails: Yes

Supported on event data stores: Yes

resources.type

Yes

Equals

This field is used to select the resource type for which you want to log data events. The Data events table shows the possible values.

Supported on trails: Yes

Supported on event data stores: Yes

readOnly

No

Equals

This is an optional field used to include or exclude data events based on the readOnly value. A value of true logs only read events. A value of false logs only write events. If you do not add this field, CloudTrail logs both read and write events.

Supported on trails: Yes

Supported on event data stores: Yes

eventName

No

EndsWith

Equals

NotEndsWith

NotEquals

NotStartsWith

StartsWith

This is an optional filed used to filter in or filter out any data event logged to CloudTrail, such as PutBucket or GetSnapshotBlock.

If you're using the AWS CLI, you can specify multiple values by separating each value with a comma.

If you're using the console, you can specify multiple values by creating a condition for each eventName you want to filter on.

Supported on trails: Yes

Supported on event data stores: Yes

resources.ARN

No

EndsWith

Equals

NotEndsWith

NotEquals

NotStartsWith

StartsWith

This is an optional field used to exclude or include data events for a specific resource by providing the resources.ARN. 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 resoureces.type 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.

If you're using the AWS CLI, you can specify multiple values by separating each value with a comma.

If you're using the console, you can specify multiple values by creating a condition for each resources.ARN you want to filter on.

Supported on trails: Yes

Supported on event data stores: Yes

eventSource

No

EndsWith

Equals

NotEndsWith

NotEquals

NotStartsWith

StartsWith

You can use it to include or exclude specific event sources. The eventSource is typically a short form of the service name without spaces plus .amazonaws.com. For example, you could set eventSource Equals to ec2.amazonaws.com to log only Amazon EC2 data events.

Supported on trails: No

Supported on event data stores: Yes

eventType

No

EndsWith

Equals

NotEndsWith

NotEquals

NotStartsWith

StartsWith

The eventType to include or exclude. For example, you can set this field to NotEquals AwsServiceEvent to exclude AWS service events.

Supported on trails: No

Supported on event data stores: Yes

sessionCredentialFromConsole

No

Equals

NotEquals

Include or exclude events originating from an AWS Management Console session. This field can be set to Equals or NotEquals with a value of true.

Supported on trails: No

Supported on event data stores: Yes

userIdentity.arn

No

EndsWith

Equals

NotEndsWith

NotEquals

NotStartsWith

StartsWith

Include or exclude events for actions taken by specific IAM identities. For more information, see CloudTrail userIdentity element.

Supported on trails: No

Supported on event data stores: Yes

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.

Selection of the SNS topic resource type on the 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.

Note

Trails can use either basic event selectors or advanced event selectors, but not both. If you apply advanced event selectors to a trail, any existing basic event selectors are overwritten.

How CloudTrail evaluates multiple conditions for a field

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

  • DESELECT operators are AND'd together. If any of the DESELECT operator conditions are met, the event is not delivered. These are the valid DESELECT operators for advanced event selectors:

    • NotEndsWith

    • NotEquals

    • NotStartsWith

  • SELECT operators are OR'd together. These are the valid SELECT operators for advanced event selectors:

    • EndsWith

    • Equals

    • StartsWith

  • Combinations of SELECT and DESELECT operators follow the above rules and both groups are AND'd together.

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:

  1. None of these DESELECT operator conditions are met:

    • the resources.ARN field NotStartsWith the value arn:aws:s3:::amzn-s3-demo-bucket/deselect

    • the resources.ARN field NotEndsWith the value object5

    • the resources.ARN field NotEquals the value arn:aws:s3:::amzn-s3-demo-bucket/object6

  2. At least one of these SELECT operator conditions is met:

    • the resources.ARN field Equals the value arn:aws:s3:::amzn-s3-demo-bucket/object1

    • the resources.ARN field StartsWith the value arn:aws:s3:::amzn-s3-demo-bucket/

    • the resources.ARN field EndsWith the value object3

Based on the evaluation logic:

  1. Data events for amzn-s3-demo-bucket/object1 will be delivered because it matches the value for the Equals operator and doesn’t match any of the values for the NotStartsWith, NotEndsWith, and NotEquals operators.

  2. Data event for amzn-s3-demo-bucket/object2 will be delivered because it matches the value for the StartsWith operator and doesn’t match any of the values for the NotStartsWith, NotEndsWith, and NotEquals operators.

  3. Data events for amzn-s3-demo-bucket1/object3 will be delivered because it matches the EndsWith operator and doesn’t match any of the values for the NotStartsWith, NotEndsWith, and NotEquals operators.

  4. Data events for arn:aws:s3:::amzn-s3-demo-bucket/deselectObject4 will not be delivered because it matches the condition for the NotStartsWith even though it matches the condition for the StartsWith operator.

  5. Data events for arn:aws:s3:::amzn-s3-demo-bucket/object5 will not be delivered because it matches the condition for the NotEndsWith even though it matches the condition for the StartsWith operator.

  6. Data events for the arn:aws:s3:::amzn-s3-demo-bucket/object6 will not be delivered because it matches the condition for the NotEquals operator even though it matches the condition for the StartsWith operator.

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.

  1. Follow the steps in the create trail procedure, or follow the steps in the create event data store procedure.

  2. As you follow the steps to create the trail or event data store, make the following selections:

    1. Choose Data events.

    2. Choose the Resource type for which you want to log data events.

    3. For Log selector template, choose Custom.

    4. (Optional) In Selector name, enter a name to identify your selector. The selector name is a descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets". The selector name is listed as Name in the advanced event selector and is viewable if you expand the JSON view.

    5. In Advanced event selectors, do the following to filter on the eventName:

      1. For Field, choose eventName.

      2. For Operator, choose the condition operator. In this example, we'll choose equals because we want to log a specific API call.

      3. For Value, enter the name of the event you want to filter on.

      4. To filter on another eventName, choose + Condition. For information about how CloudTrail evaluates multiple conditions, see How CloudTrail evaluates multiple conditions for a field.

      Filter S3 data events by eventName
    6. Choose +Field to add filters on other fields.

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.

The following table shows the valid ARN format for each resources.type.

Note

You can't use the resources.ARN field to filter resource types that do not have ARNs.

resources.type resources.ARN
AWS::DynamoDB::Table1
arn:partition:dynamodb:region:account_ID:table/table_name
AWS::Lambda::Function
arn:partition:lambda:region:account_ID:function:function_name

AWS::S3::Object2

arn:partition:s3:::amzn-s3-demo-bucket/ arn:partition:s3:::amzn-s3-demo-bucket/object_or_file_name/
AWS::AppConfig::Configuration
arn:partition:appconfig:region:account_ID:application/application_ID/environment/environment_ID/configuration/configuration_profile_ID
AWS::AppSync::GraphQL
arn:partition:appsync:region:account_ID:apis/GraphQL_API_ID
AWS::B2BI::Transformer
arn:partition:b2bi:region:account_ID:transformer/transformer_ID
AWS::Bedrock::AgentAlias
arn:partition:bedrock:region:account_ID:agent-alias/agent_ID/alias_ID
AWS::Bedrock::FlowAlias
arn:partition:bedrock:region:account_ID:flow/flow_ID/alias/alias_ID
AWS::Bedrock::Guardrail
arn:partition:bedrock:region:account_ID:guardrail/guardrail_ID
AWS::Bedrock::InlineAgent
arn:partition:bedrock:region:account_ID:INLINE_AGENT_UUID
AWS::Bedrock::KnowledgeBase
arn:partition:bedrock:region:account_ID:knowledge-base/knowledge_base_ID
AWS::Bedrock::Model

The ARN must be in one of the following formats:

  • arn:partition:bedrock:region::foundation-model/resource_ID

  • arn:partition:bedrock:region:account_ID:provisioned-model/resource_ID

  • arn:partition:bedrock:region:account_ID:custom-model/resource_ID

AWS::Cassandra::Table
arn:partition:cassandra:region:account_ID:keyspace/keyspace_name/table/table_name
AWS::CloudFront::KeyValueStore
arn:partition:cloudfront:region:account_ID:key-value-store/KVS_name
AWS::CloudTrail::Channel
arn:partition:cloudtrail:region:account_ID:channel/channel_UUID
AWS::CodeGuruProfiler::ProfilingGroup
arn:partition:codeguru-profiler:region:account_ID:profilingGroup/profiling_group_name
AWS::CodeWhisperer::Customization
arn:partition:codewhisperer:region:account_ID:customization/customization_ID
AWS::CodeWhisperer::Profile
arn:partition:codewhisperer:region:account_ID:profile/profile_ID
AWS::Cognito::IdentityPool
arn:partition:cognito-identity:region:account_ID:identitypool/identity_pool_ID
AWS::DataExchange::Asset
arn:partition:dataexchange:region:account_ID:data-sets/data_set_ID/revisions/revision_ID/assets/asset_ID
AWS::Deadline::Fleet
arn:partition:deadline:region:account_ID:farm/farm_ID/fleet/fleet_ID
AWS::Deadline::Job
arn:partition:deadline:region:account_ID:farm/farm_ID/queue/queue_ID/job/job_ID
AWS::Deadline::Queue
arn:partition:deadline:region:account_ID:farm/farm_ID/queue/queue_ID
AWS::Deadline::Worker
arn:partition:deadline:region:account_ID:farm/farm_ID/fleet/fleet_ID/worker/worker_ID
AWS::DynamoDB::Stream
arn:partition:dynamodb:region:account_ID:table/table_name/stream/date_time
AWS::EC2::Snapshot
arn:partition:ec2:region::snapshot/snapshot_ID
AWS::EMRWAL::Workspace
arn:partition:emrwal:region:account_ID:workspace/workspace_name
AWS::FinSpace::Environment
arn:partition:finspace:region:account_ID:environment/environment_ID
AWS::Glue::Table
arn:partition:glue:region:account_ID:table/database_name/table_name
AWS::GreengrassV2::ComponentVersion
arn:partition:greengrass:region:account_ID:components/component_name
AWS::GreengrassV2::Deployment
arn:partition:greengrass:region:account_ID:deployments/deployment_ID
AWS::GuardDuty::Detector
arn:partition:guardduty:region:account_ID:detector/detector_ID
AWS::IoT::Certificate
arn:partition:iot:region:account_ID:cert/certificate_ID
AWS::IoT::Thing
arn:partition:iot:region:account_ID:thing/thing_ID
AWS::IoTSiteWise::Asset
arn:partition:iotsitewise:region:account_ID:asset/asset_ID
AWS::IoTSiteWise::TimeSeries
arn:partition:iotsitewise:region:account_ID:timeseries/timeseries_ID
AWS::IoTTwinMaker::Entity
arn:partition:iottwinmaker:region:account_ID:workspace/workspace_ID/entity/entity_ID
AWS::IoTTwinMaker::Workspace
arn:partition:iottwinmaker:region:account_ID:workspace/workspace_ID
AWS::KendraRanking::ExecutionPlan
arn:partition:kendra-ranking:region:account_ID:rescore-execution-plan/rescore_execution_plan_ID
AWS::Kinesis::Stream
arn:partition:kinesis:region:account_ID:stream/stream_name
AWS::Kinesis::StreamConsumer
arn:partition:kinesis:region:account_ID:stream_type/stream_name/consumer/consumer_name:consumer_creation_timestamp
AWS::KinesisVideo::Stream
arn:partition:kinesisvideo:region:account_ID:stream/stream_name/creation_time
AWS::GeoMaps::Provider
arn:partition:geo-maps:region::provider/provider_ID
AWS::GeoPlaces::Provider
arn:partition:geo-places:region::provider/provider_ID
AWS::GeoRoutes::Provider
arn:partition:geo-route:region::provider/provider_ID
AWS::MachineLearning::MlModel
arn:partition:machinelearning:region:account_ID:mlmodel/model_ID
AWS::ManagedBlockchain::Network
arn:partition:managedblockchain:::networks/network_name
AWS::ManagedBlockchain::Node
arn:partition:managedblockchain:region:account_ID:nodes/node_ID
AWS::MedicalImaging::Datastore
arn:partition:medical-imaging:region:account_ID:datastore/data_store_ID
AWS::MWAA::Environment
arn:partition:airflow:region:account_ID:environment/environment_name
AWS::NeptuneGraph::Graph
arn:partition:neptune-graph:region:account_ID:graph/graph_ID
AWS::One::UKey
arn:partition:one:region:account_ID:user/user_ID/u-key/u-key_ID
AWS::One::User
arn:partition:one:region:account_ID:user/user_ID
AWS::PaymentCryptography::Alias
arn:partition:payment-cryptography:region:account_ID:alias/alias
AWS::PaymentCryptography::Key
arn:partition:payment-cryptography:region:account_ID:key/key_ID
AWS::PCAConnectorAD::Connector
arn:partition:pca-connector-ad:region:account_ID:connector/connector_ID
AWS::PCAConnectorSCEP::Connector
arn:partition:pca-connector-scep:region:account_ID:connector/connector_ID
AWS::QApps:QApp
arn:partition:qapps:region:account_ID:application/application_UUID/qapp/qapp_UUID
AWS::QBusiness::Application
arn:partition:qbusiness:region:account_ID:application/application_ID
AWS::QBusiness::DataSource
arn:partition:qbusiness:region:account_ID:application/application_ID/index/index_ID/data-source/datasource_ID
AWS::QBusiness::Index
arn:partition:qbusiness:region:account_ID:application/application_ID/index/index_ID
AWS::QBusiness::WebExperience
arn:partition:qbusiness:region:account_ID:application/application_ID/web-experience/web_experienc_ID
AWS::RDS::DBCluster
arn:partition:rds:region:account_ID:cluster/cluster_name
AWS::ResourceExplorer2::ManagedView
arn:partition:resource-explorer-2:region:account_ID:managed-view/view_name/view_UUID
AWS::ResourceExplorer2::View
arn:partition:resource-explorer-2:region:account_ID:view/view_name/view_UUID
AWS::RUM::AppMonitor
arn:partition:rum:region:account_ID:appmonitor/app_monitor_name

AWS::S3::AccessPoint3

arn:partition:s3:region:account_ID:accesspoint/access_point_name

AWS::S3Express::Object

arn:partition:s3express:region:account_ID:bucket/bucket_name
AWS::S3ObjectLambda::AccessPoint
arn:partition:s3-object-lambda:region:account_ID:accesspoint/access_point_name
AWS::S3Outposts::Object
arn:partition:s3-outposts:region:account_ID:object_path
AWS::SageMaker::Endpoint
arn:partition:sagemaker:region:account_ID:endpoint/endpoint_name
AWS::SageMaker::ExperimentTrialComponent
arn:partition:sagemaker:region:account_ID:experiment-trial-component/experiment_trial_component_name
AWS::SageMaker::FeatureGroup
arn:partition:sagemaker:region:account_ID:feature-group/feature_group_name
AWS::SCN::Instance
arn:partition:scn:region:account_ID:instance/instance_ID
AWS::ServiceDiscovery::Namespace
arn:partition:servicediscovery:region:account_ID:namespace/namespace_ID
AWS::ServiceDiscovery::Service
arn:partition:servicediscovery:region:account_ID:service/service_ID
AWS::SitewiseAssistant::Conversation
arn:partition:sitewise-assistant:region:account_ID:conversation/conversation_ID
AWS::SMSVoice::Message

arn:partition:sms-voice:region:account_ID:message/message_ID

AWS::SMSVoice::OriginationIdentity

arn:partition:sms-voice:region:account_ID:.*$

AWS::SNS::PlatformEndpoint
arn:partition:sns:region:account_ID:endpoint/endpoint_type/endpoint_name/endpoint_ID
AWS::SNS::Topic
arn:partition:sns:region:account_ID:topic_name
AWS::SocialMessaging::PhoneNumberId

arn:partition:social-messaging:region:account_ID:phone-number-id/phone_number_ID

AWS::SocialMessaging::WabaId

arn:partition:social-messaging:region:account_ID:waba/waba_ID

AWS::SQS::Queue
arn:partition:sqs:region:account_ID:queue_name
AWS::SSM::ManagedNode

The ARN must be in one of the following formats:

  • arn:partition:ssm:region:account_ID:managed-instance/instance_ID

  • arn:partition:ec2:region:account_ID:instance/instance_ID

AWS::SSMMessages::ControlChannel
arn:partition:ssmmessages:region:account_ID:control-channel/control_channel_ID
AWS::StepFunctions::StateMachine

The ARN must be in one of the following formats:

  • arn:partition:states:region:account_ID:stateMachine:stateMachine_name

  • arn:partition:states:region:account_ID:stateMachine:stateMachine_name/label_name

AWS::SWF::Domain
arn:partition:swf:region:account_ID:/domain/domain_name
AWS::ThinClient::Device
arn:partition:thinclient:region:account_ID:device/device_ID
AWS::ThinClient::Environment
arn:partition:thinclient:region:account_ID:environment/environment_ID
AWS::Timestream::Database
arn:partition:timestream:region:account_ID:database/database_name
AWS::Timestream::Table
arn:partition:timestream:region:account_ID:database/database_name/table/table_name
AWS::VerifiedPermissions::PolicyStore
arn:partition:verifiedpermissions:region:account_ID:policy-store/policy_store_ID

1 For tables with streams enabled, the resources field in the data event contains both AWS::DynamoDB::Stream and AWS::DynamoDB::Table. If you specify AWS::DynamoDB::Table for the resources.type, it will log both DynamoDB table and DynamoDB streams events by default. To exclude streams events, add a filter on the eventName field.

2 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. The trailing slash is intentional; do not exclude it.

3 To log events on all objects in an S3 access point, we recommend that you use only the access point ARN, don’t include the object path, and use the StartsWith or NotStartsWith operators.

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.

  1. Follow the steps in the create trail procedure, or follow the steps in the create event data store procedure.

  2. As you follow the steps to create the trail or event data store, make the following selections:

    1. Choose Data events.

    2. Choose the Resource type for which you want to log data events.

    3. For Log selector template, choose Custom.

    4. (Optional) In Selector name, enter a name to identify your selector. The selector name is a descriptive name for an advanced event selector, such as "Log data events for only two S3 buckets". The selector name is listed as Name in the advanced event selector and is viewable if you expand the JSON view.

    5. In Advanced event selectors, do the following to filter on the resources.ARN:

      1. For Field, choose resources.ARN.

      2. For Operator, choose the condition operator. In this example, we'll choose starts with because we want to log data events for a specific S3 bucket.

      3. For Value, enter the ARN for your resource type (for example, arn:aws:s3:::amzn-s3-demo-bucket).

      4. To filter another resources.ARN, choose + Condition. For information about how CloudTrail evaluates multiple conditions, see How CloudTrail evaluates multiple conditions for a field.

      Filter S3 data events by resources.ARN
    6. Choose +Field to add filters on other fields.

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.

  1. Follow the steps in the create trail procedure, or follow the steps in the create event data store procedure.

  2. As you follow the steps to create the trail or event data store, make the following selections:

    1. Choose Data events.

    2. Choose the Resource type for which you want to log data events.

    3. For Log selector template, choose the appropriate template for your use case.

      Note

      The Log only AWS Management Console events and Exclude AWS service-initiated events templates are available only for event data stores.

      Choose the log selector template for data events
      If you plan to do this Choose this log selector template

      Log read events only and apply no other filters (for example, on the resources.ARN value).

      Log only read events

      Log write events only and apply no other filters (for example, on the resources.ARN value).

      Log only write events

      Filter on the readOnly value and apply additional filters (for example, on the resources.ARN value).

      Custom

      In Advanced event selectors, do the following to filter on the readOnly value:

      To log write events
      1. For Field, choose readOnly.

      2. For Operator, choose equals.

      3. For Value, enter false.

      4. Choose +Field to add filters on other fields.

      To log read events
      1. For Field, choose readOnly.

      2. For Operator, choose equals.

      3. For Value, enter true.

      4. Choose +Field to add filters on other fields.

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"] } ] } ]'