Merge branch 'master' into c9-repo-support

Author: pahud

packages/@aws-cdk/assets/package.json

@@ -65,7 +65,7 @@
   "devDependencies": {
     "@aws-cdk/assert": "0.0.0",
     "@types/nodeunit": "^0.0.31",
-    "@types/sinon": "^9.0.3",
+    "@types/sinon": "^9.0.4",
     "aws-cdk": "0.0.0",
     "cdk-build-tools": "0.0.0",
     "cdk-integ-tools": "0.0.0",

packages/@aws-cdk/aws-cloudtrail/README.md

@@ -13,101 +13,82 @@
 ---
 <!--END STABILITY BANNER-->
 
-Add a CloudTrail construct - for ease of setting up CloudTrail logging in your account
+## Trail
 
-Example usage:
+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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html).
 
-```ts
-import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
+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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html).
+The following code creates a simple CloudTrail for your account -
 
+```ts
 const trail = new cloudtrail.Trail(this, 'CloudTrail');
 ```
 
-You can instantiate the CloudTrail construct with no arguments - this will by default:
+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.
 
- * 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
+## Log File Validation
 
-You can override any of these properties using the `CloudTrailProps` configuraiton object.
+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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-validation-intro.html).
 
-For example, to log to CloudWatch Logs
+This is enabled on the `Trail` construct by default, but can be turned off by setting `enableFileValidation` to `false`.
 
 ```ts
-
-import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
-
 const trail = new cloudtrail.Trail(this, 'CloudTrail', {
-  sendToCloudWatchLogs: true
+  enableFileValidation: false,
 });
 ```
 
-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
-via the `cloudWatchLogsRetention` property. If you would like to specify the log group explicitly,
-use the `cloudwatchLogGroup` property.
+## Notifications
 
-For using CloudTrail event selector to log specific S3 events,
-you can use the `CloudTrailProps` configuration object.
-Example:
+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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html).
+The following code configures an SNS topic to be notified -
 
 ```ts
-import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
+const topic = new sns.Topic(this, 'TrailTopic');
+const trail = new cloudtrail.Trail(this, 'CloudTrail', {
+  snsTopic: topic,
+});
+```
 
-const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
+## Service Integrations
 
-// Adds an event selector to the bucket magic-bucket.
-// By default, this includes management events and all operations (Read + Write)
-trail.logAllS3DataEvents();
+Besides sending trail events to S3, they can also be configured to notify other AWS services -
 
-// Adds an event selector to the bucket foo
-trail.addS3EventSelector([{
-  bucket: fooBucket // 'fooBucket' is of type s3.IBucket
-}]);
-```
+### Amazon CloudWatch Logs
 
-For using CloudTrail event selector to log events about Lambda
-functions, you can use `addLambdaEventSelector`.
+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.
 
 ```ts
-import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
-import * as lambda from '@aws-cdk/aws-lambda';
-
-const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
-const lambdaFunction = new lambda.Function(stack, 'AnAmazingFunction', {
-  runtime: lambda.Runtime.NODEJS_10_X,
-  handler: "hello.handler",
-  code: lambda.Code.fromAsset("lambda"),
+const trail = new cloudtrail.Trail(this, 'CloudTrail', {
+  sendToCloudWatchLogs: true,
+  cloudWatchLogsRetention: logs.RetentionDays.FOUR_MONTHS, 
 });
+```
 
-// Add an event selector to log data events for all functions in the account.
-trail.logAllLambdaDataEvents();
+If you would like to use a specific log group instead, this can be configured via `cloudwatchLogGroup`.
 
-// Add an event selector to log data events for the provided Lambda functions.
-trail.addLambdaEventSelector([lambdaFunction.functionArn]);
-```
+### Amazon EventBridge
 
-Using the `Trail.onEvent()` API, an EventBridge rule can be created that gets triggered for
-every event logged in CloudTrail.
-To only use the events that are of interest, either from a particular service, specific account or
-time range, they can be filtered down using the APIs available in `aws-events`. The following code
-filters events for S3 from a specific AWS account and triggers a lambda function. See [Events delivered via
+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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html#events-for-services-not-listed)
 to learn more about the event structure for events from CloudTrail.
 
-```ts
-import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
-import * as eventTargets from '@aws-cdk/aws-events-targets';
-import * as lambda from '@aws-cdk/aws-lambda';
+The following code filters events for S3 from a specific AWS account and triggers a lambda function.
 
+```ts
 const myFunctionHandler = new lambda.Function(this, 'MyFunction', {
   code: lambda.Code.fromAsset('resource/myfunction');
   runtime: lambda.Runtime.NODEJS_12_X,
@@ -123,3 +104,84 @@ eventRule.addEventPattern({
   source: 'aws.s3',
 });
 ```
