Package software.amazon.awscdk.services.cloudtrail
AWS CloudTrail Construct Library
Trail
AWS CloudTrail enables governance, compliance, and operational and risk auditing of your AWS account. Actions taken by a user, role, or an AWS service are recorded as events in CloudTrail. Learn more at the CloudTrail documentation.
The Trail
construct enables ongoing delivery of events as log files to an Amazon S3 bucket. Learn more about Creating
a Trail for Your AWS Account.
The following code creates a simple CloudTrail for your account -
Trail trail = new Trail(this, "CloudTrail");
By default, this will create a new S3 Bucket that CloudTrail will write to, and choose a few other reasonable defaults
such as turning on multi-region and global service events.
The defaults for each property and how to override them are all documented on the TrailProps
interface.
Log File Validation
In order to validate that the CloudTrail log file was not modified after CloudTrail delivered it, CloudTrail provides a digital signature for each file. Learn more at Validating CloudTrail Log File Integrity.
This is enabled on the Trail
construct by default, but can be turned off by setting enableFileValidation
to false
.
Trail trail = Trail.Builder.create(this, "CloudTrail") .enableFileValidation(false) .build();
Notifications
Amazon SNS notifications can be configured upon new log files containing Trail events are delivered to S3. Learn more at Configuring Amazon SNS Notifications for CloudTrail. The following code configures an SNS topic to be notified -
Topic topic = new Topic(this, "TrailTopic"); Trail trail = Trail.Builder.create(this, "CloudTrail") .snsTopic(topic) .build();
Service Integrations
Besides sending trail events to S3, they can also be configured to notify other AWS services -
Amazon CloudWatch Logs
CloudTrail events can be delivered to a CloudWatch Logs LogGroup. By default, a new LogGroup is created with a default retention setting. The following code enables sending CloudWatch logs but specifies a particular retention period for the created Log Group.
import software.amazon.awscdk.services.logs.*; Trail trail = Trail.Builder.create(this, "CloudTrail") .sendToCloudWatchLogs(true) .cloudWatchLogsRetention(RetentionDays.FOUR_MONTHS) .build();
If you would like to use a specific log group instead, this can be configured via cloudwatchLogGroup
.
Amazon EventBridge
Amazon EventBridge rules can be configured to be triggered when CloudTrail events occur using the Trail.onEvent()
API.
Using APIs available in aws-events
, these events can be filtered to match to those that are of interest, either from
a specific service, account or time range. See Events delivered via
CloudTrail
to learn more about the event structure for events from CloudTrail.
The following code filters events for S3 from a specific AWS account and triggers a lambda function.
Function myFunctionHandler = Function.Builder.create(this, "MyFunction") .code(Code.fromAsset("resource/myfunction")) .runtime(Runtime.NODEJS_LATEST) .handler("index.handler") .build(); Rule eventRule = Trail.onEvent(this, "MyCloudWatchEvent", OnEventOptions.builder() .target(new LambdaFunction(myFunctionHandler)) .build()); eventRule.addEventPattern(EventPattern.builder() .account(List.of("123456789012")) .source(List.of("aws.s3")) .build());
Multi-Region & Global Service Events
By default, a Trail
is configured to deliver log files from multiple regions to a single S3 bucket for a given
account. This creates shadow trails (replication of the trails) in all of the other regions. Learn more about How
CloudTrail Behaves Regionally
and about the IsMultiRegion
property.
For most services, events are recorded in the region where the action occurred. For global services such as AWS IAM, AWS STS, Amazon CloudFront, Route 53, etc., events are delivered to any trail that includes global services. Learn more About Global Service Events.
Events for global services are turned on by default for Trail
constructs in the CDK.
The following code disables multi-region trail delivery and trail delivery for global services for a specific Trail
-
Trail trail = Trail.Builder.create(this, "CloudTrail") // ... .isMultiRegionTrail(false) .includeGlobalServiceEvents(false) .build();
Events Types
Management events provide information about management operations that are performed on resources in your AWS account. These are also known as control plane operations. Learn more about Management Events.
By default, a Trail
logs all management events. However, they can be configured to either be turned off, or to only
log 'Read' or 'Write' events.
The following code configures the Trail
to only track management events that are of type 'Read'.
Trail trail = Trail.Builder.create(this, "CloudTrail") // ... .managementEvents(ReadWriteType.READ_ONLY) .build();
Data events provide information about the resource operations performed on or in a resource. These are also known
as data plane operations. Learn more about Data
Events.
By default, no data events are logged for a Trail
.
AWS CloudTrail supports data event logging for Amazon S3 objects and AWS Lambda functions.
The logAllS3DataEvents()
API configures the trail to log all S3 data events while the addS3EventSelector()
API can
be used to configure logging of S3 data events for specific buckets and specific object prefix. The following code
configures logging of S3 data events for fooBucket
and with object prefix bar/
.
import software.amazon.awscdk.services.s3.*; Bucket bucket; Trail trail = new Trail(this, "MyAmazingCloudTrail"); // Adds an event selector to the bucket foo trail.addS3EventSelector(List.of(S3EventSelector.builder() .bucket(bucket) .objectPrefix("bar/") .build()));
Similarly, the logAllLambdaDataEvents()
configures the trail to log all Lambda data events while the
addLambdaEventSelector()
API can be used to configure logging for specific Lambda functions. The following code
configures logging of Lambda data events for a specific Function.
Trail trail = new Trail(this, "MyAmazingCloudTrail"); Function amazingFunction = Function.Builder.create(this, "AnAmazingFunction") .runtime(Runtime.NODEJS_LATEST) .handler("hello.handler") .code(Code.fromAsset("lambda")) .build(); // Add an event selector to log data events for the provided Lambda functions. trail.addLambdaEventSelector(List.of(amazingFunction));
Organization Trail
It is possible to create a trail that will be applied to all accounts in an organization if the current account manages an organization.
To enable this, the property isOrganizationTrail
must be set. If this property is set and the current account does not manage an organization, the stack will fail to deploy.
Trail.Builder.create(this, "OrganizationTrail") .isOrganizationTrail(true) .build();
CloudTrail Insights
Set InsightSelector
to enable Insight.
Insights selector values can be ApiCallRateInsight
, ApiErrorRateInsight
, or both.
Trail.Builder.create(this, "Insights") .insightTypes(List.of(InsightType.API_CALL_RATE, InsightType.API_ERROR_RATE)) .build();
-
ClassDescriptionOptions for adding an event selector.A builder for
AddEventSelectorOptions
An implementation forAddEventSelectorOptions
Contains information about a returned CloudTrail channel.A fluent builder forCfnChannel
.Contains information about the destination receiving events.A builder forCfnChannel.DestinationProperty
An implementation forCfnChannel.DestinationProperty
Properties for defining aCfnChannel
.A builder forCfnChannelProps
An implementation forCfnChannelProps
Creates a new event data store.Advanced event selectors let you create fine-grained selectors for CloudTrail management and data events.A builder forCfnEventDataStore.AdvancedEventSelectorProperty
An implementation forCfnEventDataStore.AdvancedEventSelectorProperty
A single selector statement in an advanced event selector.A builder forCfnEventDataStore.AdvancedFieldSelectorProperty
An implementation forCfnEventDataStore.AdvancedFieldSelectorProperty
A fluent builder forCfnEventDataStore
.A JSON string that contains a list of Insights types that are logged on an event data store.A builder forCfnEventDataStore.InsightSelectorProperty
An implementation forCfnEventDataStore.InsightSelectorProperty
Properties for defining aCfnEventDataStore
.A builder forCfnEventDataStoreProps
An implementation forCfnEventDataStoreProps
Attaches a resource-based permission policy to a CloudTrail channel that is used for an integration with an event source outside of AWS .A fluent builder forCfnResourcePolicy
.Properties for defining aCfnResourcePolicy
.A builder forCfnResourcePolicyProps
An implementation forCfnResourcePolicyProps
Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.Advanced event selectors let you create fine-grained selectors for CloudTrail management and data events.A builder forCfnTrail.AdvancedEventSelectorProperty
An implementation forCfnTrail.AdvancedEventSelectorProperty
A single selector statement in an advanced event selector.A builder forCfnTrail.AdvancedFieldSelectorProperty
An implementation forCfnTrail.AdvancedFieldSelectorProperty
A fluent builder forCfnTrail
.You can configure theDataResource
in anEventSelector
to log data events for the following three resource types:.A builder forCfnTrail.DataResourceProperty
An implementation forCfnTrail.DataResourceProperty
Use event selectors to further specify the management and data event settings for your trail.A builder forCfnTrail.EventSelectorProperty
An implementation forCfnTrail.EventSelectorProperty
A JSON string that contains a list of Insights types that are logged on a trail.A builder forCfnTrail.InsightSelectorProperty
An implementation forCfnTrail.InsightSelectorProperty
Properties for defining aCfnTrail
.A builder forCfnTrailProps
An implementation forCfnTrailProps
Resource type for a data event.Util element for InsightSelector.Types of management event sources that can be excluded.Types of events that CloudTrail can log.Selecting an S3 bucket and an optional prefix to be logged for data events.A builder forS3EventSelector
An implementation forS3EventSelector
Cloud trail allows you to log events that happen in your AWS account For example:.A fluent builder forTrail
.Properties for an AWS CloudTrail trail.A builder forTrailProps
An implementation forTrailProps