AWS awscloudtrail documentation change
Summary
Restructured documentation to focus on AWS CLI examples, removed redundant 'Supported on trails/event data stores' columns from field descriptions, and added new examples for filtering by eventName, resources.ARN, and userIdentity.arn.
Security assessment
The changes enhance documentation for existing security-related filtering capabilities (e.g., userIdentity.arn, readOnly) but do not address a specific security vulnerability. The added examples demonstrate security-focused use cases like excluding actions from specific IAM roles.
Diff
diff --git a/awscloudtrail/latest/userguide/filtering-data-events.md b/awscloudtrail/latest/userguide/filtering-data-events.md index ae8582d85..4ee3c6831 100644 --- a//awscloudtrail/latest/userguide/filtering-data-events.md +++ b//awscloudtrail/latest/userguide/filtering-data-events.md @@ -5 +5 @@ -How CloudTrail evaluates multiple conditions for a fieldFiltering data events by eventNameFiltering data events by resources.ARNFiltering data events by readOnly value +How CloudTrail evaluates multiple conditions for a fieldAWS CLI examples for filtering data events @@ -9 +9 @@ How CloudTrail evaluates multiple conditions for a fieldFiltering data events by -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. +This section describes how you can use advanced event selectors to create fine-grained selectors for logging data events, which can help you control costs by only logging the specific data events of interest. @@ -22 +22 @@ For example: -The following table provides additional information about the configurable fields for advanced event selectors. +The following table describes the supported fields for filtering data events. For a list of supported fields for each CloudTrail event type, see [AdvancedEventSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedEventSelector.html) in the _AWS CloudTrail API Reference_. @@ -26,9 +26,9 @@ 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](./logging-data-events-with-cloudtrail.html#logging-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 `resources.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](./cloudtrail-event-reference-record-contents.html#ct-event-type) to include or exclude. For example, you can set this field to `NotEquals` `AwsServiceEvent` to exclude [AWS service events](./non-api-aws-service-events.html). **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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). **Supported on trails:** No **Supported on event data stores:** Yes +**`eventCategory` ** | Yes | `Equals` | This field is set to `Data` to log data events. +**`resources.type`** | Yes | `Equals` | This field is used to select the resource type for which you want to log data events. The [Data events](./logging-data-events-with-cloudtrail.html#logging-data-events) table shows the possible values. +**`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. +**`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. +**`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 `resources.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. +**`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. +**`eventType`** | No | `EndsWith` `Equals` `NotEndsWith` `NotEquals` `NotStartsWith` `StartsWith` | The [eventType](./cloudtrail-event-reference-record-contents.html#ct-event-type) to include or exclude. For example, you can set this field to `NotEquals` `AwsServiceEvent` to exclude [AWS service events](./non-api-aws-service-events.html). +**`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`. +**`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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). @@ -87,5 +87 @@ Selectors don't support the use of wildcards like `*` . To match multiple values - * Filtering data events by eventName - - * Filtering data events by resources.ARN - - * Filtering data events by readOnly value + * AWS CLI examples for filtering data events @@ -203,22 +199 @@ 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`. - -###### Topics - - * Filtering data events by eventName using the AWS Management Console - - * Filtering data events by eventName using the AWS CLI - - - - -### 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](./cloudtrail-create-a-trail-using-the-console-first-time.html#creating-a-trail-in-the-console) procedure, or follow the steps in the [create event data store](./query-event-data-store-cloudtrail.html#query-event-data-store-cloudtrail-procedure) procedure. - - 2. As you follow the steps to create the trail or event data store, make the following selections: +## AWS CLI examples for filtering data events @@ -226 +201 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 1. Choose **Data events**. +This section provides AWS CLI examples showing how to filter data events on different fields. For additional AWS CLI examples, see [Log data events for trails by using advanced event selectors](./logging-data-events-with-cloudtrail.html#creating-data-event-selectors-advanced) and [Logging data events for event data stores with the AWS CLI](./logging-data-events-with-cloudtrail.html#logging-data-events-CLI-eds-examples). @@ -228 +203 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 2. Choose the **Resource type** for which you want to log data events. +For information about how to log data events using the console, see [Logging data events with the AWS Management Console](./logging-data-events-with-cloudtrail.html#logging-data-events-console). @@ -230 +205 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 3. For **Log selector template** , choose **Custom**. +###### Examples: @@ -232 +207 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 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**. + * Example 1: Filtering on the eventName field @@ -234 +209 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 5. In **Advanced event selectors** , do the following to filter on the `eventName`: + * Example 2: Filtering on the resources.ARN and userIdentity.arn fields @@ -236 +210,0 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 1. For **Field** , choose **eventName**. @@ -238 +211,0 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 2. For **Operator** , choose the condition operator. In this example, we'll choose **equals** because we want to log a specific API call. @@ -240 +212,0 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 3. For **Value** , enter the name of the event you want to filter on. @@ -242 +214 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 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. +### Example 1: Filtering on the `eventName` field @@ -244,12 +216 @@ Take the following steps to filter on the `eventName` field using the CloudTrail - 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`](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-event-selectors.html) command for a trail, or the [`get-event-data-store`](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-event-data-store.html) 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. +In the first example, the `--advanced-event-selectors` for a trail are configured to log only the `GetObject`, `PutObject`, and `DeleteObject` API calls for Amazon S3 objects in general purpose buckets. @@ -287 +248 @@ The next example creates a new event data store that logs data events for EBS Di -## Filtering data events by `resources.ARN` +### Example 2: Filtering on the `resources.ARN` and `userIdentity.arn` fields @@ -289,59 +250 @@ The next example creates a new event data store that logs data events for EBS Di -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](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) in the _Service Authorization Reference_. - -###### Note - -You can't use the `resources.ARN` field to filter resource types that do not have ARNs. - -###### Topics - - * Filtering data events by resources.ARN using the AWS Management Console - - * Filtering data events by resources.ARN using the AWS CLI - - - - -### 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](./cloudtrail-create-a-trail-using-the-console-first-time.html#creating-a-trail-in-the-console) procedure, or follow the steps in the [create event data store](./query-event-data-store-cloudtrail.html#query-event-data-store-cloudtrail-procedure) 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. - - - - 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`](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-event-selectors.html) command for a trail, or the [`get-event-data-store`](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-event-data-store.html) 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. +The following example shows how to include all data events for all Amazon S3 objects in a specific general purpose S3 bucket but exclude events generated by the `bucket-scanner-role` `userIdentity`. 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`. @@ -351,2 +254 @@ The following example shows how to configure your trail to include all data even - --trail-name TrailName \ - --region region \ + --trail-name trailName \ @@ -360 +262,2 @@ The following example shows how to configure your trail to include all data even - { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3:::amzn-s3-demo-bucket/"] } + { "Field": "resources.ARN", "StartsWith": ["arn:partition:s3:::amzn-s3-demo-bucket/"] }, + { "Field": "userIdentity.arn", "NotStartsWith": ["arn:aws:sts::123456789012:assumed-role/bucket-scanner-role"]} @@ -365,99 +267,0 @@ The following example shows how to configure your trail to include all data even -## 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. - -###### Topics - - * Filtering data events by readOnly value using the AWS Management Console - - * Filtering data events by readOnly value using the AWS CLI - - - - -### 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](./cloudtrail-create-a-trail-using-the-console-first-time.html#creating-a-trail-in-the-console) procedure, or follow the steps in the [create event data store](./query-event-data-store-cloudtrail.html#query-event-data-store-cloudtrail-procedure) 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.