# Security in AWS CloudTrail
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.
Security is a shared responsibility between AWS and you. The [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security *of* the cloud and security *in* the cloud:
+ **Security of the cloud** – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the [AWS compliance programs](https://aws.amazon.com/compliance/programs/). To learn about the compliance programs that apply to AWS CloudTrail, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/).
+ **Security in the cloud** – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations.
This documentation helps you understand how to apply the shared responsibility model when using CloudTrail. The following topics show you how to configure CloudTrail to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your CloudTrail resources.
**Topics**
+ [Data protection in AWS CloudTrail](data-protection.md)
+ [Identity and Access Management for AWS CloudTrail](security-iam.md)
+ [Compliance validation for AWS CloudTrail](CloudTrail-compliance.md)
+ [Resilience in AWS CloudTrail](disaster-recovery-resiliency.md)
+ [Infrastructure security in AWS CloudTrail](infrastructure-security.md)
+ [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md)
+ [Security best practices in AWS CloudTrail](best-practices-security.md)
+ [Encrypting CloudTrail log files, digest files, and event data stores with AWS KMS keys (SSE-KMS)](encrypting-cloudtrail-log-files-with-aws-kms.md)
# Data protection in AWS CloudTrail
The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in AWS CloudTrail. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/). For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*.
For data protection purposes, we recommend that you protect AWS account credentials and set up individual users with AWS IAM Identity Center or AWS Identity and Access Management (IAM). That way, each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
+ Use multi-factor authentication (MFA) with each account.
+ Use SSL/TLS to communicate with AWS resources. We require TLS 1.2 and recommend TLS 1.3.
+ Set up API and user activity logging with AWS CloudTrail. For information about using CloudTrail trails to capture AWS activities, see [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html) in the *AWS CloudTrail User Guide*.
+ Use AWS encryption solutions, along with all default security controls within AWS services.
+ Use advanced managed security services such as Amazon Macie, which assists in discovering and securing sensitive data that is stored in Amazon S3.
+ If you require FIPS 140-3 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/).
We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form text fields such as a **Name** field. This includes when you work with CloudTrail or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form text fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.
By default, CloudTrail event log files and digest files are encrypted using Amazon S3 server-side encryption (SSE). You can also choose to encrypt your log files and digest files with an AWS Key Management Service (AWS KMS) key. You can store your log files in your bucket for as long as you want. You can also define Amazon S3 lifecycle rules to archive or delete log files automatically. If you want notifications about log file delivery and validation, you can set up Amazon SNS notifications.
The following security best practices also address data protection in CloudTrail:
+ [Encrypting CloudTrail log files, digest files, and event data stores with AWS KMS keys (SSE-KMS)](encrypting-cloudtrail-log-files-with-aws-kms.md)
+ [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md)
+ [Validating CloudTrail log file integrity](cloudtrail-log-file-validation-intro.md)
+ [Sharing CloudTrail log files between AWS accounts](cloudtrail-sharing-logs.md)
Because CloudTrail logs files are stored in a bucket or buckets in Amazon S3, you should also review the data protection information in the Amazon Simple Storage Service User Guide. For more information, see [Data protection in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/DataDurability.html).
# Identity and Access Management for AWS CloudTrail
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use CloudTrail resources. IAM is an AWS service that you can use with no additional charge.
**Topics**
+ [Audience](#security_iam_audience)
+ [Authenticating with identities](#security_iam_authentication)
+ [Managing access using policies](#security_iam_access-manage)
+ [How AWS CloudTrail works with IAM](security_iam_service-with-iam.md)
+ [Identity-based policy examples for AWS CloudTrail](security_iam_id-based-policy-examples.md)
+ [AWS CloudTrail resource-based policy examples](security_iam_resource-based-policy-examples.md)
+ [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md)
+ [Amazon S3 bucket policy for CloudTrail Lake query results](s3-bucket-policy-lake-query-results.md)
+ [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md)
+ [Troubleshooting AWS CloudTrail identity and access](security_iam_troubleshoot.md)
+ [Using service-linked roles for CloudTrail](using-service-linked-roles.md)
+ [AWS managed policies for AWS CloudTrail](security-iam-awsmanpol.md)
## Audience
How you use AWS Identity and Access Management (IAM) differs based on your role:
+ **Service user** - request permissions from your administrator if you cannot access features (see [Troubleshooting AWS CloudTrail identity and access](security_iam_troubleshoot.md))
+ **Service administrator** - determine user access and submit permission requests (see [How AWS CloudTrail works with IAM](security_iam_service-with-iam.md))
+ **IAM administrator** - write policies to manage access (see [Identity-based policy examples for AWS CloudTrail](security_iam_id-based-policy-examples.md))
## Authenticating with identities
Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role.
You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*.
For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*.
### AWS account root user
When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*.
### Federated identity
As a best practice, require human users to use federation with an identity provider to access AWS services using temporary credentials.
A *federated identity* is a user from your enterprise directory, web identity provider, or Directory Service that accesses AWS services using credentials from an identity source. Federated identities assume roles that provide temporary credentials.
For centralized access management, we recommend AWS IAM Identity Center. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*.
### IAM users and groups
An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*.
An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*.
### IAM roles
An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*.
IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.
## Managing access using policies
You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*.
Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**.
By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation.
### Identity-based policies
Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*.
### Resource-based policies
Resource-based policies are JSON policy documents that you attach to a resource. Examples include IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy.
Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy.
### Other policy types
AWS supports additional policy types that can set the maximum permissions granted by more common policy types:
+ **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*.
+ **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
+ **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*.
+ **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*.
### Multiple policy types
When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*.
# How AWS CloudTrail works with IAM
Before you use IAM to manage access to CloudTrail, learn what IAM features are available to use with CloudTrail.
**IAM features you can use with AWS CloudTrail**
| IAM feature | CloudTrail support |
| --- | --- |
| [Identity-based policies](#security_iam_service-with-iam-id-based-policies) | Yes |
| [Resource-based policies](#security_iam_service-with-iam-resource-based-policies) | Partial |
| [Policy actions](#security_iam_service-with-iam-id-based-policies-actions) | Yes |
| [Policy resources](#security_iam_service-with-iam-id-based-policies-resources) | Yes |
| [Policy condition keys (service-specific)](#security_iam_service-with-iam-id-based-policies-conditionkeys) | No |
| [ACLs](#security_iam_service-with-iam-acls) | No |
| [ABAC (tags in policies)](#security_iam_service-with-iam-tags) | Yes |
| [Temporary credentials](#security_iam_service-with-iam-roles-tempcreds) | Yes |
| [Forward access sessions (FAS)](#security_iam_service-with-iam-principal-permissions) | Yes |
| [Service roles](#security_iam_service-with-iam-roles-service) | Yes |
| [Service-linked roles](#security_iam_service-with-iam-roles-service-linked) | Yes |
To get a high-level view of how CloudTrail and other AWS services work with most IAM features, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*.
## Identity-based policies for CloudTrail
**Supports identity-based policies:** Yes
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. To learn about all of the elements that you can use in a JSON policy, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.
### Identity-based policy examples for CloudTrail
To view examples of CloudTrail identity-based policies, see [Identity-based policy examples for AWS CloudTrail](security_iam_id-based-policy-examples.md).
## Resource-based policies within CloudTrail
**Supports resource-based policies:** Partial
Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource-based policies are IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services.
To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.
CloudTrail supports the following types of resource-based policies:
+ Resource-based policies on channels used for CloudTrail Lake integrations with event sources outside of AWS. The resource-based policy for the channel defines which principal entities (accounts, users, roles, and federated users) can call `PutAuditEvents` on the channel to deliver events to the destination event data store. For more information about creating integrations with CloudTrail Lake, see [Create an integration with an event source outside of AWS](query-event-data-store-integration.md).
+ Resource-based polices to control which principals can perform actions on your event data store. You can use resource-based policies to provide cross-account access to your event data stores.
+ Resource-based policies on dashboards to allow CloudTrail to refresh a CloudTrail Lake dashboard at the interval you define when you set a refresh schedule for a dashboard. For more information, see [Set a refresh schedule for a custom dashboard with the CloudTrail console](lake-dashboard-refresh.md).
### Examples
To view examples of CloudTrail resource-based policies, see [AWS CloudTrail resource-based policy examples](security_iam_resource-based-policy-examples.md).
## Policy actions for CloudTrail
**Supports policy actions:** Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Include actions in a policy to grant permissions to perform the associated operation.
To see a list of CloudTrail actions, see [Actions Defined by AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html#awscloudtrail-actions-as-permissions) in the *Service Authorization Reference*.
Policy actions in CloudTrail use the following prefix before the action:
```
cloudtrail
```
For example, to grant someone permission to list tags for a trail with the `ListTags` API operation, you include the `cloudtrail:ListTags` action in their policy. Policy statements must include either an `Action` or `NotAction` element. CloudTrail defines its own set of actions that describe tasks that you can perform with this service.
To specify multiple actions in a single statement, separate them with commas as follows:
```
"Action": [
"cloudtrail:AddTags",
"cloudtrail:ListTags",
"cloudtrail:RemoveTags
```
You can specify multiple actions using wildcards (`*`). For example, to specify all actions that begin with the word `Get`, include the following action:
```
"Action": "cloudtrail:Get*"
```
## Policy resources for CloudTrail
**Supports policy resources:** Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (\$1) to indicate that the statement applies to all resources.
```
"Resource": "*"
```
To see a list of CloudTrail resource types and their ARNs, see [Resources Defined by AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html#awscloudtrail-resources-for-iam-policies) in the *Service Authorization Reference*. To learn with which actions you can specify the ARN of each resource, see [Actions Defined by AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html#awscloudtrail-actions-as-permissions).
In CloudTrail, there are four resource types: trails, event data stores, dashboards, and channels. Each resource has a unique Amazon Resource Name (ARN) associated with it. In a policy, you use an ARN to identify the resource that the policy applies to. CloudTrail does not currently support other resource types, which are sometimes referred to as subresources.
The CloudTrail trail resource has the following ARN:
```
arn:${Partition}:cloudtrail:${Region}:${Account}:trail/{TrailName}
```
The CloudTrail event data store resource has the following ARN:
```
arn:${Partition}:cloudtrail:${Region}:${Account}:eventdatastore/{EventDataStoreId}
```
The CloudTrail dashboard resource has the following ARN:
```
arn:${Partition}:cloudtrail:${Region}:${Account}:dashboard/{DashboardName}
```
The CloudTrail channel resource has the following ARN:
```
arn:${Partition}:cloudtrail:${Region}:${Account}:channel/{ChannelId}
```
For more information about the format of ARNs, see [Amazon Resource Names (ARNs) and AWS Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
For example, for an AWS account with the ID *123456789012*, to specify a trail named *My-Trail* that exists in the US East (Ohio) Region in your statement, use the following ARN:
```
"Resource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/My-Trail"
```
To specify all trails that belong to a specific account in that AWS Region, use the wildcard (\$1):
```
"Resource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/*"
```
Some CloudTrail actions, such as those for creating resources, can't be performed on a specific resource. In those cases, you must use the wildcard (`*`).
```
"Resource": "*"
```
Many CloudTrail API actions involve multiple resources. For example, `CreateTrail` requires an Amazon S3 bucket for storing log files, so a user must have permissions to write to the bucket. To specify multiple resources in a single statement, separate the ARNs with commas.
```
"Resource": [
"resource1",
"resource2"
```
## Policy condition keys for CloudTrail
**Supports service-specific policy condition keys:** No
Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**.
The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
CloudTrail doesn't define its own condition keys, but it supports using some global condition keys. To see all AWS global condition keys, see [AWS Global Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
To see a list of CloudTrail condition keys, see [Condition Keys for AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html#awscloudtrail-policy-keys) in the *Service Authorization Reference*. To learn with which actions and resources you can use a condition key, see [Actions Defined by AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html#awscloudtrail-actions-as-permissions).
## ACLs in CloudTrail
**Supports ACLs:** No
Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.
## ABAC with CloudTrail
**Supports ABAC (tags in policies):** Yes
Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes called tags. You can attach tags to IAM entities and AWS resources, then design ABAC policies to allow operations when the principal's tag matches the tag on the resource.
To control access based on tags, you provide tag information in the [condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy using the `aws:ResourceTag/key-name`, `aws:RequestTag/key-name`, or `aws:TagKeys` condition keys.
If a service supports all three condition keys for every resource type, then the value is **Yes** for the service. If a service supports all three condition keys for only some resource types, then the value is **Partial**.
For more information about ABAC, see [Define permissions with ABAC authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) in the *IAM User Guide*. To view a tutorial with steps for setting up ABAC, see [Use attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) in the *IAM User Guide*.
You can attach tags to CloudTrail resources or pass tags in a request to CloudTrail. For more information about tagging CloudTrail resources, see [Creating a trail with the CloudTrail console](cloudtrail-create-a-trail-using-the-console-first-time.md) and [Creating, updating, and managing trails with the AWS CLI](cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.md).
## Using temporary credentials with CloudTrail
**Supports temporary credentials:** Yes
Temporary credentials provide short-term access to AWS resources and are automatically created when you use federation or switch roles. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) and [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*.
## Forward access sessions for CloudTrail
**Supports forward access sessions (FAS):** Yes
Forward access sessions (FAS) use the permissions of the principal calling an AWS service, combined with the requesting AWS service to make requests to downstream services. For policy details when making FAS requests, see [Forward access sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html).
## Service roles for CloudTrail
**Supports service roles:** Yes
A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*.
**Warning**
Changing the permissions for a service role might break CloudTrail functionality. Edit service roles only when CloudTrail provides guidance to do so.
## Service-linked roles for CloudTrail
**Supports service-linked roles:** Yes
A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.
CloudTrail supports a service-linked role for integration with AWS Organizations. This role is required for the creation of an organization trail or event data store. Organization trails and event data stores log events for all AWS accounts in an organization. For more information about creating or managing CloudTrail service-linked roles, see [Using service-linked roles for CloudTrail](using-service-linked-roles.md).
# Identity-based policy examples for AWS CloudTrail
By default, users and roles don't have permission to create or modify CloudTrail resources. To grant users permission to perform actions on the resources that they need, an IAM administrator can create IAM policies.
To learn how to create an IAM identity-based policy by using these example JSON policy documents, see [Create IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in the *IAM User Guide*.
For details about actions and resource types defined by CloudTrail, including the format of the ARNs for each of the resource types, see [Actions, Resources, and Condition Keys for AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html) in the *Service Authorization Reference*.
**Topics**
+ [Policy best practices](#security_iam_service-with-iam-policy-best-practices)
+ [Example: Allowing and denying actions for a specified trail](#security_iam_id-based-policy-examples-allow-deny-for-specific-trail)
+ [Examples: Creating and applying policies for actions on specific trails](#grant-custom-permissions-for-cloudtrail-users-resource-level)
+ [Examples: Denying access to create or delete event data stores based on tags](#security_iam_id-based-policy-examples-eds-tags)
+ [Using the CloudTrail console](#security_iam_id-based-policy-examples-console)
+ [Allow users to view their own permissions](#security_iam_id-based-policy-examples-view-own-permissions)
+ [Granting custom permissions for CloudTrail users](#grant-custom-permissions-for-cloudtrail-users)
## Policy best practices
Identity-based policies determine whether someone can create, access, or delete CloudTrail resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
+ **Get started with AWS managed policies and move toward least-privilege permissions** – To get started granting permissions to your users and workloads, use the *AWS managed policies* that grant permissions for many common use cases. They are available in your AWS account. We recommend that you reduce permissions further by defining AWS customer managed policies that are specific to your use cases. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) or [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*.
+ **Apply least-privilege permissions** – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as *least-privilege permissions*. For more information about using IAM to apply permissions, see [ Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
+ **Use conditions in IAM policies to further restrict access** – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific AWS service, such as CloudFormation. For more information, see [ IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*.
+ **Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions** – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see [Validate policies with IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html) in the *IAM User Guide*.
+ **Require multi-factor authentication (MFA)** – If you have a scenario that requires IAM users or a root user in your AWS account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see [ Secure API access with MFA](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html) in the *IAM User Guide*.
For more information about best practices in IAM, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
CloudTrail doesn't have service-specific context keys that you can use in the `Condition` element of policy statements.
## Example: Allowing and denying actions for a specified trail
The following example demonstrates a policy that allows users with the policy to view the status and configuration of a trail and start and stop logging for a trail named *My-First-Trail*. This trail was created in the US East (Ohio) Region (its home Region) in the AWS account with the ID *123456789012*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudtrail:StartLogging",
"cloudtrail:StopLogging",
"cloudtrail:GetTrail",
"cloudtrail:GetTrailStatus",
"cloudtrail:GetEventSelectors"
],
"Resource": [
"arn:aws:cloudtrail:us-east-2:123456789012:trail/My-First-Trail"
]
}
]
}
```
------
The following example demonstrates a policy that explicitly denies CloudTrail actions for any trail not named *My-First-Trail*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"cloudtrail:*"
],
"NotResource": [
"arn:aws:cloudtrail:us-east-2:123456789012:trail/My-First-Trail"
]
}
]
}
```
------
## Examples: Creating and applying policies for actions on specific trails
You can use permissions and policies to control a user's ability to perform specific actions on CloudTrail trails.
For example, you don't want users of your company’s developer group to start or stop logging on a specific trail. However, you might want to grant them permission to perform the `DescribeTrails` and `GetTrailStatus` actions on the trail. You want the users of the developer group to perform the `StartLogging` or `StopLogging` actions on trails that they manage.
You can create two policy statements and attach them to the developer group you create in IAM. For more information about groups in IAM, see [IAM Groups](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) in the *IAM User Guide*.
In the first policy, you deny the `StartLogging` and `StopLogging` actions for the trail ARN that you specify. In the following example, the trail ARN is `arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1446057698000",
"Effect": "Deny",
"Action": [
"cloudtrail:StartLogging",
"cloudtrail:StopLogging"
],
"Resource": [
"arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail"
]
}
]
}
```
------
In the second policy, the `DescribeTrails` and `GetTrailStatus` actions are allowed on all CloudTrail resources:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1446072643000",
"Effect": "Allow",
"Action": [
"cloudtrail:DescribeTrails",
"cloudtrail:GetTrail",
"cloudtrail:GetTrailStatus"
],
"Resource": [
"*"
]
}
]
}
```
------
If a user of the developer group tries to start or stop logging on the trail that you specified in the first policy, that user gets an access denied exception. Users of the developer group can start and stop logging on trails that they create and manage.
The following examples show that the configured developer group in an AWS CLI profile named `devgroup`. First, a user of `devgroup` runs the `describe-trails` command.
```
$ aws --profile devgroup cloudtrail describe-trails
```
The command complete successfully with the following output:
```
{
"trailList": [
{
"IncludeGlobalServiceEvents": true,
"Name": "Default",
"TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail",
"IsMultiRegionTrail": false,
"S3BucketName": "amzn-s3-demo-bucket",
"HomeRegion": "us-east-2"
}
]
}
```
The user then runs the `get-trail-status` command on the trail that you specified in the first policy.
```
$ aws --profile devgroup cloudtrail get-trail-status --name Example-Trail
```
The command complete successfully with the following output:
```
{
"LatestDeliveryTime": 1449517556.256,
"LatestDeliveryAttemptTime": "2015-12-07T19:45:56Z",
"LatestNotificationAttemptSucceeded": "",
"LatestDeliveryAttemptSucceeded": "2015-12-07T19:45:56Z",
"IsLogging": true,
"TimeLoggingStarted": "2015-12-07T19:36:27Z",
"StartLoggingTime": 1449516987.685,
"StopLoggingTime": 1449516977.332,
"LatestNotificationAttemptTime": "",
"TimeLoggingStopped": "2015-12-07T19:36:17Z"
}
```
Next, a user in the `devgroup` group runs the `stop-logging` command on the same trail.
```
$ aws --profile devgroup cloudtrail stop-logging --name Example-Trail
```
The command returns an access denied exception, such as the following:
```
A client error (AccessDeniedException) occurred when calling the StopLogging operation: Unknown
```
The user runs the `start-logging` command on the same trail.
```
$ aws --profile devgroup cloudtrail start-logging --name Example-Trail
```
Again the command returns an access denied exception, such as the following:
```
A client error (AccessDeniedException) occurred when calling the StartLogging operation: Unknown
```
## Examples: Denying access to create or delete event data stores based on tags
In the following policy example, permission to create an event data store with `CreateEventDataStore` is denied if at least one of the following conditions aren't met:
+ The event data store doesn't have a tag key of `stage` applied to itself
+ The value of the stage tag isn't `alpha`, `beta`, `gamma`, or `prod`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "cloudtrail:CreateEventDataStore",
"Resource": "*",
"Condition": {
"Null": {
"aws:RequestTag/stage": "true"
}
}
},
{
"Effect": "Deny",
"Action": "cloudtrail:CreateEventDataStore",
"Resource": "*",
"Condition": {
"ForAnyValue:StringNotEquals": {
"aws:RequestTag/stage": [
"alpha",
"beta",
"gamma",
"prod"
]
}
}
}
]
}
```
------
In the following policy example, permission to delete an event data store with `DeleteEventDataStore` is denied is if the event data store has a `stage` tag with a value of `prod`. A policy like this one can help protect an event data store from accidental deletion.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "cloudtrail:DeleteEventDataStore",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/stage": "prod"
}
}
}
]
}
```
------
## Using the CloudTrail console
To access the AWS CloudTrail console, you must have a minimum set of permissions. These permissions must allow you to list and view details about the CloudTrail resources in your AWS account. If you create an identity-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities (users or roles) with that policy.
You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API. Instead, allow access to only the actions that match the API operation that they're trying to perform.
### Granting permissions for CloudTrail administration
To allow IAM roles or users to administer a CloudTrail resource, such as a trail, event data store, or channel, you must grant explicit permissions to perform the actions associated with CloudTrail tasks. In most situations, you can use an AWS managed policy that contains predefined permissions.
**Note**
The permissions you grant to users to perform CloudTrail administration tasks aren't the same as the permissions that CloudTrail requires to deliver log files to Amazon S3 buckets or send notifications to Amazon SNS topics. For more information about those permissions, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md).
If you configure integration with Amazon CloudWatch Logs, CloudTrail also requires a role that it can assume to deliver events to an Amazon CloudWatch Logs log group. You must create the role that CloudTrail uses. For more information, see [Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console](#grant-cloudwatch-permissions-for-cloudtrail-users) and [Sending events to CloudWatch Logs](send-cloudtrail-events-to-cloudwatch-logs.md).
The following AWS managed policies are available for CloudTrail:
+ [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) – This policy provides full access to CloudTrail actions on CloudTrail resources, such as trails, event data stores, and channels. This policy provides the required permissions to create, update, and delete CloudTrail trails, event data stores, and channels.
This policy also provides permissions to manage the Amazon S3 bucket, the log group for CloudWatch Logs, and an Amazon SNS topic for a trail. However, the `AWSCloudTrail_FullAccess` managed policy doesn't provide permissions to delete the Amazon S3 bucket, the log group for CloudWatch Logs, or an Amazon SNS topic. For information about managed policies for other AWS services, see the [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/about-managed-policy-reference.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/about-managed-policy-reference.html).
**Note**
The **AWSCloudTrail\$1FullAccess** policy isn't intended to be shared broadly across your AWS account. Users with this role can turn off or reconfigure the most sensitive and important auditing functions in their AWS accounts. For this reason, you must only apply this policy to account administrators. You must closely control and monitor use of this policy.
+ [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html) – This policy grants permissions to view the CloudTrail console, including recent events and event history. This policy also allows you to view existing trails, event data stores, and channels. Roles and users with this policy can [download the event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events-console.html#downloading-events), but they can't create or update trails, event data stores, or channels.
To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:
Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
#### Additional resources
To learn more about using IAM to give identities, such as users and roles, access to resources in your account, see [Getting set up with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-set-up.html) and [Access management for AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*.
You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API. Instead, allow access to only the actions that match the API operation that you're trying to perform.
## Allow users to view their own permissions
This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}
```
## Granting custom permissions for CloudTrail users
CloudTrail policies grant permissions to users who work with CloudTrail. If you need to grant different permissions to users, you can attach a CloudTrail policy to an IAM group or to a user. You can edit the policy to include or exclude specific permissions. You can also create your own custom policy. Policies are JSON documents that define the actions a user is allowed to perform and the resources that the user is allowed to perform those actions on. For specific examples, see [Example: Allowing and denying actions for a specified trail](#security_iam_id-based-policy-examples-allow-deny-for-specific-trail) and [Examples: Creating and applying policies for actions on specific trails](#grant-custom-permissions-for-cloudtrail-users-resource-level).
**Contents**
+ [Read-only access](#grant-custom-permissions-for-cloudtrail-users-read-only)
+ [Full access](#grant-custom-permissions-for-cloudtrail-users-full-access)
+ [Granting permission to view AWS Config information on the CloudTrail console](#grant-aws-config-permissions-for-cloudtrail-users)
+ [Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console](#grant-cloudwatch-permissions-for-cloudtrail-users)
+ [Additional information](#cloudtrail-notifications-more-info-2)
### Read-only access
The following example shows a policy that grants read-only access to CloudTrail trails. This is equivalent to the managed policy **AWSCloudTrail\$1ReadOnlyAccess**. It grants users permission to see trail information, but not to create or update trails.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudtrail:Get*",
"cloudtrail:Describe*",
"cloudtrail:List*",
"cloudtrail:LookupEvents"
],
"Resource": "*"
}
]
}
```
------
In the policy statements, the `Effect` element specifies whether the actions are allowed or denied. The `Action` element lists the specific actions that the user is allowed to perform. The `Resource` element lists the AWS resources the user is allowed to perform those actions on. For policies that control access to CloudTrail actions, the `Resource` element is usually set to `*`, a wildcard that means "all resources."
The values in the `Action` element correspond to the APIs that the services support. The actions are preceded by `cloudtrail:` to indicate that they refer to CloudTrail actions. You can use the `*` wildcard character in the `Action` element , such as in the following examples:
+ `"Action": ["cloudtrail:*Logging"]`
This allows all CloudTrail actions that end with "Logging" (`StartLogging`, `StopLogging`).
+ `"Action": ["cloudtrail:*"]`
This allows all CloudTrail actions, but not actions for other AWS services.
+ `"Action": ["*"]`
This allows all AWS actions. This permission is suitable for a user who acts as an AWS administrator for your account.
The read-only policy doesn't grant user permission for the `CreateTrail`, `UpdateTrail`, `StartLogging`, and `StopLogging` actions. Users with this policy are not allowed to create trails, update trails, or turn logging on and off. For the list of CloudTrail actions, see the [AWS CloudTrail API Reference](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/).
### Full access
The following example shows a policy that grants full access to CloudTrail. This is equivalent to the managed policy **AWSCloudTrail\$1FullAccess**. It grants users the permission to perform all CloudTrail actions. It also lets users log data events in Amazon S3 and AWS Lambda, manage files in Amazon S3 buckets, manage how CloudWatch Logs monitors CloudTrail log events, and manage Amazon SNS topics in the account that the user is associated with.
**Important**
The **AWSCloudTrail\$1FullAccess** policy or equivalent permissions are not intended to be shared broadly across your AWS account. Users with this role or equivalent access have the ability to disable or reconfigure the most sensitive and important auditing functions in their AWS accounts. For this reason, this policy should be applied only to account administrators, and use of this policy should be closely controlled and monitored.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:AddPermission",
"sns:CreateTopic",
"sns:SetTopicAttributes",
"sns:GetTopicAttributes"
],
"Resource": [
"arn:aws:sns:*:*:aws-cloudtrail-logs*"
]
},
{
"Effect": "Allow",
"Action": [
"sns:ListTopics"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:CreateBucket",
"s3:PutBucketPolicy"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-logging-bucket1*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetBucketLocation",
"s3:GetBucketPolicy"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "cloudtrail:*",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup"
],
"Resource": [
"arn:aws:logs:*:*:log-group:aws-cloudtrail-logs*"
]
},
{
"Effect": "Allow",
"Action": [
"iam:ListRoles",
"iam:GetRolePolicy",
"iam:GetUser"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"iam:PassedToService": "cloudtrail.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"kms:CreateKey",
"kms:CreateAlias",
"kms:ListKeys",
"kms:ListAliases"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"lambda:ListFunctions"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"dynamodb:ListGlobalTables",
"dynamodb:ListTables"
],
"Resource": "*"
}
]
}
```
------
### Granting permission to view AWS Config information on the CloudTrail console
You can view event information on the CloudTrail console, including resources that are related to that event. For these resources, you can choose the AWS Config icon to view the timeline for that resource in the AWS Config console. Attach this policy to your users to grant them read-only AWS Config access. The policy doesn't grant them permission to change settings in AWS Config.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"config:Get*",
"config:Describe*",
"config:List*"
],
"Resource": "*"
}]
}
```
------
For more information, see [Viewing resources referenced with AWS Config](view-cloudtrail-events-console.md#viewing-resources-config).
### Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console
You can view and configure delivery of events to CloudWatch Logs in the CloudTrail console if you have sufficient permissions. These are permissions that may be beyond those granted for CloudTrail administrators. Attach this policy to administrators who will configure and manage CloudTrail integration with CloudWatch Logs. The policy doesn't grant them permissions in CloudTrail or in CloudWatch Logs directly, but instead grants the permissions required to create and configure the role CloudTrail will assume to successfully deliver events to your CloudWatch Logs group.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:PutRolePolicy",
"iam:AttachRolePolicy",
"iam:ListRoles",
"iam:GetRolePolicy",
"iam:GetUser"
],
"Resource": "*"
}]
}
```
------
For more information, see [Monitoring CloudTrail Log Files with Amazon CloudWatch Logs](monitor-cloudtrail-log-files-with-cloudwatch-logs.md).
### Additional information
To learn more about using IAM to give identities, such as users and roles, access to resources in your account, see [Getting started](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-set-up.html) and [Access management for AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*.
# AWS CloudTrail resource-based policy examples
This section provides example resource-based polices for CloudTrail Lake dashboards, event data stores, and channels.
CloudTrail supports the following types of resource-based policies:
+ Resource-based policies on channels used for CloudTrail Lake integrations with event sources outside of AWS. The resource-based policy for the channel defines which principal entities (accounts, users, roles, and federated users) can call `PutAuditEvents` on the channel to deliver events to the destination event data store. For more information about creating integrations with CloudTrail Lake, see [Create an integration with an event source outside of AWS](query-event-data-store-integration.md).
+ Resource-based polices to control which principals can perform actions on your event data store. You can use resource-based policies to provide cross-account access to your event data stores.
+ Resource-based policies on dashboards to allow CloudTrail to refresh a CloudTrail Lake dashboard at the interval you define when you set a refresh schedule for a dashboard. For more information, see [Set a refresh schedule for a custom dashboard with the CloudTrail console](lake-dashboard-refresh.md).
**Topics**
+ [Resource-based policy examples for channels](#security_iam_resource-based-policy-examples-channels)
+ [Resource-based policy examples for event data stores](#security_iam_resource-based-policy-examples-eds)
+ [Resource-based policy example for a dashboard](#security_iam_resource-based-policy-examples-dashboards)
## Resource-based policy examples for channels
The resource-based policy for the channel defines which principal entities (accounts, users, roles, and federated users) can call `PutAuditEvents` on the channel to deliver events to the destination event data store.
The information required for the policy is determined by the integration type.
+ For a direction integration, CloudTrail requires the policy to contain the partner's AWS account IDs, and requires you to enter the unique external ID provided by the partner. CloudTrail automatically adds the partner's AWS account IDs to the resource policy when you create an integration using the CloudTrail console. Refer to the [partner's documentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-integration.html#cloudtrail-lake-partner-information#lake-integration-partner-documentation) to learn how to get the AWS account numbers required for the policy.
+ For a solution integration, you must specify at least one AWS account ID as principal, and can optionally enter an external ID to prevent against confused deputy.
The following are requirements for the resource-based policy:
+ The policy contains at least one statement. The policy can have a maximum of 20 statements.
+ Each statement contains at least one principal. A principal is an account, user, role, or federated user. A statement can have a maximum of 50 principals.
+ The resource ARN defined in the policy must match the channel ARN the policy is attached to.
+ The policy contains only one action: `cloudtrail-data:PutAuditEvents`
The channel owner can call the `PutAuditEvents` API on the channel unless the policy denies the owner access to the resource.
**Topics**
+ [Example: Providing channel access to principals](#security_iam_resource-based-policy-examples-principals)
+ [Example: Using an external ID to prevent against confused deputy](#security_iam_resource-based-policy-examples-externalID)
### Example: Providing channel access to principals
The following example grants permissions to the principals with the ARNs `arn:aws:iam::111122223333:root`, `arn:aws:iam::444455556666:root`, and `arn:aws:iam::123456789012:root` to call the [PutAuditEvents](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API on the CloudTrail channel with the ARN `arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":
[
{
"Sid": "ChannelPolicy",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam::111122223333:root",
"arn:aws:iam::444455556666:root",
"arn:aws:iam::123456789012:root"
]
},
"Action": "cloudtrail-data:PutAuditEvents",
"Resource": "arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b"
}
]
}
```
------
### Example: Using an external ID to prevent against confused deputy
The following example uses an external ID to address and prevent against [confused deputy](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cross-service-confused-deputy-prevention.html). The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action.
The integration partner creates the external ID to use in the policy. Then, it provides the external ID to you as part of creating the integration. The value can be any unique string, such as a passphrase or account number.
The example grants permissions to the principals with the ARNs `arn:aws:iam::111122223333:root`, `arn:aws:iam::444455556666:root`, and `arn:aws:iam::123456789012:root` to call the [PutAuditEvents](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API on the CloudTrail channel resource if the call to the `PutAuditEvents` API includes the external ID value defined in the policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":
[
{
"Sid": "ChannelPolicy",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam::111122223333:root",
"arn:aws:iam::444455556666:root",
"arn:aws:iam::123456789012:root"
]
},
"Action": "cloudtrail-data:PutAuditEvents",
"Resource": "arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b"
}
]
}
```
------
## Resource-based policy examples for event data stores
Resource-based policies allow you to control which principals can perform actions on your event data store.
You can use resource-based policies to provide cross-account access to allow selected principals to query your event data store, list and cancel queries, and view query results.
For CloudTrail Lake dashboard, resource-based policies are used to allow CloudTrail to run queries on your event data stores to populate the data for the dashboard's widgets when the dashboard is refreshed. CloudTrail Lake gives you the option to attach a default resource-based policy to your event data stores when you [create a custom dashboard](lake-dashboard-custom.md) or [enable the Highlights dashboard](lake-dashboard-highlights.md) on the CloudTrail console.
The following actions are supported in resource-based policies for event data stores:
+ `cloudtrail:StartQuery`
+ `cloudtrail:CancelQuery`
+ `cloudtrail:ListQueries`
+ `cloudtrail:DescribeQuery`
+ `cloudtrail:GetQueryResults`
+ `cloudtrail:GenerateQuery`
+ `cloudtrail:GenerateQueryResultsSummary`
+ `cloudtrail:GetEventDataStore`
When you [create](query-event-data-store-cloudtrail.md#query-event-data-store-cloudtrail-procedure) or [update](query-event-data-store-update.md) an event data store, or manage dashboards on the CloudTrail console, you’re given the option to add a resource-based policy to your event data store. You can also run the [put-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/put-resource-policy.html) command to attach a resource-based policy to an event data store.
A resource-based policy consists of one or more statements. For example, it can include one statement that allows CloudTrail to query the event data store for a dashboard and another statement that allows cross-account access to query the event data store. You can [update](query-event-data-store-update.md) an existing event data store's resource-based policy from the event data store's details page on the CloudTrail console.
For [organization event data stores](cloudtrail-lake-organizations.md), CloudTrail creates a [default resource-based policy](cloudtrail-lake-organizations.md#cloudtrail-lake-organizations-eds-rbp) that lists the actions that the delegated administrator accounts are allowed to perform on organization event data stores. The permissions in this policy are derived from the delegated administrator permissions in AWS Organizations. This policy is updated automatically following changes to the organization event data store or to the organization (for example, a CloudTrail delegated administrator account is registered or removed).
**Topics**
+ [Example: Allow CloudTrail to run queries to refresh a dashboard](#security_iam_resource-based-policy-examples-eds-dashboard)
+ [Example: Allow other accounts to query an event data store and view query results](#security_iam_resource-based-policy-examples-eds-query)
### Example: Allow CloudTrail to run queries to refresh a dashboard
To populate the data on a CloudTrail Lake dashboard during a refresh, you need to allow CloudTrail to run queries on your behalf. To do this, attach a resource-based policy to each event data store associated with a dashboard widget that includes a statement that allows CloudTrail to perform the `StartQuery` operation to populate the data for the widget.
The following are the requirements for the statement:
+ The only `Principal` is `cloudtrail.amazonaws.com`.
+ The only `Action` allowed is `cloudtrail:StartQuery`.
+ The `Condition` only includes the dashboard ARN(s) and AWS account ID. For `AWS:SourceArn`, you can provide an array of dashboard ARNs.
The following example policy includes a statement that allows CloudTrail to run queries on an event data store for two custom dashboards named `example-dashboard1` and `example-dashboard2` and the Highlights dashboard named `AWSCloudTrail-Highlights` for account `123456789012`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":
[
{
"Effect": "Allow",
"Principal":
{
"Service": "cloudtrail.amazonaws.com"
},
"Action":
[
"cloudtrail:StartQuery"
],
"Resource": "arn:aws:cloudtrail:us-east-1:123456789012:dashboard/*",
"Condition": {
"StringLike": {
"AWS:SourceArn": [
"arn:aws:cloudtrail:us-east-1:123456789012:dashboard/example-dashboard1",
"arn:aws:cloudtrail:us-east-1:123456789012:dashboard/example-dashboard2",
"arn:aws:cloudtrail:us-east-1:123456789012:dashboard/AWSCloudTrail-Highlights"
],
"AWS:SourceAccount": "123456789012"
}
}
}
]
}
```
------
### Example: Allow other accounts to query an event data store and view query results
You can use resource-based policies to provide cross-account access to your event data stores to allow other accounts to run queries on your event data stores.
The following example policy includes a statement that allows root users in accounts `111122223333`, `777777777777`, `999999999999`, and `111111111111` to run queries and get query results on the event data store owned by account ID `555555555555`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "policy1",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::777777777777:root",
"arn:aws:iam::999999999999:root",
"arn:aws:iam::111111111111:root"
]
},
"Action": [
"cloudtrail:StartQuery",
"cloudtrail:GetEventDataStore",
"cloudtrail:GetQueryResults"
],
"Resource": "arn:aws:cloudtrail:us-east-1:555555555555:eventdatastore/example80-699f-4045-a7d2-730dbf313ccf"
}
]
}
```
------
## Resource-based policy example for a dashboard
You can set a refresh schedule for a CloudTrail Lake dashboard, which allows CloudTrail to refresh the dashboard on your behalf at the interval you define when you set the refresh schedule. To do this, you need to attach a resource-based policy to the dashboard to allow CloudTrail to perform the `StartDashboardRefresh` operation on your dashboard.
The following are requirements for the resource-based policy:
+ The only `Principal` is `cloudtrail.amazonaws.com`.
+ The only `Action` allowed in the policy is `cloudtrail:StartDashboardRefresh`.
+ The `Condition` only includes the dashboard ARN and AWS account ID.
The following example policy allows CloudTrail to refresh a dashboard named `exampleDash` for account `123456789012`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":
[
{
"Effect": "Allow",
"Principal":
{
"Service": "cloudtrail.amazonaws.com"
},
"Action":
[
"cloudtrail:StartDashboardRefresh"
],
"Resource": "arn:aws:cloudtrail:us-east-1:123456789012:dashboard/*",
"Condition": {
"StringEquals": {
"AWS:SourceArn": "arn:aws:cloudtrail:us-east-1:123456789012:dashboard/exampleDash",
"AWS:SourceAccount":"123456789012"
}
}
}
]
}
```
------
# Amazon S3 bucket policy for CloudTrail
By default, Amazon S3 buckets and objects are private. Only the resource owner (the AWS account that created the bucket) can access the bucket and objects it contains. The resource owner can grant access permissions to other resources and users by writing an access policy.
To create or modify an Amazon S3 bucket to receive log files for an organization trail, you must change the bucket policy. For more information, see [Creating a trail for an organization with the AWS CLI](cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli.md).
To deliver log files to an S3 bucket, CloudTrail must have the required permissions, and it cannot be configured as a [Requester Pays](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) bucket.
CloudTrail adds the following fields in the policy for you:
+ The allowed SIDs
+ The bucket name
+ The service principal name for CloudTrail
+ The name of the folder where the log files are stored, including the bucket name, a prefix (if you specified one), and your AWS account ID
As a security best practice, add an `aws:SourceArn` condition key to the Amazon S3 bucket policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail writes to the S3 bucket only for a specific trail or trails. The value of `aws:SourceArn` is always the ARN of the trail (or array of trail ARNs) that is using the bucket to store logs. Be sure to add the `aws:SourceArn` condition key to S3 bucket policies for existing trails.
**Note**
If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail.
The following policy allows CloudTrail to write log files to the bucket from supported AWS Regions. Replace *amzn-s3-demo-bucket*, *[optionalPrefix]/*, *myAccountID*, *region*, and *trailName* with the appropriate values for your configuration.
**S3 bucket policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailAclCheck20150319",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:trail/trailName"
}
}
},
{
"Sid": "AWSCloudTrailWrite20150319",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/[optionalPrefix]/AWSLogs/myAccountID/*",
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:trail/trailName"
}
}
}
]
}
```
------
For more information about AWS Regions, see [CloudTrail supported Regions](cloudtrail-supported-regions.md).
**Contents**
+ [Specifying an existing bucket for CloudTrail log delivery](#specify-an-existing-bucket-for-cloudtrail-log-delivery)
+ [Receiving log files from other accounts](#aggregration-option)
+ [Create or update an Amazon S3 bucket to use to store the log files for an organization trail](#org-trail-bucket-policy)
+ [Troubleshooting the Amazon S3 bucket policy](#troubleshooting-s3-bucket-policy)
+ [Common Amazon S3 policy configuration errors](#s3-bucket-policy-for-multiple-regions)
+ [Changing a prefix for an existing bucket](#cloudtrail-add-change-or-remove-a-bucket-prefix)
+ [Additional resources](#cloudtrail-S3-bucket-policy-resources)
## Specifying an existing bucket for CloudTrail log delivery
If you specified an existing S3 bucket as the storage location for log file delivery, you must attach a policy to the bucket that allows CloudTrail to write to the bucket.
**Note**
As a best practice, use a dedicated S3 bucket for CloudTrail logs.
**To add the required CloudTrail policy to an Amazon S3 bucket**
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose the bucket where you want CloudTrail to deliver your log files, and then choose **Permissions**.
1. Choose **Edit**.
1. Copy the [S3 bucket policy](#s3-bucket-policy) to the **Bucket Policy Editor** window. Replace the placeholders in italics with the names of your bucket, prefix, and account number. If you specified a prefix when you created your trail, include it here. The prefix is an optional addition to the S3 object key that creates a folder-like organization in your bucket.
**Note**
If the existing bucket already has one or more policies attached, add the statements for CloudTrail access to that policy or policies. Evaluate the resulting set of permissions to be sure that they are appropriate for the users who will access the bucket.
## Receiving log files from other accounts
You can configure CloudTrail to deliver log files from multiple AWS accounts to a single S3 bucket. For more information, see [Receiving CloudTrail log files from multiple accountsRedacting bucket owner account IDs for data events called by other accounts](cloudtrail-receive-logs-from-multiple-accounts.md).
## Create or update an Amazon S3 bucket to use to store the log files for an organization trail
You must specify an Amazon S3 bucket to receive the log files for an organization trail. This bucket must have a policy that allows CloudTrail to put the log files for the organization into the bucket.
The following is an example policy for an Amazon S3 bucket named *amzn-s3-demo-bucket*, which is owned by the organization's management account. Replace *amzn-s3-demo-bucket*, *region*, *managementAccountID*, *trailName*, and *o-organizationID* with the values for your organization
This bucket policy contains three statements.
+ The first statement allows CloudTrail to call the Amazon S3 `GetBucketAcl` action on the Amazon S3 bucket.
+ The second statement allows logging in the event the trail is changed from an organization trail to a trail for that account only.
+ The third statement allows logging for an organization trail.
The example policy includes an `aws:SourceArn` condition key for the Amazon S3 bucket policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail writes to the S3 bucket only for a specific trail or trails. In an organization trail, the value of `aws:SourceArn` must be a trail ARN that is owned by the management account, and uses the management account ID.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailAclCheck20150319",
"Effect": "Allow",
"Principal": {
"Service": [
"cloudtrail.amazonaws.com"
]
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
}
}
},
{
"Sid": "AWSCloudTrailWrite20150319",
"Effect": "Allow",
"Principal": {
"Service": [
"cloudtrail.amazonaws.com"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/AWSLogs/managementAccountID/*",
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
}
}
},
{
"Sid": "AWSCloudTrailOrganizationWrite20150319",
"Effect": "Allow",
"Principal": {
"Service": [
"cloudtrail.amazonaws.com"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/AWSLogs/o-organizationID/*",
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceArn": "arn:aws:cloudtrail:region:managementAccountID:trail/trailName"
}
}
}
]
}
```
------
This example policy does not allow any users from member accounts to access the log files created for the organization. By default, organization log files are accessible only to the management account. For information about how to allow read access to the Amazon S3 bucket for IAM users in member accounts, see [Sharing CloudTrail log files between AWS accounts](cloudtrail-sharing-logs.md).
## Troubleshooting the Amazon S3 bucket policy
The following sections describe how to troubleshoot the S3 bucket policy.
**Note**
If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail.
### Common Amazon S3 policy configuration errors
When you create a new bucket as part of creating or updating a trail, CloudTrail attaches the required permissions to your bucket. The bucket policy uses the service principal name, `"cloudtrail.amazonaws.com"`, which allows CloudTrail to deliver logs for all Regions.
If CloudTrail is not delivering logs for a Region, it's possible that your bucket has an older policy that specifies CloudTrail account IDs for each Region. This policy gives CloudTrail permission to deliver logs only for the Regions specified.
As a best practice, update the policy to use a permission with the CloudTrail service principal. To do this, replace the account ID ARNs with the service principal name: `"cloudtrail.amazonaws.com"`. This gives CloudTrail permission to deliver logs for current and new Regions. As a security best practice, add an `aws:SourceArn` or `aws:SourceAccount` condition key to the Amazon S3 bucket policy. This helps prevent unauthorized account access to your S3 bucket. If you have existing trails, be sure to add one or more condition keys. The following example shows a recommended policy configuration. Replace *amzn-s3-demo-bucket*, *[optionalPrefix]/*, *myAccountID*, *region*, and *trailName* with the appropriate values for your configuration.
**Example bucket policy with service principal name**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailAclCheck20150319",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:trail/trailName"
}
}
},
{
"Sid": "AWSCloudTrailWrite20150319",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/[optionalPrefix]/AWSLogs/myAccountID/*",
"Condition": {"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceArn": "arn:aws:cloudtrail:region:myAccountID:trail/trailName"
}
}
}
]
}
```
### Changing a prefix for an existing bucket
If you try to add, modify, or remove a log file prefix for an S3 bucket that receives logs from a trail, you might see the error: **There is a problem with the bucket policy**. A bucket policy with an incorrect prefix can prevent your trail from delivering logs to the bucket. To resolve this issue, use the Amazon S3 console to update the prefix in the bucket policy, and then use the CloudTrail console to specify the same prefix for the bucket in the trail.
**To update the log file prefix for an Amazon S3 bucket**
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose the bucket for which you want to modify the prefix, and then choose **Permissions**.
1. Choose **Edit**.
1. In the bucket policy, under the `s3:PutObject` action, edit the `Resource` entry to add, modify, or remove the log file *prefix/* as needed.
```
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/AWSLogs/myAccountID/*",
```
1. Choose **Save**.
1. Open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. Choose your trail and for **Storage location**, click the pencil icon to edit the settings for your bucket.
1. For **S3 bucket**, choose the bucket with the prefix you are changing.
1. For **Log file prefix**, update the prefix to match the prefix that you entered in the bucket policy.
1. Choose **Save**.
## Additional resources
For more information about S3 buckets and policies, see [Using bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) in the *Amazon Simple Storage Service User Guide*.
# Amazon S3 bucket policy for CloudTrail Lake query results
By default, Amazon S3 buckets and objects are private. Only the resource owner (the AWS account that created the bucket) can access the bucket and objects it contains. The resource owner can grant access permissions to other resources and users by writing an access policy.
To deliver CloudTrail Lake query results to an S3 bucket, CloudTrail must have the required permissions, and it cannot be configured as a [Requester Pays](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) bucket.
CloudTrail adds the following fields in the policy for you:
+ The allowed SIDs
+ The bucket name
+ The service principal name for CloudTrail
As a security best practice, add an `aws:SourceArn` condition key to the Amazon S3 bucket policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail writes to the S3 bucket only for the event data store.
The following policy allows CloudTrail to deliver query results to the bucket from supported AWS Regions. Replace *amzn-s3-demo-bucket*, *myAccountID*, and *myQueryRunningRegion* with the appropriate values for your configuration. The *myAccountID* is the AWS account ID used for CloudTrail, which may not be the same as the AWS account ID for the S3 bucket.
**Note**
If your bucket policy includes a statement for a KMS key, we recommend using a fully qualified KMS key ARN. If you use a KMS key alias instead, AWS KMS resolves the key within the requester’s account. This behavior can result in data that's encrypted with a KMS key that belongs to the requester, and not the bucket owner.
If this is an organization event data store, the event data store ARN must include the AWS account ID for the management account. This is because the management account maintains ownership of all organization resources.
**S3 bucket policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailLake1",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": [
"s3:PutObject*",
"s3:Abort*"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
],
"Condition": {
"StringEquals": {
"aws:sourceAccount": "111111111111"
},
"ArnLike": {
"aws:sourceArn": "arn:aws:cloudtrail:us-east-1:111111111111:eventdatastore/*"
}
}
},
{
"Sid": "AWSCloudTrailLake2",
"Effect": "Allow",
"Principal": {"Service":"cloudtrail.amazonaws.com"},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
"Condition": {
"StringEquals": {
"aws:sourceAccount": "111111111111"
},
"ArnLike": {
"aws:sourceArn": "arn:aws:cloudtrail:us-east-1:111111111111:eventdatastore/*"
}
}
}
]
}
```
------
**Contents**
+ [Specifying an existing bucket for CloudTrail Lake query results](#specify-an-existing-bucket-for-cloudtrail-query-results-delivery)
+ [Additional resources](#cloudtrail-lake-S3-bucket-policy-resources)
## Specifying an existing bucket for CloudTrail Lake query results
If you specified an existing S3 bucket as the storage location for CloudTrail Lake query results delivery, you must attach a policy to the bucket that allows CloudTrail to deliver the query results to the bucket.
**Note**
As a best practice, use a dedicated S3 bucket for CloudTrail Lake query results.
**To add the required CloudTrail policy to an Amazon S3 bucket**
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose the bucket where you want CloudTrail to deliver your Lake query results, and then choose **Permissions**.
1. Choose **Edit**.
1. Copy the [S3 bucket policy for query results](#s3-bucket-policy-lake-query) to the **Bucket Policy Editor** window. Replace the placeholders in italics with the names of your bucket, Region, and account ID.
**Note**
If the existing bucket already has one or more policies attached, add the statements for CloudTrail access to that policy or policies. Evaluate the resulting set of permissions to be sure that they are appropriate for the users who access the bucket.
## Additional resources
For more information about S3 buckets and policies, see [Using bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) in the *Amazon Simple Storage Service User Guide*.
# Amazon SNS topic policy for CloudTrail
To send notifications to an SNS topic, CloudTrail must have the required permissions. CloudTrail automatically attaches the required permissions to the topic when you create an Amazon SNS topic as part of creating or updating a trail in the CloudTrail console.
**Important**
As a security best practice, to restrict access to your SNS topic, we strongly recommend that after you create or update a trail to send SNS notifications, you manually edit the IAM policy that is attached to the SNS topic to add condition keys. For more information, see [Security best practice for SNS topic policy](#cloudtrail-sns-notifications-policy-security) in this topic.
CloudTrail adds the following statement to the policy for you with the following fields:
+ The allowed SIDs.
+ The service principal name for CloudTrail.
+ The SNS topic, including Region, account ID, and topic name.
The following policy allows CloudTrail to send notifications about log file delivery from supported Regions. For more information, see [CloudTrail supported Regions](cloudtrail-supported-regions.md). This is the default policy that is attached to a new or existing SNS topic policy when you create or update a trail, and choose to enable SNS notifications.
**SNS topic policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailSNSPolicy20131101",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-east-1:111111111111:SNSTopicName"
}
]
}
```
------
To use an AWS KMS-encrypted Amazon SNS topic to send notifications, you must also enable compatibility between the event source (CloudTrail) and the encrypted topic by adding the following statement to the policy of the AWS KMS key.
**KMS key policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey*",
"kms:Decrypt"
],
"Resource": "*"
}
]
}
```
------
For more information, see [Enable Compatibility between Event Sources from AWS Services and Encrypted Topics](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html#compatibility-with-aws-services).
**Contents**
+ [Security best practice for SNS topic policy](#cloudtrail-sns-notifications-policy-security)
+ [Specifying an existing topic for sending notifications](#specifying-an-existing-topic-for-sns-notifications)
+ [Troubleshooting the SNS topic policy](#troubleshooting-sns-topic-policy)
+ [CloudTrail is not sending notifications for a Region](#sns-topic-policy-for-multiple-regions)
+ [CloudTrail is not sending notifications for a member account in an organization](#sns-topic-policy-authorization-failure)
+ [Additional resources](#cloudtrail-notifications-more-info-5)
## Security best practice for SNS topic policy
By default, the IAM policy statement that CloudTrail attaches to your Amazon SNS topic allows the CloudTrail service principal to publish to an SNS topic, identified by an ARN. To help prevent an attacker from gaining access to your SNS topic, and sending notifications on behalf of CloudTrail to topic recipients, manually edit your CloudTrail SNS topic policy to add an `aws:SourceArn` condition key to the policy statement attached by CloudTrail. The value of this key is the ARN of the trail, or an array of trail ARNs that are using the SNS topic. Because it includes both the specific trail ID and the ID of the account that owns the trail, it restricts SNS topic access to only those accounts that have permission to manage the trail. Before you add condition keys to your SNS topic policy, get the SNS topic name from your trail's settings in the CloudTrail console.
The `aws:SourceAccount` condition key is also supported, but is not recommended.
**To add the `aws:SourceArn` condition key to your SNS topic policy**
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. In the navigation pane, choose **Topics**.
1. Choose the SNS topic that is shown in your trail settings, and then choose **Edit**.
1. Expand **Access policy**.
1. In the **Access policy** JSON editor, look for a block that resembles the following example.
```
{
"Sid": "AWSCloudTrailSNSPolicy20150319",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-west-2:111122223333:aws-cloudtrail-logs-111122223333-61bbe496"
}
```
1. Add a new block for a condition, `aws:SourceArn`, as shown in the following example. The value of `aws:SourceArn` is the ARN of the trail about which you are sending notifications to SNS.
```
{
"Sid": "AWSCloudTrailSNSPolicy20150319",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-west-2:111122223333:aws-cloudtrail-logs-111122223333-61bbe496",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:us-west-2:123456789012:trail/Trail3"
}
}
}
```
1. When you are finished editing the SNS topic policy, choose **Save changes**.
**To add the `aws:SourceAccount` condition key to your SNS topic policy**
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. In the navigation pane, choose **Topics**.
1. Choose the SNS topic that is shown in your trail settings, and then choose **Edit**.
1. Expand **Access policy**.
1. In the **Access policy** JSON editor, look for a block that resembles the following example.
```
{
"Sid": "AWSCloudTrailSNSPolicy20150319",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-west-2:111122223333:aws-cloudtrail-logs-111122223333-61bbe496"
}
```
1. Add a new block for a condition, `aws:SourceAccount`, as shown in the following example. The value of `aws:SourceAccount` is the ID of the account that owns the CloudTrail trail. This example restricts access to the SNS topic to only those users who can sign in to the AWS account 123456789012.
```
{
"Sid": "AWSCloudTrailSNSPolicy20150319",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-west-2:111122223333:aws-cloudtrail-logs-111122223333-61bbe496",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
```
1. When you are finished editing the SNS topic policy, choose **Save changes**.
## Specifying an existing topic for sending notifications
You can manually add the permissions for an Amazon SNS topic to your topic policy in the Amazon SNS console and then specify the topic in the CloudTrail console.
**To manually update an SNS topic policy**
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. Choose **Topics** and then choose the topic.
1. Choose **Edit** and then scroll down to **Access policy**.
1. Add the statement from [SNS topic policy](#sns-topic-policy) with the appropriate values for the Region, account ID, and topic name.
1. If your topic is an encrypted topic, you must allow CloudTrail to have `kms:GenerateDataKey*` and the `kms:Decrypt` permissions. For more information, see [Encrypted SNS topic KMS key policy](#kms-key-policy).
1. Choose **Save changes**.
1. Return to the CloudTrail console and specify the topic for the trail.
## Troubleshooting the SNS topic policy
The following sections describe how to troubleshoot the SNS topic policy.
**Topics**
+ [CloudTrail is not sending notifications for a Region](#sns-topic-policy-for-multiple-regions)
+ [CloudTrail is not sending notifications for a member account in an organization](#sns-topic-policy-authorization-failure)
### CloudTrail is not sending notifications for a Region
When you create a new topic as part of creating or updating a trail, CloudTrail attaches the required permissions to your topic. The topic policy uses the service principal name, `"cloudtrail.amazonaws.com"`, which allows CloudTrail to send notifications for all Regions.
If CloudTrail is not sending notifications for a Region, it's possible that your topic has an older policy that specifies CloudTrail account IDs for each Region. This type of policy gives CloudTrail permission to send notifications only for the Regions specified.
As a best practice, update the policy to use a permission with the CloudTrail service principal. To do this, replace the account ID ARNs with the service principal name: `"cloudtrail.amazonaws.com"`.
The following example policy gives CloudTrail permission to send notifications for current and new Regions:
**Example topic policy with service principal name**
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "AWSCloudTrailSNSPolicy20131101",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "SNS:Publish",
"Resource": "arn:aws:sns:us-west-2:123456789012:myTopic"
}]
}
```
Verify that the policy has the correct values:
+ In the `Resource` field, specify the account number of the topic owner. For topics that you create, specify your account number.
+ Specify the appropriate values for the Region and SNS topic name.
### CloudTrail is not sending notifications for a member account in an organization
When a member account with an AWS Organizations organization trail is not sending Amazon SNS notifications, there could be an issue with the configuration of the SNS topic policy. CloudTrail creates organization trails in member accounts even if a resource validation fails, for example, the organization trail's SNS topic does not include all member account IDs. If the SNS topic policy is incorrect, an authorization failure occurs.
To check whether a trail's SNS topic policy has an authorization failure:
+ From the CloudTrail console, check the trail's details page. If there's an authorization failure, the details page includes a warning `SNS authorization failed` and indicates to fix the SNS topic policy.
+ From the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-trail-status.html) command. If there's an authorization failure, the command output includes the `LastNotificationError` field with a value of `AuthorizationError`.
## Additional resources
For more information about SNS topics and subscribing to them, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/).
# Troubleshooting AWS CloudTrail identity and access
Use the following information to help you diagnose and fix common issues that you might encounter when working with CloudTrail and IAM.
**Topics**
+ [I am not authorized to perform an action in CloudTrail](#security_iam_troubleshoot-no-permissions)
+ [I am not authorized to perform `iam:PassRole`](#security_iam_troubleshoot-passrole)
+ [I want to allow people outside of my AWS account to access my CloudTrail resources](#security_iam_troubleshoot-cross-account-access)
+ [I am not authorized to perform `iam:PassRole`](#security_iam_troubleshoot-passrole)
+ [I am getting a `NoManagementAccountSLRExistsException` exception when I try to create an organization trail or event data store](#security_iam_troubleshoot-no-slr)
## I am not authorized to perform an action in CloudTrail
If you receive an error that you're not authorized to perform an action, your policies must be updated to allow you to perform the action.
The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a fictional `my-example-widget` resource but doesn't have the fictional `cloudtrail:GetWidget` permissions.
```
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: cloudtrail:GetWidget on resource: my-example-widget
```
In this case, the policy for the `mateojackson` user must be updated to allow access to the `my-example-widget` resource by using the `cloudtrail:GetWidget` action.
If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.
If the AWS Management Console tells you that you're not authorized to perform an action, then you must contact your administrator for assistance. Your administrator is the person that provided you with your sign-in credentials.
The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a trail but doesn't have either the appropriate CloudTrail managed policy (**AWSCloudTrail\$1FullAccess** or **AWSCloudTrail\$1ReadOnlyAccess**) or the equivalent permissions applied to his account.
```
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: cloudtrail:GetTrailStatus on resource: My-Trail
```
In this case, Mateo asks his administrator to update his policies to allow him to access trail information and status in the console.
If you sign in with an IAM user or role that has the **AWSCloudTrail\$1FullAccess** managed policy or its equivalent permissions, and you can't configure AWS Config or Amazon CloudWatch Logs integration with a trail, you might be missing the required permissions for integration with those services. For more information, see [Granting permission to view AWS Config information on the CloudTrail console](security_iam_id-based-policy-examples.md#grant-aws-config-permissions-for-cloudtrail-users) and [Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console](security_iam_id-based-policy-examples.md#grant-cloudwatch-permissions-for-cloudtrail-users).
## I am not authorized to perform `iam:PassRole`
If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to CloudTrail.
Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service.
The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in CloudTrail. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service.
```
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
```
In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action.
If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.
## I want to allow people outside of my AWS account to access my CloudTrail resources
You can create a role and share CloudTrail information between multiple AWS accounts. For more information, see [Sharing CloudTrail log files between AWS accounts](cloudtrail-sharing-logs.md).
You can create a role that users in other accounts or people outside of your organization can use to access your resources. You can specify who is trusted to assume the role. For services that support resource-based policies or access control lists (ACLs), you can use those policies to grant people access to your resources.
To learn more, consult the following:
+ To learn whether CloudTrail supports these features, see [How AWS CloudTrail works with IAM](security_iam_service-with-iam.md).
+ To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*.
+ To learn how to provide access to your resources to third-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*.
+ To learn how to provide access through identity federation, see [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*.
+ To learn the difference between using roles and resource-based policies for cross-account access, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*.
## I am not authorized to perform `iam:PassRole`
If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to CloudTrail.
Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service.
The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in CloudTrail. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service.
```
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
```
In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action.
If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials.
## I am getting a `NoManagementAccountSLRExistsException` exception when I try to create an organization trail or event data store
The `NoManagementAccountSLRExistsException` exception is thrown when the management account does not have a service-linked role.
When you add a delegated administrator using the AWS Organizations CLI or API operation, CloudTrail service-linked roles won't be created automatically if they don't exist. The service-linked roles are only created when you make a call from the management account directly to the CloudTrail service. For example, when you add a delegated administrator or create an organization trail or event data store using the CloudTrail console, AWS CLI or CloudTrail API, the AWSServiceRoleForCloudTrail service-linked role is created.
When you add a delegated administrator using the AWS CloudTrail; CLI or API operation, CloudTrail will create both the AWSServiceRoleForCloudTrail and the AWSServiceRoleForCloudTrailEventContext service-linked roles.
When you use your organization's management account to add a delegated administrator or create an organization trail or event data store in the CloudTrail console, or by using the AWS CLI or CloudTrail API, CloudTrail automatically creates the AWSServiceRoleForCloudTrail service-linked role for your management account if it does not already exist. For more information, see [Using service-linked roles for CloudTrail](using-service-linked-roles.md).
If you haven't added a delegated administrator, use the CloudTrail console, AWS CLI or CloudTrail API to add the delegated administrator. For more information about adding a delegated administrator, see [Add a CloudTrail delegated administrator](cloudtrail-add-delegated-administrator.md) and [RegisterOrganizationDelegatedAdmin](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_RegisterOrganizationDelegatedAdmin.html) (API).
If you've already added the delegated administrator, use the management account to create the organization trail or event data store in the CloudTrail console, or by using the AWS CLI or CloudTrail API. For more information about creating an organization trail, see [Creating a trail for your organization in the console](creating-an-organizational-trail-in-the-console.md), [Creating a trail for an organization with the AWS CLI](cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli.md), and [CreateTrail](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_CreateTrail.html) (API).
# Using service-linked roles for CloudTrail
AWS CloudTrail uses AWS Identity and Access Management (IAM) [ service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to CloudTrail. Service-linked roles are predefined by CloudTrail and include all the permissions that the service requires to call other AWS services on your behalf.
**Topics**
+ [Using roles for creating and managing CloudTrail organization trails and CloudTrail Lake organization event data stores in CloudTrail](using-service-linked-roles-create-slr-for-org-trails.md)
+ [Supported Regions for CloudTrail service-linked roles](#slr-regions-create-slr-for-org-trails)
+ [Using roles for creating and managing CloudTrail event context in CloudTrail](using-service-linked-roles-create-slr-for-context-management.md)
+ [Supported Regions for CloudTrail service-linked roles](#slr-regions-create-slr-for-context-management)
# Using roles for creating and managing CloudTrail organization trails and CloudTrail Lake organization event data stores in CloudTrail
AWS CloudTrail uses AWS Identity and Access Management (IAM) [service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to CloudTrail. Service-linked roles are predefined by CloudTrail and include all the permissions that the service requires to call other AWS services on your behalf.
A service-linked role makes setting up CloudTrail easier because you don’t have to manually add the necessary permissions. CloudTrail defines the permissions of its service-linked roles, and unless defined otherwise, only CloudTrail can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity.
You can delete a service-linked role only after first deleting their related resources. This protects your CloudTrail resources because you can't inadvertently remove permission to access the resources.
For information about other services that support service-linked roles, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) and look for the services that have **Yes** in the **Service-linked roles** column. Choose a **Yes** with a link to view the service-linked role documentation for that service.
## Service-linked role permissions for CloudTrail
CloudTrail uses the service-linked role named **AWSServiceRoleForCloudTrail** – This service linked role is used for supporting organization trails and organization event data stores.
The AWSServiceRoleForCloudTrail service-linked role trusts the following services to assume the role:
+ `cloudtrail.amazonaws.com`
The role permissions policy named CloudTrailServiceRolePolicy allows CloudTrail to complete the following actions on the specified resources:
+ Actions on all CloudTrail resources:
+ `All`
+ Actions on all AWS Organizations resources:
+ `organizations:DescribeAccount`
+ `organizations:DescribeOrganization`
+ `organizations:ListAccounts`
+ `organizations:ListAWSServiceAccessForOrganization`
+ Actions on all Organizations resources for the CloudTrail service principal to list the delegated administrators for the organization:
+ `organizations:ListDelegatedAdministrators`
+ Actions for [disabling Lake federation](query-disable-federation.md) on an organization event data store:
+ `glue:DeleteTable`
+ `lakeformation:DeRegisterResource`
You must configure permissions to allow your users, groups, or roles to create, edit, or delete a service-linked role. For more information, see [Service-linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*.
For more information about the managed policy associated with AWSServiceRoleForCloudTrail, see [AWS managed policies for AWS CloudTrail](security-iam-awsmanpol.md).
## Creating a service-linked role for CloudTrail
You don't need to manually create a service-linked role. When you create an organization trail or organization event data store, or add a delegated administrator in the CloudTrail console, in the AWS Management Console, the AWS CLI, or the AWS API, CloudTrail creates the service-linked role for you.
If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you create an organization trail or organization event data store, or add a delegated administrator in the CloudTrail console,, CloudTrail creates the service-linked role for you again.
## Editing a service-linked role for CloudTrail
CloudTrail does not allow you to edit the AWSServiceRoleForCloudTrail service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*.
## Deleting a service-linked role for CloudTrail
You don't need to manually delete the AWSServiceRoleForCloudTrail role. If an AWS account is removed from an Organizations organization, the AWSServiceRoleForCloudTrail role is automatically removed from that AWS account. You cannot detach or remove policies from the AWSServiceRoleForCloudTrail service-linked role in an organization management account without removing the account from the organization.
You can also use the IAM console, the AWS CLI or the AWS API to manually delete the service-linked role. To do this, you must first manually clean up the resources for your service-linked role, and then you can manually delete it.
**Note**
If the CloudTrail service is using the role when you try to delete the resources, then deletion might fail. If that happens, wait for a few minutes and try the operation again.
To remove a resource being used by the AWSServiceRoleForCloudTrail role, you can do one of the following:
+ Remove the AWS account from the organization in Organizations.
+ Update the trail so that it is no longer an organization trail. For more information, see [Updating a trail with the CloudTrail console](cloudtrail-update-a-trail-console.md).
+ Update the event data store so that it is no longer an organization event data store. For more information, see [Update an event data store with the console](query-event-data-store-update.md).
+ Delete the trail. For more information, see [Deleting a trail with the CloudTrail console](cloudtrail-delete-trails-console.md).
+ Delete the event data store. For more information, see [Delete an event data store with the console](query-event-data-store-delete.md).
**To manually delete the service-linked role using IAM**
Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForCloudTrail service-linked role. For more information, see [Deleting a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.
## Supported Regions for CloudTrail service-linked roles
CloudTrail supports using service-linked roles in all of the AWS Regions where CloudTrail and Organizations are both available. For more information, see [AWS Regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the *AWS General Reference*.
# Using roles for creating and managing CloudTrail event context in CloudTrail
AWS CloudTrail uses AWS Identity and Access Management (IAM) [service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). A service-linked role is a unique type of IAM role that is linked directly to CloudTrail. Service-linked roles are predefined by CloudTrail and include all the permissions that the service requires to call other AWS services on your behalf.
A service-linked role makes setting up CloudTrail easier because you don’t have to manually add the necessary permissions. CloudTrail defines the permissions of its service-linked roles, and unless defined otherwise, only CloudTrail can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity.
You can delete a service-linked role only after first deleting their related resources. This protects your CloudTrail resources because you can't inadvertently remove permission to access the resources.
For information about other services that support service-linked roles, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) and look for the services that have **Yes** in the **Service-linked roles** column. Choose a **Yes** with a link to view the service-linked role documentation for that service.
## Service-linked role permissions for CloudTrail
CloudTrail uses the service-linked role named **AWSServiceRoleForCloudTrailEventContext** – This service linked role is used for managing CloudTrail Event Context and EventBridge rules.
The AWSServiceRoleForCloudTrailEventContext service-linked role trusts the following services to assume the role:
+ `context.cloudtrail.amazonaws.com`
The role permissions policy named CloudTrailEventContext allows CloudTrail to complete the following actions on the specified resources:
+ Actions on resource tags:
+ `tag:GetResources`
+ Actions on all Amazon EventBridge resources for the CloudTrail service principal to create rules:
+ `events:PutRule`
+ Actions on all Amazon EventBridge resources for the CloudTrail service principal to manage the rules it creates:
+ `events:PutTargets`
+ `events:DeleteRule`
+ `events:RemoveTargets`
+ `events:RemoveTargets`
+ Actions on all Amazon EventBridge resources for the CloudTrail service principal to describe the rules it creates:
+ `events:DescribeRule`
+ `events:DeRegisterResource`
+ Actions on all Amazon EventBridge resources:
+ `events:ListRules`
You must configure permissions to allow your users, groups, or roles to create, edit, or delete a service-linked role. For more information, see [Service-linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*.
For more information about the managed policy associated with AWSServiceRoleForCloudTrailEventContext, see [AWS managed policies for AWS CloudTrail](security-iam-awsmanpol.md).
## Creating a service-linked role for CloudTrail
You don't need to manually create a service-linked role. When you begin using the context event feature in the AWS Management Console, the AWS CLI, or the AWS API, CloudTrail creates the service-linked role for you.
If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you begin using the context event feature, CloudTrail creates the service-linked role for you again.
## Editing a service-linked role for CloudTrail
CloudTrail does not allow you to edit the AWSServiceRoleForCloudTrailEventContext service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Editing a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*.
## Deleting the AWSServiceRoleForCloudTrailEventContext service-linked role for CloudTrail
If you no longer need to use a feature or service that requires the AWSServiceRoleForCloudTrailEventContext service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or maintained. However, you must clean up the resources for your service-linked role before you can manually delete it by removing the TagContext key from event data stores.
**Note**
If the CloudTrail service is using the role when you try to delete the resources, then the deletion might fail. If that happens, wait for a few minutes and try the operation again.
**To delete CloudTrail resources used by the AWSServiceRoleForCloudTrailEventContext service linked role**
1. At the terminal or command line, run the **put-event-configuration** command for the event store from which you want to remove the `TagContext` key. For example, to remove the `TagContext` key from an event store in the *111122223333* account in the US East (Ohio) Region with an ARN of *arn:aws:cloudtrail:us-east-2:111122223333:eventdatastore/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111* where `TagContext` is the only context key selector, you would use the **put-event-configuration** command with no value specified for `--context-key-selectors`:
```
aws cloudtrail put-event-configuration --event-data-store arn:aws:cloudtrail:us-east-2:111122223333:eventdatastore/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 --max-event-size Large --context-key-selectors
```
1. Repeat this command for every data store in every Region in the partition. For more information, see [Identify AWS resources with Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html).
**To manually delete the service-linked role using IAM**
Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForCloudTrailEventContext service-linked role. For more information, see [Deleting a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.
## Supported Regions for CloudTrail service-linked roles
CloudTrail supports using service-linked roles in all of the Regions where CloudTrail and EventBridge are available. For more information, see [AWS Regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html).
# AWS managed policies for AWS CloudTrail
To add permissions to users, groups, and roles, it is easier to use AWS managed policies than to write policies yourself. It takes time and expertise to [create IAM customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) that provide your team with only the permissions they need. To get started quickly, you can use AWS managed policies. These policies cover common use cases and are available in your AWS account. For more information about AWS managed policies, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*.
AWS services maintain and update AWS managed policies. You can't change the permissions in AWS managed policies. Services occasionally add additional permissions to an AWS managed policy to support new features. This type of update affects all identities (users, groups, and roles) where the policy is attached. Services are most likely to update an AWS managed policy when a new feature is launched or when new operations become available. Services do not remove permissions from an AWS managed policy, so policy updates won't break your existing permissions.
Additionally, AWS supports managed policies for job functions that span multiple services. For example, the **ReadOnlyAccess** AWS managed policy provides read-only access to all AWS services and resources. When a service launches a new feature, AWS adds read-only permissions for new operations and resources. For a list and descriptions of job function policies, see [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*.
## AWS managed policy: `AWSCloudTrail_FullAccess`
A user identity that has the [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) policy attached to its role has full administrative access in CloudTrail.
For a JSON listing of the policy details, see [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_FullAccess.html) in the *AWS Managed Policy reference guide*.
## AWS managed policy: `AWSCloudTrail_ReadOnlyAccess`
A user identity that has the [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html) policy attached to its role can perform read-only actions in CloudTrail, such as `Get*`, `List*`, and `Describe*` actions on trails, CloudTrail Lake event data stores, or Lake queries.
For a JSON listing of the policy details, see [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCloudTrail_ReadOnlyAccess.html) in the *AWS Managed Policy reference guide*.
## AWS managed policy: `AWSServiceRoleForCloudTrail`
The [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailServiceRolePolicy.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailServiceRolePolicy.html) policy allows AWS CloudTrail to perform actions on organization trails and organization event data stores on your behalf. The policy includes required AWS Organizations permissions for describing and listing the organization accounts and delegated administrators in an AWS Organizations organization.
This policy additionally includes the required AWS Glue and AWS Lake Formation permissions to [disable Lake federation](query-disable-federation.md) on an organization event data store.
This policy is attached to the **AWSServiceRoleForCloudTrail** service-linked role that allows CloudTrail to perform actions on your behalf. You cannot attach this policy to your users, groups, or roles.
For a JSON listing of the policy details, see [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailServiceRolePolicy.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailServiceRolePolicy.html) in the *AWS Managed Policy reference guide*.
## AWS managed policy: `CloudTrailEventContext`
The [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailEventContext.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailEventContext.html) policy allows AWS CloudTrail to manage CloudTrail Event Context and EventBridge rules on your behalf. The policy includes required EventBridge permissions for creating, managing, and describing the rules it creates for you.
This policy is attached to the **AWSServiceRoleForCloudTrailEventContext** service-linked role that allows CloudTrail to perform actions on your behalf. You cannot attach this policy to your users, groups, or roles.
For a JSON listing of the policy details, see [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailEventContext.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudTrailEventContext.html) in the *AWS Managed Policy reference guide*.
## CloudTrail updates to AWS managed policies
View details about updates to AWS managed policies for CloudTrail. For automatic alerts about changes to this page, subscribe to the RSS feed on the CloudTrail [Document history](cloudtrail-document-history.md) page.
| Change | Description | Date |
| --- | --- | --- |
| [`CloudTrailEventContext`](using-service-linked-roles-create-slr-for-context-management.md) – New policy used by the `AWSServiceRoleForCloudTrailEventContext` service linked role | Added a new policy and role used for the CloudTrail enriched events feature. | May 19, 2025 |
| [`CloudTrailServiceRolePolicy`](#security-iam-awsmanpol-CloudTrailServiceRolePolicy) – Update to an existing policy | Updated policy to allow the following actions on an organization event data store when federation is disabled: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/security-iam-awsmanpol.html) | November 26, 2023 |
| [`AWSCloudTrail_ReadOnlyAccess`](#security-iam-awsmanpol-AWSCloudTrail-ReadOnlyAccess) – Update to an existing policy | CloudTrail changed the name of the `AWSCloudTrailReadOnlyAccess` policy to `AWSCloudTrail_ReadOnlyAccess`. Also, the scope of permissions in the policy has been reduced to CloudTrail actions. It no longer includes Amazon S3, AWS KMS, or AWS Lambda action permissions. | June 6, 2022 |
| CloudTrail started tracking changes | CloudTrail started tracking changes for its AWS managed policies. | June 6, 2022 |
# Compliance validation for AWS CloudTrail
Third-party auditors assess the security and compliance of AWS CloudTrail as part of multiple AWS compliance programs. These include SOC, PCI, FedRAMP, HIPAA, and others.
To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/).
You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html).
Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. For more information about your compliance responsibility when using AWS services, see [AWS Security Documentation](https://docs.aws.amazon.com/security/).
# Resilience in AWS CloudTrail
The AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures. If you specifically need to replicate your CloudTrail log files over greater geographic distances, you can use [Cross-Region Replication](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html) for your trail Amazon S3 buckets, which enables automatic, asynchronous copying of objects across buckets in different AWS Regions.
For more information about AWS Regions and Availability Zones, see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/).
In addition to the AWS global infrastructure, CloudTrail offers several features to help support your data resiliency and backup needs.
**Trails and event data stores that log events in all AWS Regions**
When you create a multi-Region trail, CloudTrail creates trails with identical configurations in all enabled AWS Regions in your account.
When you create a multi-Region event data store, CloudTrail collects events that occur in all AWS Regions in your account.
**Versioning, lifecycle configuration, and object lock protection for CloudTrail log data**
Because CloudTrail uses Amazon S3 buckets to store log files, you can also use the features provided by Amazon S3 to help support your data resiliency and backup needs. For more information, see [Resilience in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/disaster-recovery-resiliency.html).
# Infrastructure security in AWS CloudTrail
As a managed service, AWS CloudTrail is protected by AWS global network security. For information about AWS security services and how AWS protects infrastructure, see [AWS Cloud Security](https://aws.amazon.com/security/). To design your AWS environment using the best practices for infrastructure security, see [Infrastructure Protection](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html) in *Security Pillar AWS Well‐Architected Framework*.
You use AWS published API calls to access CloudTrail through the network. Clients must support the following:
+ Transport Layer Security (TLS). We require TLS 1.2 and recommend TLS 1.3.
+ Cipher suites with perfect forward secrecy (PFS) such as DHE (Ephemeral Diffie-Hellman) or ECDHE (Elliptic Curve Ephemeral Diffie-Hellman). Most modern systems such as Java 7 and later support these modes.
The following security best practices also address infrastructure security in CloudTrail:
+ [Consider Amazon VPC endpoints for trail access.](cloudtrail-and-interface-VPC.md)
+ Consider Amazon VPC endpoints for Amazon S3 bucket access. For more information, see [Controlling access from VPC endpoints with bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies-vpc-endpoint.html).
+ Identify and audit all Amazon S3 buckets that contain CloudTrail log files. Consider using tags to help identify both your CloudTrail trails and the Amazon S3 buckets that contain CloudTrail log files. You can then use resource groups for your CloudTrail resources. For more information, see [AWS Resource Groups](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html).
# Cross-service confused deputy prevention
The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation can result in the confused deputy problem. Cross-service impersonation can occur when one service (the *calling service*) calls another service (the *called service*). The calling service can be manipulated to use its permissions to act on another customer's resources in a way it should not otherwise have permission to access. To prevent this, AWS provides tools that help you protect your data for all services with service principals that have been given access to resources in your account.
We recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource policies to limit the permissions that AWS CloudTrail gives another service to the resource. Use `aws:SourceArn` if you want only one resource to be associated with the cross-service access. Use `aws:SourceAccount` if you want to allow any resource in that account to be associated with the cross-service use.
The most effective way to protect against the confused deputy problem is to use the `aws:SourceArn` global condition context key with the full ARN of the resource. If you don't know the full ARN of the resource or if you are specifying multiple resources, use the `aws:SourceArn` global context condition key with wildcards (`*`) for the unknown portions of the ARN. For example, `"arn:aws:cloudtrail:*:AccountID:trail/*"`. When you include a wildcard, you must also use the `StringLike` condition operator.
The value of `aws:SourceArn` must be the ARN of the trail, event data store, or channel that is using the resource.
The following example shows how you can use the `aws:SourceArn` and `aws:SourceAccount` global condition context keys in CloudTrail to prevent the confused deputy problem: [Amazon S3 bucket policy for CloudTrail Lake query results](s3-bucket-policy-lake-query-results.md).
# Security best practices in AWS CloudTrail
AWS CloudTrail provides a number of security features to consider as you develop and implement your own security policies. The following best practices are general guidelines and don’t represent a complete security solution. Because these best practices might not be appropriate or sufficient for your environment, treat them as helpful considerations rather than prescriptions.
**Topics**
+ [CloudTrail detective security best practices](#best-practices-security-detective)
+ [CloudTrail preventative security best practices](#best-practices-security-preventative)
## CloudTrail detective security best practices
**Create a trail**
For an ongoing record of events in your AWS account, you must create a trail. Although CloudTrail provides 90 days of event history information for management events in the CloudTrail console without creating a trail, it is not a permanent record, and it does not provide information about all possible types of events. For an ongoing record, and for a record that contains all the event types you specify, you must create a trail, which delivers log files to an Amazon S3 bucket that you specify.
To help manage your CloudTrail data, consider creating one trail that logs management events in all AWS Regions, and then creating additional trails that log specific event types for resources, such as Amazon S3 bucket activity or AWS Lambda functions.
The following are some steps you can take:
+ [Create a trail for your AWS account.](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console)
+ [Create a trail for an organization.](creating-trail-organization.md)
**Create a multi-Region trail**
To obtain a complete record of events taken by an IAM identity, or service in your AWS account, create a multi-Region trail. Multi-Region trails log events in all AWS Regions that are [enabled](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#manage-acct-regions-enable-standalone) in your AWS account. By logging events in all enabled AWS Regions, you ensure that you capture activity in all enabled Regions in your AWS account. This includes logging [global service events](cloudtrail-concepts.md#cloudtrail-concepts-global-service-events), which are logged to an AWS Region specific to that service. All trails created using the CloudTrail console are multi-Region trails.
The following are some steps you can take:
+ [Create a trail for your AWS account.](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console)
+ [Convert an existing single-Region trail ](cloudtrail-update-a-trail-console.md) to a multi-Region trail.
+ Implement ongoing detective controls to help ensure all trails created are logging events in all AWS Regions by using the [multi-region-cloud-trail-enabled](https://docs.aws.amazon.com/config/latest/developerguide/multi-region-cloudtrail-enabled.html) rule in AWS Config.
**Enable CloudTrail log file integrity**
Validated log files are especially valuable in security and forensic investigations. For example, a validated log file enables you to assert positively that the log file itself has not changed, or that particular IAM identity credentials performed specific API activity. The CloudTrail log file integrity validation process also lets you know if a log file has been deleted or changed, or assert positively that no log files were delivered to your account during a given period of time. CloudTrail log file integrity validation uses industry standard algorithms: SHA-256 for hashing and SHA-256 with RSA for digital signing. This makes it computationally unfeasible to modify, delete or forge CloudTrail log files without detection. For more information, see [Enabling validation and validating files](cloudtrail-log-file-validation-intro.md#cloudtrail-log-file-validation-intro-enabling-and-using).
**Integrate with Amazon CloudWatch Logs**
CloudWatch Logs allows you to monitor and receive alerts for specific events captured by CloudTrail. The events sent to CloudWatch Logs are those configured to be logged by your trail, so make sure you have configured your trail or trails to log the event types (management events data events and/or network activity events) that you are interested in monitoring.
For example, you can monitor key security and network-related management events, such as [failed AWS Management Console sign-in events](cloudwatch-alarms-for-cloudtrail.md#cloudwatch-alarms-for-cloudtrail-signin).
The following are some steps you can take:
+ Review example [CloudWatch Logs integrations for CloudTrail](cloudwatch-alarms-for-cloudtrail.md).
+ Configure your trail to [send events to CloudWatch Logs](monitor-cloudtrail-log-files-with-cloudwatch-logs.md).
+ Consider implementing ongoing detective controls to help ensure all trails are sending events to CloudWatch Logs for monitoring by using the [cloud-trail-cloud-watch-logs-enabled](https://docs.aws.amazon.com/config/latest/developerguide/cloud-trail-cloud-watch-logs-enabled.html) rule in AWS Config.
**Use Amazon GuardDuty**
Amazon GuardDuty is a threat detection service that helps you protect your accounts, containers, workloads, and the data within your AWS environment. By using machine learning (ML) models, and anomaly and threat detection capabilities, GuardDuty continuously monitors different log sources to identify, and prioritize potential security risks and malicious activities in your environment.
For example, GuardDuty will detect potential credential exfiltration in case it detects credentials that were created exclusively for an Amazon EC2 instance through an instance launch role but are being used from another account within AWS. For more information, see the [https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html).
**Use AWS Security Hub CSPM**
Monitor your usage of CloudTrail as it relates to security best practices by using [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html). Security Hub CSPM uses detective *security controls* to evaluate resource configurations and *security standards* to help you comply with various compliance frameworks. For more information about using Security Hub CSPM to evaluate CloudTrail resources, see [AWS CloudTrail controls](https://docs.aws.amazon.com/securityhub/latest/userguide/cloudtrail-controls.html) in the *AWS Security Hub User Guide*.
## CloudTrail preventative security best practices
The following best practices for CloudTrail can help prevent security incidents.
**Log to a dedicated and centralized Amazon S3 bucket**
CloudTrail log files are an audit log of actions taken by an IAM identity or an AWS service. The integrity, completeness and availability of these logs is crucial for forensic and auditing purposes. By logging to a dedicated and centralized Amazon S3 bucket, you can enforce strict security controls, access, and segregation of duties.
The following are some steps you can take:
+ Create a separate AWS account as a log archive account. If you use AWS Organizations, enroll this account in the organization, and consider [creating an organization trail](creating-trail-organization.md) to log data for all AWS accounts in your organization.
+ If you do not use Organizations but want to log data for multiple AWS accounts, [create a trail](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console) to log activity in this log archive account. Restrict access to this account to only trusted administrative users who should have access to account and auditing data.
+ As part of creating a trail, whether it is an organization trail or a trail for a single AWS account, create a dedicated Amazon S3 bucket to store log files for this trail.
+ If you want to log activity for more than one AWS account, [modify the bucket policy](cloudtrail-set-bucket-policy-for-multiple-accounts.md) to allow logging and storing log files for all AWS accounts that you want to log AWS account activity.
+ If you are not using an organization trail, create trails in all of your AWS accounts, specifying the Amazon S3 bucket in the log archive account.
**Use server-side encryption with AWS KMS managed keys**
By default, the log files delivered by CloudTrail to your S3 bucket are encrypted by using [server-side encryption with a KMS key (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). To use SSE-KMS with CloudTrail, you create and manage an [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html), also known as a KMS key.
**Note**
If you use SSE-KMS and log file validation, and you have modified your Amazon S3 bucket policy to only allow SSE-KMS encrypted files, you will not be able to create trails that utilize that bucket unless you modify your bucket policy to specifically allow AES256 encryption, as shown in the following example policy line.
```
"StringNotEquals": { "s3:x-amz-server-side-encryption": ["aws:kms", "AES256"] }
```
The following are some steps you can take:
+ [Review the advantages of encrypting your log files with SSE-KMS](encrypting-cloudtrail-log-files-with-aws-kms.md).
+ [Create a KMS key to use for encrypting log files](create-kms-key-policy-for-cloudtrail.md).
+ [Configure log file encryption for your trails.](create-kms-key-policy-for-cloudtrail-update-trail.md)
+ Consider implementing ongoing detective controls to help ensure all trails are encrypting log files with SSE-KMS by using the [cloud-trail-encryption-enabled](https://docs.aws.amazon.com/config/latest/developerguide/cloud-trail-encryption-enabled.html) rule in AWS Config.
**Add a condition key to the default Amazon SNS topic policy**
When you configure a trail to send notifications to Amazon SNS, CloudTrail adds a policy statement to your SNS topic access policy that allows CloudTrail to send content to an SNS topic. As a security best practice, we recommend adding an `aws:SourceArn` (or optionally `aws:SourceAccount`) condition key to the Amazon SNS topic policy statement. This helps prevent unauthorized account access to your SNS topic. For more information, see [Amazon SNS topic policy for CloudTrail](cloudtrail-permissions-for-sns-notifications.md).
**Implement least privilege access to Amazon S3 buckets where you store log files**
CloudTrail trails log events to an Amazon S3 bucket that you specify. These log files contain an audit log of actions taken by IAM identities and AWS services. The integrity and completeness of these log files are crucial for auditing and forensic purposes. In order to help ensure that integrity, you should adhere to the principle of least privilege when creating or modifying access to any Amazon S3 bucket used for storing CloudTrail log files.
Take the following steps:
+ Review the [Amazon S3 bucket policy](create-s3-bucket-policy-for-cloudtrail.md) for any and all buckets where you store log files and adjust it if necessary to remove any unnecessary access. This bucket policy will be generated for you if you create a trail using the CloudTrail console, but can also be created and managed manually.
+ As a security best practice, be sure to manually add a `aws:SourceArn` condition key to the bucket policy. For more information, see [Amazon S3 bucket policy for CloudTrail](create-s3-bucket-policy-for-cloudtrail.md).
+ If you are using the same Amazon S3 bucket to store log files for multiple AWS accounts, follow the guidance for [receiving log files for multiple accounts](cloudtrail-receive-logs-from-multiple-accounts.md).
+ If you are using an organization trail, make sure you follow the guidance for [organization trails](creating-trail-organization.md), and review the example policy for an Amazon S3 bucket for an organization trail in [Creating a trail for an organization with the AWS CLI](cloudtrail-create-and-update-an-organizational-trail-by-using-the-aws-cli.md).
+ Review the [Amazon S3 security documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security.html) and the [example walkthrough for securing a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/walkthrough1.html).
**Enable MFA delete on the Amazon S3 bucket where you store log files**
When you configure multi-factor authentication (MFA), attempts to change the versioning state of bucket, or delete an object version in a bucket, require additional authentication. This way, even if a user acquires the password of an IAM user with permissions to permanently delete Amazon S3 objects, you can still prevent operations that could compromise your log files.
The following are some steps you can take:
+ Review the [MFA delete](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) guidance in the *Amazon Simple Storage Service User Guide*.
+ [Add an Amazon S3 bucket policy to require MFA](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-MFA).
**Note**
You cannot use MFA delete with lifecycle configurations. For more information about lifecycle configurations and how they interact with other configurations, see [Lifecycle and other bucket configurations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-and-other-bucket-config.html) in the *Amazon Simple Storage Service User Guide*.
**Configure object lifecycle management on the Amazon S3 bucket where you store log files**
The CloudTrail trail default is to store log files indefinitely in the Amazon S3 bucket configured for the trail. You can use the [Amazon S3 object lifecycle management rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to define your own retention policy to better meet your business and auditing needs. For example, you might want to archive log files that are more than a year old to Amazon Glacier, or delete log files after a certain amount of time has passed.
**Note**
Lifecycle configuration on multi-factor authentication (MFA)-enabled buckets is not supported.
**Limit access to the AWSCloudTrail\$1FullAccess policy**
Users with the [AWSCloudTrail\$1FullAccess](security_iam_id-based-policy-examples.md#grant-custom-permissions-for-cloudtrail-users-full-access) policy have the ability to disable or reconfigure the most sensitive and important auditing functions in their AWS accounts. This policy is not intended to be shared or applied broadly to IAM identities in your AWS account. Limit application of this policy to as few individuals as possible, those you expect to act as AWS account administrators.
# Encrypting CloudTrail log files, digest files, and event data stores with AWS KMS keys (SSE-KMS)
By default, the log files and digest files delivered by CloudTrail to your bucket are encrypted by using [server-side encryption with a KMS key (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). If you don't enable SSE-KMS encryption, your log files and digest files are encrypted using [SSE-S3 encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html).
**Note**
If you're using an existing S3 bucket with an [S3 bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), CloudTrail must be allowed permission in the key policy to use the AWS KMS actions `GenerateDataKey` and `DescribeKey`. If `cloudtrail.amazonaws.com` is not granted those permissions in the key policy, you cannot create or update a trail.
To use SSE-KMS with CloudTrail, you create and manage a [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html). You attach a policy to the key that determines which users can use the key for encrypting and decrypting CloudTrail log files and digest files. The decryption is seamless through S3. When authorized users of the key read CloudTrail log files or digest files, S3 manages the decryption, and the authorized users are able to read the files in unencrypted form.
This approach has the following advantages:
+ You can create and manage the KMS key yourself.
+ You can use a single KMS key to encrypt and decrypt log files and digest files for multiple accounts across all Regions.
+ You have control over who can use your key for encrypting and decrypting CloudTrail log files and digest files. You can assign permissions for the key to the users in your organization according to your requirements.
+ You have enhanced security. With this feature, to read log files or digest files, the following permissions are required:
+ A user must have S3 read permissions for the bucket that contains the log files and digest files.
+ A user must also have a policy or role applied that allows decrypt permissions by the KMS key policy.
+ Because S3 automatically decrypts the log files and digest files for requests from users authorized to use the KMS key, SSE-KMS encryption for the files is backward-compatible with applications that read CloudTrail log data.
**Note**
The KMS key that you choose must be created in the same AWS Region as the Amazon S3 bucket that receives your log files and digest files. For example, if the log files and digest files will be stored in a bucket in the US East (Ohio) Region, you must create or choose a KMS key that was created in that Region. To verify the Region for an Amazon S3 bucket, inspect its properties in the Amazon S3 console.
By default, event data stores are encrypted by CloudTrail. You have the option to use your own KMS key for encryption when you create or update an event data store.
## Enabling log file encryption
**Note**
If you create a KMS key in the CloudTrail console, CloudTrail adds the required KMS key policy sections for you. Follow these procedures if you created a key in the IAM console or AWS CLI and you need to manually add the required policy sections.
To enable SSE-KMS encryption for CloudTrail log files, perform the following high-level steps:
1. Create a KMS key.
+ For information about creating a KMS key with the AWS Management Console, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For information about creating a KMS key with the AWS CLI, see [create-key](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html).
**Note**
The KMS key that you choose must be in the same Region as the S3 bucket that receives your log files and digest files. To verify the Region for an S3 bucket, inspect the bucket's properties in the S3 console.
1. Add policy sections to the key that enable CloudTrail to encrypt and users to decrypt log files and digest files.
+ For information about what to include in the policy, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md).
**Warning**
Be sure to include decrypt permissions in the policy for all users who need to read log files or digest files. If you do not perform this step before adding the key to your trail configuration, users without decrypt permissions cannot read encrypted files until you grant them those permissions.
+ For information about editing a policy with the IAM console, see [Editing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-editing) in the *AWS Key Management Service Developer Guide*.
+ For information about attaching a policy to a KMS key with the AWS CLI, see [put-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html).
1. Update your trail or event data store to use the KMS key whose policy you modified for CloudTrail.
+ To update a trail or event data store using the CloudTrail console, see [Updating a resource to use your KMS key with the console](create-kms-key-policy-for-cloudtrail-update-trail.md).
+ To update a trail or event data store using the AWS CLI, see [Enabling and disabling encryption for CloudTrail log files, digest files and event data stores with the AWS CLI](cloudtrail-log-file-encryption-cli.md).
CloudTrail also supports AWS KMS multi-Region keys. For more information about multi-Region keys, see [Using multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS Key Management Service Developer Guide*.
The next section describes the policy sections that your KMS key policy requires for use with CloudTrail.
# Granting permissions to create a KMS key
You can grant users permission to create an AWS KMS key with the [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSKeyManagementServicePowerUser.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSKeyManagementServicePowerUser.html) policy.
**To grant permission to create a KMS key**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Choose the group or user that you want to give permission.
1. Choose the **Permissions** tab.
1. From the **Add permissions** list, choose **Attach policies**.
1. Search for **AWSKeyManagementServicePowerUser**, choose the policy, and then choose **Attach policies**.
The user now has permission to create a KMS key. For more information about creating policies, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
# Configure AWS KMS key policies for CloudTrail
You can create an AWS KMS key in three ways:
+ The CloudTrail console
+ The AWS Management console
+ The AWS CLI
**Note**
If you create a KMS key in the CloudTrail console, CloudTrail adds the required KMS key policy for you. You do not need to manually add the policy statements. See [Default KMS key policy created in CloudTrail console](default-kms-key-policy.md).
If you create a KMS key in the AWS Management Console or the AWS CLI, you must add policy sections to the key so that you can use it with CloudTrail. The policy must allow CloudTrail to use the key to encrypt your log files, digest files, and event data stores, and allow the users you specify to read log files and digest files in unencrypted form.
See the following resources:
+ To create a KMS key with the AWS CLI, see [create-key](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html).
+ To edit a KMS key policy for CloudTrail, see [Editing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-editing) in the *AWS Key Management Service Developer Guide*.
+ For technical details on how CloudTrail uses AWS KMS, see [How AWS CloudTrail uses AWS KMS](how-kms-works-with-cloudtrail.md).
**Topics**
+ [Required KMS key policy sections for use with CloudTrail](#create-kms-key-policy-for-cloudtrail-policy-sections)
+ [Granting encrypt permissions for trails](#create-kms-key-policy-for-cloudtrail-encrypt)
+ [Granting encrypt permissions for event data stores](#create-kms-key-policy-for-cloudtrail-encrypt-eds)
+ [Granting decrypt permissions for trails](#create-kms-key-policy-for-cloudtrail-decrypt)
+ [Granting decrypt permissions for event data stores](#create-kms-key-policy-for-cloudtrail-decrypt-eds)
+ [Enable CloudTrail to describe KMS key properties](#create-kms-key-policy-for-cloudtrail-describe)
+ [Default KMS key policy created in CloudTrail console](default-kms-key-policy.md)
## Required KMS key policy sections for use with CloudTrail
If you created a KMS key with the AWS Management console or the AWS CLI, then you must, at minimum, add the following statements to your KMS key policy for it to work with CloudTrail.
**Topics**
+ [Required KMS key policy elements for trails](#required-kms-key-policy-trails)
+ [Required KMS key policy elements for event data stores](#required-kms-key-policy-eventdatastores)
### Required KMS key policy elements for trails
1. Grant permissions to encrypt CloudTrail log and digest files. For more information, see [Granting encrypt permissions for trails](#create-kms-key-policy-for-cloudtrail-encrypt).
1. Grant permissions to decrypt CloudTrail log and digest files. For more information, see [Granting decrypt permissions for trails](#create-kms-key-policy-for-cloudtrail-decrypt). If you are using an existing S3 bucket with an [S3 Bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), `kms:Decrypt` permissions are required to create or update a trail with SSE-KMS encryption enabled.
1. Enable CloudTrail to describe KMS key properties. For more information, see [Enable CloudTrail to describe KMS key properties](#create-kms-key-policy-for-cloudtrail-describe).
As a security best practice, add an `aws:SourceArn` condition key to the KMS key policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail uses the KMS key only for a specific trail or trails. The value of `aws:SourceArn` is always the trail ARN (or array of trail ARNs) that is using the KMS key. Be sure to add the `aws:SourceArn` condition key to KMS key policies for existing trails.
The `aws:SourceAccount` condition key is also supported, but not recommended. The value of `aws:SourceAccount` is the account ID of the trail owner, or for organization trails, the management account ID.
**Important**
When you add the new sections to your KMS key policy, do not change any existing sections in the policy.
If encryption is enabled on a trail, and the KMS key is disabled, or the KMS key policy is not correctly configured for CloudTrail, CloudTrail cannot deliver logs.
### Required KMS key policy elements for event data stores
1. Grant permissions to encrypt a CloudTrail Lake event data store. For more information, see [Granting encrypt permissions for event data stores](#create-kms-key-policy-for-cloudtrail-encrypt-eds).
1. Grant permissions to decrypt a CloudTrail Lake event data store. For more information, see [Granting decrypt permissions for event data stores](#create-kms-key-policy-for-cloudtrail-decrypt-eds).
When you create an event data store and encrypt it with a KMS key, or run queries on an event data store that you're encrypting with a KMS key, you should have write access to the KMS key. The KMS key policy must have access to CloudTrail, and the KMS key should be manageable by users who run operations (such as queries) on the event data store.
1. Enable CloudTrail to describe KMS key properties. For more information, see [Enable CloudTrail to describe KMS key properties](#create-kms-key-policy-for-cloudtrail-describe).
The `aws:SourceArn` and `aws:SourceAccount` condition keys are not supported in KMS key policies for event data stores.
**Important**
When you add the new sections to your KMS key policy, do not change any existing sections in the policy.
If encryption is enabled on an event data store, and the KMS key is disabled or deleted, or the KMS key policy is not correctly configured for CloudTrail, CloudTrail cannot deliver events to your event data store.
## Granting encrypt permissions for trails
**Example Allow CloudTrail to encrypt log files and digest files on behalf of specific accounts**
CloudTrail needs explicit permission to use the KMS key to encrypt log files and digest files on behalf of specific accounts. To specify an account, add the following required statement to your KMS key policy and replace *account-id*, *region*, and *trailName* with the appropriate values for your configuration. You can add additional account IDs to the `EncryptionContext` section to enable those accounts to use CloudTrail to use your KMS key to encrypt log files and digest files.
As a security best practice, add an `aws:SourceArn` condition key to the KMS key policy for a trail. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail uses the KMS key only for a specific trail or trails.
```
{
"Sid": "AllowCloudTrailEncryptLogs",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:GenerateDataKey*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:account-id:trail/trail-name"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws:cloudtrail:*:account-id:trail/*"
}
}
}
```
**Example**
The following example policy statement illustrates how another account can use your KMS key to encrypt CloudTrail log files and digest files.
**Scenario**
+ Your KMS key is in account *111111111111*.
+ Both you and account *222222222222* will encrypt logs.
In the policy, you add one or more accounts that encrypt with your key to the CloudTrail **EncryptionContext**. This restricts CloudTrail to using your key to encrypt log files and digest files only for the accounts that you specify. When you give the root of account *222222222222* permission to encrypt log files and digest files, it delegates permission to the account administrator to encrypt the necessary permissions to other users in that account. The account administrator does this by changing the policies associated with those IAM users.
As a security best practice, add an `aws:SourceArn` condition key to the KMS key policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail uses the KMS key only for the specified trails. This condition isn't supported in KMS key policies for event data stores.
KMS key policy statement:
```
{
"Sid": "EnableCloudTrailEncryptPermissions",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:GenerateDataKey*",
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": [
"arn:aws:cloudtrail:*:111111111111:trail/*",
"arn:aws:cloudtrail:*:222222222222:trail/*"
]
},
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:account-id:trail/trail-name"
}
}
}
```
For more information about editing a KMS key policy for use with CloudTrail, see [Editing a key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-editing) in the AWS Key Management Service Developer Guide.
## Granting encrypt permissions for event data stores
A policy for a KMS key used to encrypt a CloudTrail Lake event data store cannot use the condition keys `aws:SourceArn` or `aws:SourceAccount`. The following is an example of a KMS key policy for an event data store.
```
{
"Sid": "AllowCloudTrailEncryptEds",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*"
}
```
## Granting decrypt permissions for trails
Before you add your KMS key to your CloudTrail configuration, it is important to give decrypt permissions to all users who require them. Users who have encrypt permissions but no decrypt permissions cannot read encrypted logs. If you are using an existing S3 bucket with an [S3 Bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), `kms:Decrypt` permissions are required to create or update a trail with SSE-KMS encryption enabled.
**Enable CloudTrail log decrypt permissions**
Users of your key must be given explicit permissions to read the log files that CloudTrail has encrypted. To enable users to read encrypted logs, add the following required statement to your KMS key policy, modifying the `Principal` section to add a line for every principal that you want to be able decrypt by using your KMS key.
```
{
"Sid": "EnableCloudTrailLogDecryptPermissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::account-id:user/username"
},
"Action": "kms:Decrypt",
"Resource": "*",
"Condition": {
"Null": {
"kms:EncryptionContext:aws:cloudtrail:arn": "false"
}
}
}
```
The following is an example policy that is required to allow the CloudTrail service principal to decrypt trail logs.
```
{
"Sid": "AllowCloudTrailDecryptTrail",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:Decrypt",
"Resource": "*"
}
```
### Allow users in your account to decrypt trail logs with your KMS key
**Example**
This policy statement illustrates how to allow a user or role in your account to use your key to read the encrypted logs in your account's S3 bucket.
**Example Scenario**
+ Your KMS key, S3 bucket, and IAM user Bob are in account `111111111111`.
+ You give IAM user Bob permission to decrypt CloudTrail logs in the S3 bucket.
In the key policy, you enable CloudTrail log decrypt permissions for IAM user Bob.
KMS key policy statement:
```
{
"Sid": "EnableCloudTrailLogDecryptPermissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:user/Bob"
},
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:region:account-id:key/key-id",
"Condition": {
"Null": {
"kms:EncryptionContext:aws:cloudtrail:arn": "false"
}
}
}
```
**Topics**
### Allow users in other accounts to decrypt trail logs with your KMS key
You can allow users in other accounts to use your KMS key to decrypt trail logs. The changes required to your key policy depend on whether the S3 bucket is in your account or in another account.
#### Allow users of a bucket in a different account to decrypt logs
**Example**
This policy statement illustrates how to allow an IAM user or role in another account to use your key to read encrypted logs from an S3 bucket in the other account.
**Scenario**
+ Your KMS key is in account `111111111111`.
+ The IAM user Alice and S3 bucket are in account `222222222222`.
In this case, you give CloudTrail permission to decrypt logs under account `222222222222`, and you give Alice's IAM user policy permission to use your key `KeyA`, which is in account `111111111111`.
KMS key policy statement:
```
{
"Sid": "EnableEncryptedCloudTrailLogReadAccess",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::222222222222:root"
]
},
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:region:111111111111:key/key-id",
"Condition": {
"Null": {
"kms:EncryptionContext:aws:cloudtrail:arn": "false"
}
}
}
```
Alice's IAM user policy statement:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:us-west-2:111111111111:key/KeyA"
}
]
}
```
------
#### Allow users in a different account to decrypt trail logs from your bucket
**Example**
This policy illustrates how another account can use your key to read encrypted logs from your S3 bucket.
**Example Scenario**
+ Your KMS key and S3 bucket are in account `111111111111`.
+ The user who reads logs from your bucket is in account `222222222222`.
To enable this scenario, you enable decrypt permissions for the IAM role **CloudTrailReadRole** in your account, and then give the other account permission to assume that role.
KMS key policy statement:
```
{
"Sid": "EnableEncryptedCloudTrailLogReadAccess",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111111111111:role/CloudTrailReadRole"
]
},
"Action": "kms:Decrypt",
"Resource": "arn:aws:kms:region:account-id:key/key-id",
"Condition": {
"Null": {
"kms:EncryptionContext:aws:cloudtrail:arn": "false"
}
}
}
```
**CloudTrailReadRole** trust entity policy statement:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Allow CloudTrail access",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::222222222222:root"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
For information about editing a KMS key policy for use with CloudTrail, see [Editing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-editing) in the *AWS Key Management Service Developer Guide*.
## Granting decrypt permissions for event data stores
A decrypt policy for a KMS key that is used with a CloudTrail Lake event data store is similar to the following. The user or role ARNs specified as values for `Principal` need decrypt permissions to create or update event data stores, run queries, or get query results.
```
{
"Sid": "EnableUserKeyPermissionsEds"
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::account-id:user/username"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*"
}
```
The following is an example policy that is required to allow the CloudTrail service principal to decrypt an event data store.
```
{
"Sid": "AllowCloudTrailDecryptEds",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:Decrypt",
"Resource": "*"
}
```
## Enable CloudTrail to describe KMS key properties
CloudTrail requires the ability to describe the properties of the KMS key. To enable this functionality, add the following required statement as is to your KMS key policy. This statement does not grant CloudTrail any permissions beyond the other permissions that you specify.
As a security best practice, add an `aws:SourceArn` condition key to the KMS key policy. The IAM global condition key `aws:SourceArn` helps ensure that CloudTrail uses the KMS key only for a specific trail or trails.
```
{
"Sid": "AllowCloudTrailAccess",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:DescribeKey",
"Resource": "arn:aws:kms:region:account-id:key/key-id",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:region:account-id:trail/trail-name"
}
}
}
```
For more information about editing KMS key policies, see [Editing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-editing) in the *AWS Key Management Service Developer Guide*.
# Default KMS key policy created in CloudTrail console
If you create an AWS KMS key in the CloudTrail console, the following policies are automatically created for you. The policy allows these permissions:
+ Allows AWS account (root) permissions for the KMS key.
+ Allows CloudTrail to encrypt log files and digest files under the KMS key and describe the KMS key.
+ Allows all users in the specified accounts to decrypt log files and digest files.
+ Allows all users in the specified account to create a KMS alias for the KMS key.
+ Enables cross-account log decryption for the account ID of the account that created the trail.
**Topics**
+ [Default KMS key policy for trails](#default-kms-key-policy-trail)
+ [Default KMS key policy for CloudTrail Lake event data stores](#default-kms-key-policy-eds)
## Default KMS key policy for trails
The following is the default policy created for a AWS KMS key that you use with a trail.
**Note**
The policy includes a statement to allow cross accounts to decrypt log files and digest files with the KMS key.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "Key policy created by CloudTrail",
"Statement": [
{
"Sid": "Enable IAM user permissions",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111111111111:root",
"arn:aws:iam::111111111111:user/username"
]
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow CloudTrail to encrypt logs",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:GenerateDataKey*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:cloudtrail:us-east-1:111111111111:trail/trail-name"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws:cloudtrail:*:111111111111:trail/*"
}
}
},
{
"Sid": "Allow CloudTrail to describe key",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "Allow principals in the account to decrypt log files",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"kms:Decrypt",
"kms:ReEncryptFrom"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:CallerAccount": "111111111111"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws:cloudtrail:*:111111111111:trail/*"
}
}
},
{
"Sid": "Enable cross account log decryption",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"kms:Decrypt",
"kms:ReEncryptFrom"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:CallerAccount": "111111111111"
},
"StringLike": {
"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws:cloudtrail:*:111111111111:trail/*"
}
}
}
]
}
```
------
## Default KMS key policy for CloudTrail Lake event data stores
The following is the default policy created for a AWS KMS key that you use with an event data store in CloudTrail Lake.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "Key policy created by CloudTrail",
"Statement": [
{
"Sid": "The key created by CloudTrail to encrypt event data stores. Created ${new Date().toUTCString()}",
"Effect": "Allow",
"Principal": {
"Service": "cloudtrail.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*"
},
{
"Sid": "Enable IAM user permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:root"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Enable user to have permissions",
"Effect": "Allow",
"Principal": {
"AWS" : "arn:aws:sts::111111111111:assumed-role/example-role-name"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*"
}
]
}
```
------
# Updating a resource to use your KMS key with the console
On the CloudTrail console, update a trail or an event data store to use an KMS key. Be aware that using your own KMS key incurs AWS KMS costs for encryption and decryption. For more information, see [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/).
**Topics**
+ [Update a trail to use a KMS key](#kms-key-policy-update-trail)
+ [Update an event data store to use a KMS key](#kms-key-policy-update-eds)
## Update a trail to use a KMS key
To update a trail to use the AWS KMS key that you modified for CloudTrail, complete the following steps in the CloudTrail console.
**Note**
If you are using an existing S3 bucket with an [S3 Bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), CloudTrail must be allowed permission in the key policy to use the AWS KMS actions `GenerateDataKey` and `DescribeKey`. If `cloudtrail.amazonaws.com` is not granted those permissions in the key policy, you cannot create or update a trail.
To update a trail using the AWS CLI, see [Enabling and disabling encryption for CloudTrail log files, digest files and event data stores with the AWS CLI](cloudtrail-log-file-encryption-cli.md).
**To update a trail to use your KMS key**
1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. Choose **Trails** and then choose a trail name.
1. In **General details**, choose **Edit**.
1. For **Log file SSE-KMS encryption**, choose **Enabled** if you want to encrypt your log files and digest files using SSE-KMS encryption instead of SSE-S3 encryption. The default is **Enabled**. If you don't enable SSE-KMS encryption, your log files and digest files are encrypted using SSE-S3 encryption. For more information about SSE-KMS encryption, see [Using server-side encryption with AWS Key Management Service (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). For more information about SSE-S3 encryption, see [Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html).
Choose **Existing** to update your trail with your AWS KMS key. Choose a KMS key that is in the same Region as the S3 bucket that receives your log files. To verify the Region for an S3 bucket, view its properties in the S3 console.
**Note**
You can also type the ARN of a key from another account. For more information, see [Updating a resource to use your KMS key with the console](#create-kms-key-policy-for-cloudtrail-update-trail). The key policy must allow CloudTrail to use the key to encrypt your log files and digest files, and allow the users you specify to read log files or digest files in unencrypted form. For information about manually editing the key policy, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md).
In **AWS KMS Alias**, specify the alias for which you changed the policy for use with CloudTrail, in the format `alias/`*MyAliasName*. For more information, see [Updating a resource to use your KMS key with the console](#create-kms-key-policy-for-cloudtrail-update-trail).
You can type the alias name, ARN, or the globally unique key ID. If the KMS key belongs to another account, verify that the key policy has permissions that enable you to use it. The value can be one of the following formats:
+ **Alias Name**: `alias/MyAliasName`
+ **Alias ARN**: `arn:aws:kms:region:123456789012:alias/MyAliasName`
+ **Key ARN**: `arn:aws:kms:region:123456789012:key/12345678-1234-1234-1234-123456789012`
+ **Globally unique key ID**: `12345678-1234-1234-1234-123456789012`
1. Choose **Update trail**.
**Note**
If the KMS key that you chose is disabled or is pending deletion, you cannot save the trail with that KMS key. You can enable the KMS key or choose another one. For more information, see [Key state: Effect on your KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html) in the *AWS Key Management Service Developer Guide*.
## Update an event data store to use a KMS key
To update an event data store to use the AWS KMS key that you modified for CloudTrail, complete the following steps in the CloudTrail console.
To update an event data store by using the AWS CLI, see [Update an event data store with the AWS CLI](lake-cli-update-eds.md).
**Important**
Disabling or deleting the KMS key, or removing CloudTrail permissions on the key, prevents CloudTrail from ingesting events into the event data store, and prevents users from querying data in the event data store that was encrypted with the key. After you associate an event data store with a KMS key, the KMS key cannot be removed or changed. Before you disable or delete a KMS key that you are using with an event data store, delete or back up your event data store.
**To update an event data store to use your KMS key**
1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. In the navigation pane, choose **Event data stores** in **Lake**. Choose an event data store to update.
1. In **General details**, choose **Edit**.
1. For **Encryption**, if it is not already enabled, choose **Use my own AWS KMS key** to encrypt your event data store with your own KMS key.
Choose **Existing** to update your event data store with your KMS key. Choose a KMS key that is in the same Region as the event data store. A key from another account is not supported.
In **Enter AWS KMS Alias**, specify the alias for which you changed the policy for use with CloudTrail, in the format `alias/`*MyAliasName*. For more information, see [Updating a resource to use your KMS key with the console](#create-kms-key-policy-for-cloudtrail-update-trail).
You can choose an alias, or use the globally unique key ID. The value can be one of the following formats:
+ **Alias Name**: `alias/MyAliasName`
+ **Alias ARN**: `arn:aws:kms:region:123456789012:alias/MyAliasName`
+ **Key ARN**: `arn:aws:kms:region:123456789012:key/12345678-1234-1234-1234-123456789012`
+ **Globally unique key ID**: `12345678-1234-1234-1234-123456789012`
1. Choose **Save changes**.
**Note**
If the KMS key that you chose is disabled or is pending deletion, you cannot save the event data store configuration with that KMS key. You can enable the KMS key, or choose a different key. For more information, see [Key state: Effect on your KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html) in the *AWS Key Management Service Developer Guide*.
# Enabling and disabling encryption for CloudTrail log files, digest files and event data stores with the AWS CLI
This topic describes how to enable and disable SSE-KMS encryption for CloudTrail log files, digest files, and event data stores by using the AWS CLI. For background information, see [Encrypting CloudTrail log files, digest files, and event data stores with AWS KMS keys (SSE-KMS)](encrypting-cloudtrail-log-files-with-aws-kms.md).
**Topics**
+ [Enabling encryption for CloudTrail log files, digest files, and event data stores by using the AWS CLI](#cloudtrail-log-file-encryption-cli-enable)
+ [Disabling encryption for log files and digest files by using the AWS CLI](#cloudtrail-log-file-encryption-cli-disable)
## Enabling encryption for CloudTrail log files, digest files, and event data stores by using the AWS CLI
+ [Enable log file and digest file encryption for a trail](#log-encryption-trail)
+ [Enable encryption for an event data store](#log-encryption-eds)
**Enable encryption for log files and digest files for a trail**
1. Create a key with the AWS CLI. The key that you create must be in the same Region as the S3 bucket that receives your CloudTrail log files. For this step, you use the AWS KMS [https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html) command.
1. Get the existing key policy so that you can modify it for use with CloudTrail. You can retrieve the key policy with the AWS KMS [https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) command.
1. Add required sections to the key policy so that CloudTrail can encrypt and users can decrypt your log files and digest files. Be sure that all users who read the log files are granted decrypt permissions. Do not change existing sections of the policy. For information about the policy sections to include, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md).
1. Attach the modified JSON policy file to the key by using the AWS KMS [https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html) command.
1. Run the CloudTrail `create-trail` or `update-trail` command with the `--kms-key-id` parameter. This command enables encryption of log files and digest files.
```
aws cloudtrail update-trail --name Default --kms-key-id alias/MyKmsKey
```
The `--kms-key-id` parameter specifies the key whose policy you modified for CloudTrail. It can be any one of the following formats:
+ **Alias Name**. Example: `alias/MyAliasName`
+ **Alias ARN**. Example: `arn:aws:kms:us-east-2:123456789012:alias/MyAliasName`
+ **Key ARN**. Example: `arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012`
+ **Globally unique key ID.** Example: `12345678-1234-1234-1234-123456789012`
The following is an example response:
```
{
"IncludeGlobalServiceEvents": true,
"Name": "Default",
"TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Default",
"LogFileValidationEnabled": false,
"KmsKeyId": "arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012",
"S3BucketName": "amzn-s3-demo-bucket"
}
```
The presence of the `KmsKeyId` element indicates that encryption for your log files has been enabled. If log file validation has been enabled (indicated by the `LogFileValidationEnabled` element being set to true), this also indicates that encryption has been enabled for your digest files. The encrypted log files and digest files should appear in the S3 bucket configured for the trail within approximately 5 minutes.
**Enable encryption for an event data store**
1. Create a key with the AWS CLI. The key that you create must be in the same Region as the event data store. For this step, run the AWS KMS [https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html) command.
1. Get the existing key policy to edit for use with CloudTrail. You can get the key policy by running the AWS KMS [https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) command.
1. Add required sections to the key policy so that CloudTrail can encrypt and users can decrypt your event data store. Be sure that all users who read the event data store are granted decrypt permissions. Do not change existing sections of the policy. For information about the policy sections to include, see [Configure AWS KMS key policies for CloudTrail](create-kms-key-policy-for-cloudtrail.md).
1. Attach the edited JSON policy file to the key by running the AWS KMS [put-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html) command.
1. Run the CloudTrail `create-event-data-store` or `update-event-data-store` command, and add the `--kms-key-id` parameter. This command enables encryption of the event data store.
```
aws cloudtrail update-event-data-store --name my-event-data-store --kms-key-id alias/MyKmsKey
```
The `--kms-key-id` parameter specifies the key whose policy you modified for CloudTrail. It can be any one of the following four formats:
+ **Alias Name**. Example: `alias/MyAliasName`
+ **Alias ARN**. Example: `arn:aws:kms:us-east-2:123456789012:alias/MyAliasName`
+ **Key ARN**. Example: `arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012`
+ **Globally unique key ID.** Example: `12345678-1234-1234-1234-123456789012`
The following is an example response:
```
{
"Name": "my-event-data-store",
"ARN": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
"RetentionPeriod": "90",
"KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
"MultiRegionEnabled": false,
"OrganizationEnabled": false,
"TerminationProtectionEnabled": true,
"AdvancedEventSelectors": [{
"Name": "Select all external events",
"FieldSelectors": [{
"Field": "eventCategory",
"Equals": [
"ActivityAuditLog"
]
}]
}]
}
```
The presence of the `KmsKeyId` element indicates that encryption for event data store has been enabled.
## Disabling encryption for log files and digest files by using the AWS CLI
To stop encrypting log files and digest files for a trail, run `update-trail` and pass an empty string to the `kms-key-id` parameter:
```
aws cloudtrail update-trail --name my-test-trail --kms-key-id ""
```
The following is an example response:
```
{
"IncludeGlobalServiceEvents": true,
"Name": "Default",
"TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Default",
"LogFileValidationEnabled": false,
"S3BucketName": "amzn-s3-demo-bucket"
}
```
The absence of the `KmsKeyId` value indicates that encryption for log files and digest files is no longer enabled.
**Important**
You cannot stop encryption for an event data store.
# How AWS CloudTrail uses AWS KMS
This section describes how AWS KMS works with a CloudTrail trail that is encrypted with an SSE-KMS key.
**Important**
AWS CloudTrail and Amazon S3 support only [symmetric AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html#symmetric-cmks). You cannot use an [asymmetric KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) to encrypt your CloudTrail Logs. For help determining whether a KMS key is symmetric or asymmetric, see [Identify different key types](https://docs.aws.amazon.com/kms/latest/developerguide/identify-key-types.html) in the *AWS Key Management Service Developer Guide*.
You do not pay a key usage charge when CloudTrail reads or writes log files encrypted with an SSE-KMS key. However, you pay a key usage charge when you access CloudTrail log files encrypted with an SSE-KMS key. For information about AWS KMS pricing, see [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/). For information about CloudTrail pricing, see [AWS CloudTrail pricing](https://aws.amazon.com/cloudtrail/pricing/).
## Understanding when your KMS key is used for your trail
Encrypting CloudTrail log files with AWS KMS builds on the Amazon S3 feature called server-side encryption with an AWS KMS key (SSE-KMS). To learn more about SSE-KMS, see [Using server-side encryption with AWS KMS keys (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html) in the *Amazon Simple Storage Service User Guide*.
When you configure AWS CloudTrail to use SSE-KMS to encrypt your log files, CloudTrail and Amazon S3 use your AWS KMS keys when you perform certain actions with those services. The following sections explain when and how those services can use your KMS key, and provide additional information that you can use to validate this explanation.
**Contents**
+ [You configure CloudTrail to encrypt log files with your AWS KMS key](#cloudtrail-details-update-configuration)
+ [CloudTrail puts a log file into your S3 bucket](#cloudtrail-details-put-log-file)
+ [You get an encrypted log file from your S3 bucket](#cloudtrail-details-get-log-file)
### You configure CloudTrail to encrypt log files with your AWS KMS key
When you [update your CloudTrail configuration to use your KMS key](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail-update-trail.html), CloudTrail sends a [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) request to AWS KMS to verify that the KMS key exists and that CloudTrail has permission to use it for encryption. CloudTrail does not use the resulting data key.
The `GenerateDataKey` request includes the following information for the [encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/encrypt_context.html):
+ The [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of the CloudTrail trail
+ The ARN of the S3 bucket and path where the CloudTrail log files are delivered
The `GenerateDataKey` request results in an entry in your CloudTrail logs similar to the following example. When you see a log entry like this one, you can determine that CloudTrail called the AWS KMS `GenerateDataKey` operation for a specific trail. AWS KMS created the data key under a specific KMS key.
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AWSService",
"invokedBy": "cloudtrail.amazonaws.com"
},
"eventTime": "2024-12-06T20:14:46Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-east-1",
"sourceIPAddress": "cloudtrail.amazonaws.com",
"userAgent": "cloudtrail.amazonaws.com",
"requestParameters": {
"keySpec": "AES_256",
"keyId": "arn:aws:kms:us-east-1:123456789012:key/example1-6736-4661-bf00-exampleeb770",
"encryptionContext": {
"aws:cloudtrail:arn": "arn:aws:cloudtrail:us-east-1:123456789012:trail/management-events",
"aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-logging-bucket-123456789012-9af1fb49/AWSLogs/123456789012/CloudTrail/us-east-1/2024/12/06/123456789012_CloudTrail_us-east-1_20241206T2010Z_TO50OLMG1hIQ1png.json.gz"
}
},
"responseElements": null,
"requestID": "a0555e85-7e8a-4765-bd8f-2222295558e1",
"eventID": "e4f3557e-7dbd-4e37-a00a-d86c137d1111",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:123456789012:key/example1-6736-4661-bf00-exampleeb770"
}],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"sharedEventID": "ce71d6be-0846-498e-851f-111a1af9078f",
"eventCategory": "Management"
}
```
### CloudTrail puts a log file into your S3 bucket
Each time CloudTrail puts a log file into your S3 bucket, Amazon S3 sends a [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) request to AWS KMS on behalf of CloudTrail. In response to this request, AWS KMS generates a unique data key and then sends Amazon S3 two copies of the data key, one in plaintext and one that is encrypted with the specified KMS key. Amazon S3 uses the plaintext data key to encrypt the CloudTrail log file and then removes the plaintext data key from memory as soon as possible after use. Amazon S3 stores the encrypted data key as metadata with the encrypted CloudTrail log file.
The `GenerateDataKey` request includes the following information for the [encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/encrypt_context.html):
+ The [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of the CloudTrail trail
+ The ARN of the S3 object (the CloudTrail log file)
Each `GenerateDataKey` request results in an entry in your CloudTrail logs similar to the following example. When you see a log entry like this one, you can determine that CloudTrail called the AWS KMS `GenerateDataKey` operation for a specific trail to protect a specific log file. AWS KMS created the data key under the specified KMS key, shown twice in the same log entry.
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AWSService",
"invokedBy": "cloudtrail.amazonaws.com"
},
"eventTime": "2024-12-06T21:49:28Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-east-1",
"sourceIPAddress": "cloudtrail.amazonaws.com",
"userAgent": "cloudtrail.amazonaws.com",
"requestParameters": {
"encryptionContext": {
"aws:cloudtrail:arn": "arn:aws:cloudtrail:us-east-1::trail/insights-trail",
"aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-logging-bucket1-123456789012-7867ab0c/AWSLogs/123456789012/CloudTrail/us-east-1/2024/12/06/123456789012_CloudTrail_us-east-1_20241206T2150Z_hVXmrJzjZk2wAM2V.json.gz"
},
"keySpec": "AES_256",
"keyId": "arn:aws:kms:us-east-1:123456789012:key/example9-16ef-48ba-9163-example67a5a"
},
"responseElements": null,
"requestID": "11117d14-9232-414a-b3d1-01bab4dc9f99",
"eventID": "999e9a50-512c-4e2a-84a3-111a5f511111",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:123456789012:key/example9-16ef-48ba-9163-example67a5a"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"sharedEventID": "5e663acc-b7fd-4cdd-8328-0eff862952fa",
"eventCategory": "Management"
}
```
### You get an encrypted log file from your S3 bucket
Each time you get an encrypted CloudTrail log file from your S3 bucket, Amazon S3 sends a [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) request to AWS KMS on your behalf to decrypt the log file's encrypted data key. In response to this request, AWS KMS uses your KMS key to decrypt the data key and then sends the plaintext data key to Amazon S3. Amazon S3 uses the plaintext data key to decrypt the CloudTrail log file and then removes the plaintext data key from memory as soon as possible after use.
The `Decrypt` request includes the following information for the [encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/encrypt_context.html):
+ The [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of the CloudTrail trail
+ The ARN of the S3 object (the CloudTrail log file)
Each `Decrypt` request results in an entry in your CloudTrail logs similar to the following example. When you see a log entry like this one, you can determine that an assumed role called the AWS KMS `Decrypt` operation for a specific trail and a specific log file. AWS KMS decrypted the data key under a specific KMS key.
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:sts::123456789012:assumed-role/Admin",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::123456789012:role/Admin",
"accountId": "123456789012",
"userName": "Admin"
},
"attributes": {
"creationDate": "2024-12-06T22:04:04Z",
"mfaAuthenticated": "false"
}
},
"invokedBy": "AWS Internal"
},
"eventTime": "2024-12-06T22:26:34Z",
"eventSource": "kms.amazonaws.com",
"eventName": "Decrypt",
"awsRegion": "us-east-1",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"requestParameters": {
"encryptionContext": {
"aws:cloudtrail:arn": "arn:aws:cloudtrail:us-east-1:123456789012:trail/insights-trail",
"aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-logging-bucket1-123456789012-7867ab0c/AWSLogs/123456789012/CloudTrail/us-east-1/2024/12/06/123456789012_CloudTrail_us-east-1_20241206T0000Z_aAAsHbGBdye3jp2R.json.gz"
},
"encryptionAlgorithm": "SYMMETRIC_DEFAULT"
},
"responseElements": null,
"requestID": "1ab2d2d2-111a-2222-a59b-11a2b3832b53",
"eventID": "af4d4074-2849-4b3d-1a11-a1aaa111a111",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:123456789012:key/example9-16ef-48ba-9163-example67a5a"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"sessionCredentialFromConsole": "true"
}
```