feat(cloudtrail): create cloudwatch event without needing to create a…

… Trail (#8076)

closes #6716

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

@@ -92,4 +92,33 @@ trail.addLambdaEventSelector(["arn:aws:lambda"]);
 
 // Add an event selector to log data events for the provided Lambda functions.
 trail.addLambdaEventSelector([lambdaFunction.functionArn]);
-```
+```
+
+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
+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';
+
+const myFunctionHandler = new lambda.Function(this, 'MyFunction', {
+  code: lambda.Code.fromAsset('resource/myfunction');
+  runtime: lambda.Runtime.NODEJS_12_X,
+  handler: 'index.handler',
+});
+
+const eventRule = Trail.onEvent(this, 'MyCloudWatchEvent', {
+  target: new eventTargets.LambdaFunction(myFunctionHandler),
+});
+
+eventRule.addEventPattern({
+  account: '123456789012',
+  source: 'aws.s3',
+});
+```

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

@@ -140,6 +140,23 @@ export enum ReadWriteType {
  */
 export class Trail extends Resource {
 
+  /**
+   * Create an event rule for when an event is recorded by any Trail in the account.
+   *
+   * Note that the event doesn't necessarily have to come from this Trail, it can
+   * be captured from any one.
+   *
+   * Be sure to filter the event further down using an event pattern.
+   */
+  public static onEvent(scope: Construct, id: string, options: events.OnEventOptions = {}): events.Rule {
+    const rule = new events.Rule(scope, id, options);
+    rule.addTarget(options.target);
+    rule.addEventPattern({
+      detailType: ['AWS API Call via CloudTrail'],
+    });
+    return rule;
+  }
+
   /**
    * ARN of the CloudTrail trail
    * i.e. arn:aws:cloudtrail:us-east-2:123456789012:trail/myCloudTrail
@@ -313,14 +330,11 @@ export class Trail extends Resource {
    * be captured from any one.
    *
    * Be sure to filter the event further down using an event pattern.
+   *
+   * @deprecated - use Trail.onEvent()
    */
   public onCloudTrailEvent(id: string, options: events.OnEventOptions = {}): events.Rule {
-    const rule = new events.Rule(this, id, options);
-    rule.addTarget(options.target);
-    rule.addEventPattern({
-      detailType: ['AWS API Call via CloudTrail'],
-    });
-    return rule;
+    return Trail.onEvent(this, id, options);
   }
 }
 

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

@@ -93,6 +93,11 @@
     "@aws-cdk/core": "0.0.0",
     "constructs": "^3.0.2"
   },
+  "awslint": {
+    "exclude": [
+      "events-method-signature:@aws-cdk/aws-cloudtrail.Trail.onEvent"
+    ]
+  },
   "engines": {
     "node": ">= 10.13.0 <13 || >=13.7.0"
   },

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

@@ -323,4 +323,37 @@ describe('cloudtrail', () => {
       });
     });
   });
+
+  describe('onEvent', () => {
+    test('add an event rule', () => {
+      // GIVEN
+      const stack = getTestStack();
+
+      // WHEN
+      Trail.onEvent(stack, 'DoEvents', {
+        target: {
+          bind: () => ({
+            id: '',
+            arn: 'arn',
+          }),
+        },
+      });
+
+      // THEN
+      expect(stack).toHaveResource('AWS::Events::Rule', {
+        EventPattern: {
+          'detail-type': [
+            'AWS API Call via CloudTrail',
+          ],
+        },
+        State: 'ENABLED',
+        Targets: [
+          {
+            Arn: 'arn',
+            Id: 'Target0',
+          },
+        ],
+      });
+    });
+  });
 });