Merge branch 'master' into nija-at/cognito-userpool-idp

.gitignore

@@ -1,5 +1,7 @@
 # VSCode extension
-.vscode/
+
+# Store launch config in repo but not settings
+.vscode/settings.json
 /.favorites.json
 
 # TypeScript incremental build states

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      // Has convenient settings for attaching to a NodeJS process for debugging purposes
+      // that are NOT the default and otherwise every developers has to configure for
+      // themselves again and again.
+      "type": "node",
+      "request": "attach",
+      "name": "Attach to NodeJS",
+      // If we don't do this, every step-into into an async function call will go into
+      // NodeJS internals which are hard to step out of.
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      // Saves some button-pressing latency on attaching
+      "stopOnEntry": false
+    }
+  ]
+}

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.42.1](https://github.com/aws/aws-cdk/compare/v1.42.0...v1.42.1) (2020-06-01)
+
+
+### Bug Fixes
+
+* **lambda:** `SingletonFunction.grantInvoke()` API fails with error 'No child with id' ([#8296](https://github.com/aws/aws-cdk/issues/8296)) ([b4e264c](https://github.com/aws/aws-cdk/commit/b4e264c024bc58053412be1343bed6458628f7cb)), closes [#8240](https://github.com/aws/aws-cdk/issues/8240)
+
 ## [1.42.0](https://github.com/aws/aws-cdk/compare/v1.41.0...v1.42.0) (2020-05-27)
 
 

CONTRIBUTING.md

@@ -43,6 +43,7 @@ and let us know if it's not up-to-date (even better, submit a PR with your  corr
 - [Troubleshooting](#troubleshooting)
 - [Debugging](#debugging)
   - [Connecting the VS Code Debugger](#connecting-the-vs-code-debugger)
+  - [Run a CDK unit test in the debugger](#run-a-cdk-unit-test-in-the-debugger)
 - [Related Repositories](#related-repositories)
 
 ## Getting Started
@@ -234,7 +235,7 @@ BREAKING CHANGE: Description of what broke and how to achieve this behavior now
 ### Step 5: Pull Request
 
 * Push to a GitHub fork or to a branch (naming convention: `<user>/<feature-bug-name>`)
-* Submit a Pull Requests on GitHub and assign the PR for a review to the "awslabs/aws-cdk" team.
+* Submit a Pull Request on GitHub. A reviewer will later be assigned by the maintainers.
 * Please follow the PR checklist written below. We trust our contributors to self-check, and this helps that process!
 * Discuss review comments and iterate until you get at least one “Approve”. When iterating, push new commits to the
   same branch. Usually all these are going to be squashed when you merge to master. The commit messages should be hints
@@ -327,7 +328,7 @@ All packages in the repo use a standard base configuration found at [eslintrc.js
 This can be customized for any package by modifying the `.eslintrc` file found at its root.
 
 If you're using the VS Code and would like to see eslint violations on it, install the [eslint
-extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint). 
+extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
 
 #### pkglint
 
@@ -910,6 +911,24 @@ To debug your CDK application along with the CDK repository,
 6. The debug view, should now have a launch configuration called 'Debug hello-cdk' and launching that will start the debugger.
 7. Any time you modify the CDK app or any of the CDK modules, they need to be re-built and depending on the change the `link-all.sh` script from step#2, may need to be re-run. Only then, would VS code recognize the change and potentially the breakpoint.
 
+### Run a CDK unit test in the debugger
+
+If you want to run the VSCode debugger on unit tests of the CDK project
+itself, do the following:
+
+1. Set a breakpoint inside your unit test.
+2. In your terminal, depending on the type of test, run either:
+
+```
+# (For tests names test.xxx.ts)
+$ node --inspect-brk /path/to/aws-cdk/node_modules/.bin/nodeunit -t 'TESTNAME'
+
+# (For tests names xxxx.test.ts)
+$ node --inspect-brk /path/to/aws-cdk/node_modules/.bin/jest -i -t 'TESTNAME'
+```
+
+3. On the `Run` pane of VSCode, select the run configuration **Attach to NodeJS** and click the button.
+
 ## Related Repositories
 
 * [Samples](https://github.com/aws-samples/aws-cdk-examples): includes sample code in multiple languages

lerna.json

@@ -10,5 +10,5 @@
     "tools/*"
   ],
   "rejectCycles": "true",
-  "version": "1.42.0"
+  "version": "1.42.1"
 }

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);
     }