@aws-cdk/cloudtrail

AWS CloudTrail Construct Library

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

Example usage:

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

const trail = new CloudTrail(stack, '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 } from '@aws-cdk/cloudtrail';

const trail = new CloudTrail(stack, '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

For example - this logs all ReadWriteEvents for the magic-bucket bucket:

import { CloudTrail, DataResourceType, ReadWriteType  } from '@aws-cdk/cloudtrail';

const trail = new CloudTrail(stack, 'MyAmazingCloudTrail')

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

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

Reference

CloudTrail

class _aws-cdk_cloudtrail.CloudTrail(parent, name[, props])

Cloud trail allows you to log events that happen in your AWS account For example: import { CloudTrail } from @aws-cdk/ec2’ const cloudTrail = new CloudTrail(this, ‘MyTrail’);

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (CloudTrailProps or None) –
addS3EventSelector(prefixes, readWriteType)

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) –
  • readWriteType (ReadWriteType) – the configuration type to log for this data event Eg, ReadWriteType.ReadOnly will only log “read” events for S3 objects that match a filter)
cloudTrailArn
Type:TrailArn (readonly)

CloudTrailProps (interface)

class _aws-cdk_cloudtrail.CloudTrailProps
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 or None
isMultiRegionTrail

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

Type:boolean or 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:string or None
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 or None
sendToCloudWatchLogs

If CloudTrail pushes logs to CloudWatch Logs in addition to S3. Disabled for cost out of the box.

Type:boolean or None
cloudWatchLogsRetentionTimeDays

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

Type:number or None
kmsKey

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

Type:EncryptionKeyRef or None
snsTopic

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

Type:string or None
trailName

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

Type:string or None
s3KeyPrefix

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

Type:string or None

LogRetention (enum)

class _aws-cdk_cloudtrail.LogRetention
OneDay
ThreeDays
FiveDays
OneWeek
TwoWeeks
OneMonth
TwoMonths
ThreeMonths
FourMonths
FiveMonths
HalfYear
OneYear
FourHundredDays
EighteenMonths
TwoYears
FiveYears
TenYears

ReadWriteType (enum)

class _aws-cdk_cloudtrail.ReadWriteType
ReadOnly
WriteOnly
All