+
+## 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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-regional-and-global-services)
+and about the [`IsMultiRegion`
+property](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-ismultiregiontrail).
+
+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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-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` -
+
+```ts
+const trail = new cloudtrail.Trail(this, 'CloudTrail', {
+  // ...
+  isMultiRegionTrail: false,
+  includeGlobalServiceEvents: false,
+});
+```
+
+## 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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-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'.
+
+```ts
+const trail = new cloudtrail.Trail(this, 'CloudTrail', {
+  // ...
+  managementEvents: ReadWriteType.READ_ONLY,
+});
+```
+
+**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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-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/`.
+
+```ts
+import * as cloudtrail from '@aws-cdk/aws-cloudtrail';
+
+const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
+
+// Adds an event selector to the bucket foo
+trail.addS3EventSelector([{
+  bucket: fooBucket, // 'fooBucket' is of type s3.IBucket
+  objectPrefix: 'bar/',
+}]);
+```
+
+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.
+
+```ts
+const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
+const amazingFunction = new lambda.Function(stack, 'AnAmazingFunction', {
+  runtime: lambda.Runtime.NODEJS_10_X,
+  handler: "hello.handler",
+  code: lambda.Code.fromAsset("lambda"),
+});
+
+// Add an event selector to log data events for the provided Lambda functions.
+trail.addLambdaEventSelector([ lambdaFunction ]);
+```

packages/@aws-cdk/aws-cloudtrail/lib/cloudtrail.ts

@@ -41,7 +41,7 @@ export interface TrailProps {
    *
    * @param managementEvents the management configuration type to log
    *
-   * @default - Management events will not be logged.
+   * @default ReadWriteType.ALL
    */
   readonly managementEvents?: ReadWriteType;
 
@@ -131,7 +131,12 @@ export enum ReadWriteType {
   /**
    * All events
    */
-  ALL = 'All'
+  ALL = 'All',
+
+  /**
+   * No events
+   */
+  NONE = 'None',
 }
 
 /**
@@ -235,10 +240,17 @@ export class Trail extends Resource {
     }
 
     if (props.managementEvents) {
-      const managementEvent = {
-        includeManagementEvents: true,
-        readWriteType: props.managementEvents,
-      };
+      let managementEvent;
+      if (props.managementEvents === ReadWriteType.NONE) {
+        managementEvent = {
+          includeManagementEvents: false,
+        };
+      } else {
+        managementEvent = {
+          includeManagementEvents: true,
+          readWriteType: props.managementEvents,
+        };
+      }
       this.eventSelectors.push(managementEvent);
     }
 

packages/@aws-cdk/aws-cloudtrail/test/cloudtrail.test.ts

@@ -397,6 +397,22 @@ describe('cloudtrail', () => {
           ],
         });
       });
+
+      test('managementEvents set to None correctly turns off management events', () => {
+        const stack = getTestStack();
+
+        new Trail(stack, 'MyAmazingCloudTrail', {
+          managementEvents: ReadWriteType.NONE,
+        });
+
+        expect(stack).toHaveResourceLike('AWS::CloudTrail::Trail', {
+          EventSelectors: [
+            {
+              IncludeManagementEvents: false,
+            },
+          ],
+        });
+      });
     });
   });
 

packages/@aws-cdk/aws-events-targets/README.md

@@ -22,6 +22,7 @@ Currently supported are:
 * Start a StepFunctions state machine
 * Queue a Batch job
 * Make an AWS API call
+* Put a record to a Kinesis stream
 
 See the README of the `@aws-cdk/aws-events` library for more information on
 CloudWatch Events.

packages/@aws-cdk/aws-events-targets/lib/index.ts

@@ -8,3 +8,4 @@ export * from './lambda';
 export * from './ecs-task-properties';
 export * from './ecs-task';
 export * from './state-machine';
+export * from './kinesis-stream';

packages/@aws-cdk/aws-events-targets/lib/kinesis-stream.ts

@@ -0,0 +1,63 @@
+import * as events from '@aws-cdk/aws-events';
+import * as iam from '@aws-cdk/aws-iam';
+import * as kinesis from '@aws-cdk/aws-kinesis';
+import { singletonEventRole } from './util';
+
+/**
+ * Customize the Kinesis Stream Event Target
+ */
+export interface KinesisStreamProps {
+  /**
+   * Partition Key Path for records sent to this stream
+   *
+   * @default - eventId as the partition key
+   */
+  readonly partitionKeyPath?: string;
+
+  /**
+   * The message to send to the stream.
+   *
+   * Must be a valid JSON text passed to the target stream.
+   *
+   * @default - the entire CloudWatch event
+   */
+  readonly message?: events.RuleTargetInput;
+
+}
+
+/**
+ * Use a Kinesis Stream as a target for AWS CloudWatch event rules.
+ *
+ * @example
+ *
+ *    // put to a Kinesis stream every time code is committed
+ *    // to a CodeCommit repository
+ *    repository.onCommit(new targets.KinesisStream(stream));
+ *
+ */
+export class KinesisStream implements events.IRuleTarget {
+
+  constructor(private readonly stream: kinesis.IStream, private readonly props: KinesisStreamProps = {}) {
+  }
+
+  /**
+   * Returns a RuleTarget that can be used to trigger this Kinesis Stream as a
+   * result from a CloudWatch event.
+   */
+  public bind(_rule: events.IRule, _id?: string): events.RuleTargetConfig {
+    const policyStatements = [new iam.PolicyStatement({
+      actions: ['kinesis:PutRecord', 'kinesis:PutRecords'],
+      resources: [this.stream.streamArn],
+    })];
+
+    return {
+      id: '',
+      arn: this.stream.streamArn,
+      role: singletonEventRole(this.stream, policyStatements),
+      input: this.props.message,
+      targetResource: this.stream,
+      kinesisParameters: this.props.partitionKeyPath ? { partitionKeyPath: this.props.partitionKeyPath } : undefined,
+    };
+  }
+
+}