This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

@aws-cdk/aws-cloudtrail

AWS CloudTrail Construct Library

Add a CloudTrail construct - for ease of setting up CloudTrail logging in your account

Example usage:

import cloudtrail = require('@aws-cdk/aws-cloudtrail');

const trail = new cloudtrail.CloudTrail(this, 'CloudTrail');

You can instantiate the CloudTrail construct with no arguments - this will by default:

* Create a new S3 Bucket and associated Policy that allows CloudTrail to write to it
* Create a CloudTrail with the following configuration:
    * Logging Enabled
    * Log file validation enabled
    * Multi Region set to true
    * Global Service Events set to true
    * The created S3 bucket
    * CloudWatch Logging Disabled
    * No SNS configuartion
    * No tags
    * No fixed name

You can override any of these properties using the CloudTrailProps configuraiton object.

For example, to log to CloudWatch Logs

import cloudtrail = require('@aws-cdk/aws-cloudtrail');

const trail = new cloudtrail.CloudTrail(this, 'CloudTrail', {
  sendToCloudWatchLogs: true
});

This creates the same setup as above - but also logs events to a created CloudWatch Log stream. By default, the created log group has a retention period of 365 Days, but this is also configurable.

For using CloudTrail event selector to log specific S3 events, you can use the CloudTrailProps configuration object. Example:

import cloudtrail = require('@aws-cdk/aws-cloudtrail');

const trail = new cloudtrail.CloudTrail(this, 'MyAmazingCloudTrail');

// Adds an event selector to the bucket magic-bucket.
// By default, this includes management events and all operations (Read + Write)
trail.addS3EventSelector(["arn:aws:s3:::magic-bucket/"]);

// Adds an event selector to the bucket foo, with a specific configuration
trail.addS3EventSelector(["arn:aws:s3:::foo/"], {
  includeManagementEvents: false,
  readWriteType: ReadWriteType.All,
});

Reference

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.AWS.CloudTrail" Version="0.25.3" />

dotnet:

dotnet add package Amazon.CDK.AWS.CloudTrail --version 0.25.3

packages.config:

<package id="Amazon.CDK.AWS.CloudTrail" version="0.25.3" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:cloudtrail:jar:0.25.3'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="cloudtrail" rev="0.25.3"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>cloudtrail</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:cloudtrail:0.25.3'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='cloudtrail', version='0.25.3')
)

View in NPM

npm:

$ npm i @aws-cdk/aws-cloudtrail@0.25.3

package.json:

{
  "@aws-cdk/aws-cloudtrail": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-cloudtrail@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/aws-cloudtrail@0.25.3

package.json:

{
  "@aws-cdk/aws-cloudtrail": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-cloudtrail@0.25.3

AddS3EventSelectorOptions (interface)

class @aws-cdk/aws-cloudtrail.AddS3EventSelectorOptions

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.AddS3EventSelectorOptions;
// AddS3EventSelectorOptions is an interface
import { AddS3EventSelectorOptions } from '@aws-cdk/aws-cloudtrail';

Options for adding an S3 event selector.

includeManagementEvents

Specifies whether the event selector includes management events for the trail.

Type:boolean (optional)
Default:true
readWriteType

Specifies whether to log read-only events, write-only events, or all events.

Type:ReadWriteType (optional)
Default:ReadWriteType.All

CfnTrail

class @aws-cdk/aws-cloudtrail.CfnTrail(scope, id, props)

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CfnTrail;
const { CfnTrail } = require('@aws-cdk/aws-cloudtrail');
import { CfnTrail } from '@aws-cdk/aws-cloudtrail';
Extends:

@aws-cdk/cdk.Resource

Parameters:
renderProperties(properties) → string => any

Overrides @aws-cdk/cdk.Resource.renderProperties()

Protected method

Parameters:properties (any) –
Return type:string => any
resourceTypeName

The CloudFormation resource type name for this resource class.

Type:string (readonly) (static)
propertyOverrides
Type:CfnTrailProps (readonly)
tags

The TagManager handles setting, removing and formatting tags

Tags should be managed either passing them as properties during

initiation or by calling methods on this object. If both techniques are

used only the tags from the TagManager will be used. Tag (aspect)

will use the manager.

Type:@aws-cdk/cdk.TagManager (readonly)
trailArn
Type:string (readonly)
trailName
Type:string (readonly)
trailSnsTopicArn
Type:string (readonly)
class DataResourceProperty

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CfnTrail.DataResourceProperty;
// CfnTrail.DataResourceProperty is an interface
import { CfnTrail.DataResourceProperty } from '@aws-cdk/aws-cloudtrail';
type

CfnTrail.DataResourceProperty.Type

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudtrail-trail-dataresource.html#cfn-cloudtrail-trail-dataresource-type

Type:string
values

CfnTrail.DataResourceProperty.Values

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudtrail-trail-dataresource.html#cfn-cloudtrail-trail-dataresource-values

Type:@aws-cdk/cdk.Token or (string or @aws-cdk/cdk.Token)[] (optional)
class EventSelectorProperty

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CfnTrail.EventSelectorProperty;
// CfnTrail.EventSelectorProperty is an interface
import { CfnTrail.EventSelectorProperty } from '@aws-cdk/aws-cloudtrail';
dataResources

CfnTrail.EventSelectorProperty.DataResources

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudtrail-trail-eventselector.html#cfn-cloudtrail-trail-eventselector-dataresources

Type:@aws-cdk/cdk.Token or (@aws-cdk/cdk.Token or DataResourceProperty)[] (optional)
includeManagementEvents

CfnTrail.EventSelectorProperty.IncludeManagementEvents

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudtrail-trail-eventselector.html#cfn-cloudtrail-trail-eventselector-includemanagementevents

Type:boolean or @aws-cdk/cdk.Token (optional)
readWriteType

CfnTrail.EventSelectorProperty.ReadWriteType

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudtrail-trail-eventselector.html#cfn-cloudtrail-trail-eventselector-readwritetype

Type:string (optional)
toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)
ref

Inherited from @aws-cdk/cdk.Referenceable

Returns a token to a CloudFormation { Ref } that references this entity based on it’s logical ID.

Type:string (readonly)
addDeletionOverride(path)

Inherited from @aws-cdk/cdk.Resource

Syntactic sugar for addOverride(path, undefined).

Parameters:path (string) – The path of the value to delete
addDependsOn(resource)

Inherited from @aws-cdk/cdk.Resource

Indicates that this resource depends on another resource and cannot be provisioned

unless the other resource has been successfully provisioned.

Parameters:resource (@aws-cdk/cdk.Resource) –
addOverride(path, value)

Inherited from @aws-cdk/cdk.Resource

Adds an override to the synthesized CloudFormation resource. To add a

property override, either use addPropertyOverride or prefix path with

“Properties.” (i.e. Properties.TopicName).

Parameters:
  • path (string) – The path of the property, you can use dot notation to override values in complex types. Any intermdediate keys will be created as needed.
  • value (any) – The value. Could be primitive or complex.
addPropertyDeletionOverride(propertyPath)

Inherited from @aws-cdk/cdk.Resource

Adds an override that deletes the value of a property from the resource definition.

Parameters:propertyPath (string) – The path to the property.
addPropertyOverride(propertyPath, value)

Inherited from @aws-cdk/cdk.Resource

Adds an override to a resource property.

Syntactic sugar for addOverride(“Properties.<…>”, value).

Parameters:
  • propertyPath (string) – The path of the property
  • value (any) – The value
getAtt(attributeName) → @aws-cdk/cdk.CfnReference

Inherited from @aws-cdk/cdk.Resource

Returns a token for an runtime attribute of this resource.

Ideally, use generated attribute accessors (e.g. resource.arn), but this can be used for future compatibility

in case there is no generated attribute.

Parameters:attributeName (string) – The name of the attribute.
Return type:@aws-cdk/cdk.CfnReference
toCloudFormation() → json

Inherited from @aws-cdk/cdk.Resource

Emits CloudFormation for this resource.

Return type:json
options

Inherited from @aws-cdk/cdk.Resource

Options for this resource, such as condition, update policy etc.

Type:@aws-cdk/cdk.ResourceOptions (readonly)
properties

Inherited from @aws-cdk/cdk.Resource

AWS resource properties.

This object is rendered via a call to “renderProperties(this.properties)”.

Protected property

Type:any (readonly)
resourceType

Inherited from @aws-cdk/cdk.Resource

AWS resource type.

Type:string (readonly)
untypedPropertyOverrides

Inherited from @aws-cdk/cdk.Resource

AWS resource property overrides.

During synthesis, the method “renderProperties(this.overrides)” is called

with this object, and merged on top of the output of

“renderProperties(this.properties)”.

Derived classes should expose a strongly-typed version of this object as

a public property called propertyOverrides.

Protected property

Type:any (readonly)
overrideLogicalId(newLogicalId)

Inherited from @aws-cdk/cdk.StackElement

Overrides the auto-generated logical ID with a specific ID.

Parameters:newLogicalId (string) – The new logical ID to use for this stack element.
prepare()

Inherited from @aws-cdk/cdk.StackElement

Automatically detect references in this StackElement

Protected method

creationStackTrace

Inherited from @aws-cdk/cdk.StackElement

Type:string[] (readonly)
logicalId

Inherited from @aws-cdk/cdk.StackElement

The logical ID for this CloudFormation stack element. The logical ID of the element

is calculated from the path of the resource node in the construct tree.

To override this value, use overrideLogicalId(newLogicalId).

Type:string (readonly)
stackPath

Inherited from @aws-cdk/cdk.StackElement

Return the path with respect to the stack

Type:string (readonly)

CfnTrailProps (interface)

class @aws-cdk/aws-cloudtrail.CfnTrailProps

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CfnTrailProps;
// CfnTrailProps is an interface
import { CfnTrailProps } from '@aws-cdk/aws-cloudtrail';
isLogging

AWS::CloudTrail::Trail.IsLogging

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-islogging

Type:boolean or @aws-cdk/cdk.Token
s3BucketName

AWS::CloudTrail::Trail.S3BucketName

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-s3bucketname

Type:string
cloudWatchLogsLogGroupArn

AWS::CloudTrail::Trail.CloudWatchLogsLogGroupArn

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-cloudwatchlogsloggrouparn

Type:string (optional)
cloudWatchLogsRoleArn

AWS::CloudTrail::Trail.CloudWatchLogsRoleArn

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-cloudwatchlogsrolearn

Type:string (optional)
enableLogFileValidation

AWS::CloudTrail::Trail.EnableLogFileValidation

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-enablelogfilevalidation

Type:boolean or @aws-cdk/cdk.Token (optional)
eventSelectors

AWS::CloudTrail::Trail.EventSelectors

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-eventselectors

Type:@aws-cdk/cdk.Token or (@aws-cdk/cdk.Token or EventSelectorProperty)[] (optional)
includeGlobalServiceEvents

AWS::CloudTrail::Trail.IncludeGlobalServiceEvents

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-includeglobalserviceevents

Type:boolean or @aws-cdk/cdk.Token (optional)
isMultiRegionTrail

AWS::CloudTrail::Trail.IsMultiRegionTrail

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-ismultiregiontrail

Type:boolean or @aws-cdk/cdk.Token (optional)
kmsKeyId

AWS::CloudTrail::Trail.KMSKeyId

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-kmskeyid

Type:string (optional)
s3KeyPrefix

AWS::CloudTrail::Trail.S3KeyPrefix

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-s3keyprefix

Type:string (optional)
snsTopicName

AWS::CloudTrail::Trail.SnsTopicName

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-snstopicname

Type:string (optional)
tags

AWS::CloudTrail::Trail.Tags

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-tags

Type:@aws-cdk/cdk.Token or (@aws-cdk/cdk.Token or @aws-cdk/cdk.CfnTag)[] (optional)
trailName

AWS::CloudTrail::Trail.TrailName

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-trailname

Type:string (optional)

CloudTrail

class @aws-cdk/aws-cloudtrail.CloudTrail(scope, id[, props])

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CloudTrail;
const { CloudTrail } = require('@aws-cdk/aws-cloudtrail');
import { CloudTrail } from '@aws-cdk/aws-cloudtrail';

Cloud trail allows you to log events that happen in your AWS account

For example:

import { CloudTrail } from @aws-cdk/aws-cloudtrail

const cloudTrail = new CloudTrail(this, ‘MyTrail’);

Extends:

@aws-cdk/cdk.Construct

Parameters:
addS3EventSelector(prefixes[, options])

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method adds an S3 Data Event Selector for filtering events that match S3 operations.

Data events: These events provide insight into the resource operations performed on or within a resource.

These are also known as data plane operations.

Parameters:
  • prefixes (string[]) – the list of object ARN prefixes to include in logging (maximum 250 entries).
  • options (AddS3EventSelectorOptions (optional)) – the options to configure logging of management and data events.
cloudTrailArn
Type:string (readonly)
prepare()

Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

CloudTrailProps (interface)

class @aws-cdk/aws-cloudtrail.CloudTrailProps

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.CloudTrailProps;
// CloudTrailProps is an interface
import { CloudTrailProps } from '@aws-cdk/aws-cloudtrail';
cloudWatchLogsRetentionTimeDays

How long to retain logs in CloudWatchLogs. Ignored if sendToCloudWatchLogs is false

Type:LogRetention (optional)
Default:LogRetention.OneYear
enableFileValidation

To determine whether a log file was modified, deleted, or unchanged after CloudTrail delivered it,

you can use CloudTrail log file integrity validation.

This feature is built using industry standard algorithms: SHA-256 for hashing and SHA-256 with RSA for digital signing.

This makes it computationally infeasible to modify, delete or forge CloudTrail log files without detection.

You can use the AWS CLI to validate the files in the location where CloudTrail delivered them.

Type:boolean (optional)
Default:true
includeGlobalServiceEvents

For most services, events are recorded in the region where the action occurred.

For global services such as AWS Identity and Access Management (IAM), AWS STS, Amazon CloudFront, and Route 53,

events are delivered to any trail that includes global services, and are logged as occurring in US East (N. Virginia) Region.

Type:boolean (optional)
Default:true
isMultiRegionTrail

Whether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account.

Type:boolean (optional)
Default:true
kmsKey

The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.

Type:@aws-cdk/aws-kms.IEncryptionKey (optional)
Default:none
managementEvents

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails.

Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

This method sets the management configuration for this trail.

Management events provide insight into management operations that are performed on resources in your AWS account.

These are also known as control plane operations.

Management events can also include non-API events that occur in your account.

For example, when a user logs in to your account, CloudTrail logs the ConsoleLogin event.

If managementEvents is undefined, we’ll not log management events by default.

Type:ReadWriteType (optional)
s3KeyPrefix

An Amazon S3 object key prefix that precedes the name of all log files.

Type:string (optional)
Default:none
sendToCloudWatchLogs

If CloudTrail pushes logs to CloudWatch Logs in addition to S3.

Disabled for cost out of the box.

Type:boolean (optional)
Default:false
snsTopic

The name of an Amazon SNS topic that is notified when new log files are published.

Type:string (optional)
Default:none
trailName

The name of the trail. We recoomend customers do not set an explicit name.

Type:string (optional)
Default:the CloudFormation generated neme

LogRetention (enum)

class @aws-cdk/aws-cloudtrail.LogRetention

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.LogRetention;
const { LogRetention } = require('@aws-cdk/aws-cloudtrail');
import { LogRetention } from '@aws-cdk/aws-cloudtrail';
OneDay
ThreeDays
FiveDays
OneWeek
TwoWeeks
OneMonth
TwoMonths
ThreeMonths
FourMonths
FiveMonths
HalfYear
OneYear
FourHundredDays
EighteenMonths
TwoYears
FiveYears
TenYears

ReadWriteType (enum)

class @aws-cdk/aws-cloudtrail.ReadWriteType

Language-specific names:

using Amazon.CDK.AWS.CloudTrail;
import software.amazon.awscdk.services.cloudtrail.ReadWriteType;
const { ReadWriteType } = require('@aws-cdk/aws-cloudtrail');
import { ReadWriteType } from '@aws-cdk/aws-cloudtrail';
ReadOnly
WriteOnly
All