diff --git a/packages/@aws-cdk/aws-ec2/README.md b/packages/@aws-cdk/aws-ec2/README.md index a9ac3794580b4..eecc6f3857da4 100644 --- a/packages/@aws-cdk/aws-ec2/README.md +++ b/packages/@aws-cdk/aws-ec2/README.md @@ -994,6 +994,33 @@ instance.userData.addCommands( ); ``` +### Configuring Instance Metadata Service (IMDS) + +#### Toggling IMDSv1 + +You can configure [EC2 Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) options to either +allow both IMDSv1 and IMDSv2 or enforce IMDSv2 when interacting with the IMDS. + +To do this for a single `Instance`, you can use the `requireImdsv2` property. +The example below demonstrates IMDSv2 being required on a single `Instance`: + +```ts +new ec2.Instance(this, 'Instance', { + requireImdsv2: true, + // ... +}); +``` + +You can also use the either the `InstanceRequireImdsv2Aspect` for EC2 instances or the `LaunchTemplateRequireImdsv2Aspect` for EC2 launch templates +to apply the operation to multiple instances or launch templates, respectively. + +The following example demonstrates how to use the `InstanceRequireImdsv2Aspect` to require IMDSv2 for all EC2 instances in a stack: + +```ts +const aspect = new ec2.InstanceRequireImdsv2Aspect(); +Aspects.of(stack).add(aspect); +``` + ## VPC Flow Logs VPC Flow Logs is a feature that enables you to capture information about the IP traffic going to and from network interfaces in your VPC. Flow log data can be published to Amazon CloudWatch Logs and Amazon S3. After you've created a flow log, you can retrieve and view its data in the chosen destination. (). diff --git a/packages/@aws-cdk/aws-ec2/lib/aspects/index.ts b/packages/@aws-cdk/aws-ec2/lib/aspects/index.ts new file mode 100644 index 0000000000000..5685e9b46d036 --- /dev/null +++ b/packages/@aws-cdk/aws-ec2/lib/aspects/index.ts @@ -0,0 +1 @@ +export * from './require-imdsv2-aspect'; diff --git a/packages/@aws-cdk/aws-ec2/lib/aspects/require-imdsv2-aspect.ts b/packages/@aws-cdk/aws-ec2/lib/aspects/require-imdsv2-aspect.ts new file mode 100644 index 0000000000000..f1a5270f1fb08 --- /dev/null +++ b/packages/@aws-cdk/aws-ec2/lib/aspects/require-imdsv2-aspect.ts @@ -0,0 +1,150 @@ +import * as cdk from '@aws-cdk/core'; +import { CfnLaunchTemplate } from '../ec2.generated'; +import { Instance } from '../instance'; +import { LaunchTemplate } from '../launch-template'; + +/** + * Properties for `RequireImdsv2Aspect`. + */ +interface RequireImdsv2AspectProps { + /** + * Whether warning annotations from this Aspect should be suppressed or not. + * + * @default - false + */ + readonly suppressWarnings?: boolean; +} + +/** + * Base class for Aspect that makes IMDSv2 required. + */ +abstract class RequireImdsv2Aspect implements cdk.IAspect { + protected readonly suppressWarnings: boolean; + + constructor(props?: RequireImdsv2AspectProps) { + this.suppressWarnings = props?.suppressWarnings ?? false; + } + + abstract visit(node: cdk.IConstruct): void; + + /** + * Adds a warning annotation to a node, unless `suppressWarnings` is true. + * + * @param node The scope to add the warning to. + * @param message The warning message. + */ + protected warn(node: cdk.IConstruct, message: string) { + if (this.suppressWarnings !== true) { + cdk.Annotations.of(node).addWarning(`${RequireImdsv2Aspect.name} failed on node ${node.node.id}: ${message}`); + } + } +} + +/** + * Properties for `InstanceRequireImdsv2Aspect`. + */ +export interface InstanceRequireImdsv2AspectProps extends RequireImdsv2AspectProps { + /** + * Whether warnings that would be raised when an Instance is associated with an existing Launch Template + * should be suppressed or not. + * + * You can set this to `true` if `LaunchTemplateImdsAspect` is being used alongside this Aspect to + * suppress false-positive warnings because any Launch Templates associated with Instances will still be covered. + * + * @default - false + */ + readonly suppressLaunchTemplateWarning?: boolean; +} + +/** + * Aspect that applies IMDS configuration on EC2 Instance constructs. + * + * This aspect configures IMDS on an EC2 instance by creating a Launch Template with the + * IMDS configuration and associating that Launch Template with the instance. If an Instance + * is already associated with a Launch Template, a warning will (optionally) be added to the + * construct node and it will be skipped. + * + * To cover Instances already associated with Launch Templates, use `LaunchTemplateImdsAspect`. + */ +export class InstanceRequireImdsv2Aspect extends RequireImdsv2Aspect { + private readonly suppressLaunchTemplateWarning: boolean; + + constructor(props?: InstanceRequireImdsv2AspectProps) { + super(props); + this.suppressLaunchTemplateWarning = props?.suppressLaunchTemplateWarning ?? false; + } + + visit(node: cdk.IConstruct): void { + if (!(node instanceof Instance)) { + return; + } + if (node.instance.launchTemplate !== undefined) { + this.warn(node, 'Cannot toggle IMDSv1 because this Instance is associated with an existing Launch Template.'); + return; + } + + const name = `${node.node.id}LaunchTemplate`; + const launchTemplate = new CfnLaunchTemplate(node, 'LaunchTemplate', { + launchTemplateData: { + metadataOptions: { + httpTokens: 'required', + }, + }, + launchTemplateName: name, + }); + node.instance.launchTemplate = { + launchTemplateName: name, + version: launchTemplate.getAtt('LatestVersionNumber').toString(), + }; + } + + protected warn(node: cdk.IConstruct, message: string) { + if (this.suppressLaunchTemplateWarning !== true) { + super.warn(node, message); + } + } +} + +/** + * Properties for `LaunchTemplateRequireImdsv2Aspect`. + */ +export interface LaunchTemplateRequireImdsv2AspectProps extends RequireImdsv2AspectProps {} + +/** + * Aspect that applies IMDS configuration on EC2 Launch Template constructs. + * + * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-launchtemplatedata-metadataoptions.html + */ +export class LaunchTemplateRequireImdsv2Aspect extends RequireImdsv2Aspect { + constructor(props?: LaunchTemplateRequireImdsv2AspectProps) { + super(props); + } + + visit(node: cdk.IConstruct): void { + if (!(node instanceof LaunchTemplate)) { + return; + } + + const launchTemplate = node.node.tryFindChild('Resource') as CfnLaunchTemplate; + const data = launchTemplate.launchTemplateData; + if (cdk.isResolvableObject(data)) { + this.warn(node, 'LaunchTemplateData is a CDK token.'); + return; + } + + const metadataOptions = (data as CfnLaunchTemplate.LaunchTemplateDataProperty).metadataOptions; + if (cdk.isResolvableObject(metadataOptions)) { + this.warn(node, 'LaunchTemplateData.MetadataOptions is a CDK token.'); + return; + } + + const newData: CfnLaunchTemplate.LaunchTemplateDataProperty = { + ...data, + metadataOptions: { + ...metadataOptions, + httpTokens: 'required', + }, + }; + launchTemplate.launchTemplateData = newData; + } +} diff --git a/packages/@aws-cdk/aws-ec2/lib/index.ts b/packages/@aws-cdk/aws-ec2/lib/index.ts index 1b10e6fa1d566..4b0741044e4dd 100644 --- a/packages/@aws-cdk/aws-ec2/lib/index.ts +++ b/packages/@aws-cdk/aws-ec2/lib/index.ts @@ -1,3 +1,4 @@ +export * from './aspects'; export * from './bastion-host'; export * from './connections'; export * from './cfn-init'; diff --git a/packages/@aws-cdk/aws-ec2/lib/instance.ts b/packages/@aws-cdk/aws-ec2/lib/instance.ts index 813d4d5f43880..85b05fc71734b 100644 --- a/packages/@aws-cdk/aws-ec2/lib/instance.ts +++ b/packages/@aws-cdk/aws-ec2/lib/instance.ts @@ -1,8 +1,9 @@ import * as crypto from 'crypto'; import * as iam from '@aws-cdk/aws-iam'; -import { Annotations, Duration, Fn, IResource, Lazy, Resource, Stack, Tags } from '@aws-cdk/core'; +import { Annotations, Aspects, Duration, Fn, IResource, Lazy, Resource, Stack, Tags } from '@aws-cdk/core'; import { Construct } from 'constructs'; +import { InstanceRequireImdsv2Aspect } from './aspects'; import { CloudFormationInit } from './cfn-init'; import { Connections, IConnectable } from './connections'; import { CfnInstance } from './ec2.generated'; @@ -230,6 +231,13 @@ export interface InstanceProps { * @default - default options */ readonly initOptions?: ApplyCloudFormationInitOptions; + + /** + * Whether IMDSv2 should be required on this instance. + * + * @default - false + */ + readonly requireImdsv2?: boolean; } /** @@ -408,6 +416,10 @@ export class Instance extends Resource implements IInstance { return `${originalLogicalId}${digest}`; }, })); + + if (props.requireImdsv2) { + Aspects.of(this).add(new InstanceRequireImdsv2Aspect()); + } } /** diff --git a/packages/@aws-cdk/aws-ec2/lib/launch-template.ts b/packages/@aws-cdk/aws-ec2/lib/launch-template.ts index fdc03755c0268..ae7f5316c01af 100644 --- a/packages/@aws-cdk/aws-ec2/lib/launch-template.ts +++ b/packages/@aws-cdk/aws-ec2/lib/launch-template.ts @@ -12,8 +12,10 @@ import { TagType, Tags, Token, + Aspects, } from '@aws-cdk/core'; import { Construct } from 'constructs'; +import { LaunchTemplateRequireImdsv2Aspect } from '.'; import { Connections, IConnectable } from './connections'; import { CfnLaunchTemplate } from './ec2.generated'; import { InstanceType } from './instance-types'; @@ -332,6 +334,13 @@ export interface LaunchTemplateProps { * @default No security group is assigned. */ readonly securityGroup?: ISecurityGroup; + + /** + * Whether IMDSv2 should be required on launched instances. + * + * @default - false + */ + readonly requireImdsv2?: boolean; } /** @@ -637,6 +646,10 @@ export class LaunchTemplate extends Resource implements ILaunchTemplate, iam.IGr this.latestVersionNumber = resource.attrLatestVersionNumber; this.launchTemplateId = resource.ref; this.versionNumber = Token.asString(resource.getAtt('LatestVersionNumber')); + + if (props.requireImdsv2) { + Aspects.of(this).add(new LaunchTemplateRequireImdsv2Aspect()); + } } /** diff --git a/packages/@aws-cdk/aws-ec2/test/aspects/require-imdsv2-aspect.test.ts b/packages/@aws-cdk/aws-ec2/test/aspects/require-imdsv2-aspect.test.ts new file mode 100644 index 0000000000000..ade2eaeab1f1d --- /dev/null +++ b/packages/@aws-cdk/aws-ec2/test/aspects/require-imdsv2-aspect.test.ts @@ -0,0 +1,205 @@ +import { + countResources, + expect as expectCDK, + haveResourceLike, +} from '@aws-cdk/assert-internal'; +import '@aws-cdk/assert-internal/jest'; +import * as cdk from '@aws-cdk/core'; +import { + CfnLaunchTemplate, + Instance, + InstanceRequireImdsv2Aspect, + InstanceType, + LaunchTemplate, + LaunchTemplateRequireImdsv2Aspect, + MachineImage, + Vpc, +} from '../../lib'; + +describe('RequireImdsv2Aspect', () => { + let app: cdk.App; + let stack: cdk.Stack; + let vpc: Vpc; + + beforeEach(() => { + app = new cdk.App(); + stack = new cdk.Stack(app, 'Stack'); + vpc = new Vpc(stack, 'Vpc'); + }); + + test('suppresses warnings', () => { + // GIVEN + const aspect = new LaunchTemplateRequireImdsv2Aspect({ + suppressWarnings: true, + }); + const errmsg = 'ERROR'; + const visitMock = jest.spyOn(aspect, 'visit').mockImplementation((node) => { + // @ts-ignore + aspect.warn(node, errmsg); + }); + const construct = new cdk.Construct(stack, 'Construct'); + + // WHEN + aspect.visit(construct); + + // THEN + expect(visitMock).toHaveBeenCalled(); + expect(construct.node.metadataEntry).not.toContainEqual({ + data: expect.stringContaining(errmsg), + type: 'aws:cdk:warning', + trace: undefined, + }); + }); + + describe('InstanceRequireImdsv2Aspect', () => { + test('requires IMDSv2', () => { + // GIVEN + const instance = new Instance(stack, 'Instance', { + vpc, + instanceType: new InstanceType('t2.micro'), + machineImage: MachineImage.latestAmazonLinux(), + }); + const aspect = new InstanceRequireImdsv2Aspect(); + + // WHEN + cdk.Aspects.of(stack).add(aspect); + app.synth(); + + // THEN + const launchTemplate = instance.node.tryFindChild('LaunchTemplate') as LaunchTemplate; + expect(launchTemplate).toBeDefined(); + expectCDK(stack).to(haveResourceLike('AWS::EC2::LaunchTemplate', { + LaunchTemplateName: stack.resolve(launchTemplate.launchTemplateName), + LaunchTemplateData: { + MetadataOptions: { + HttpTokens: 'required', + }, + }, + })); + expectCDK(stack).to(haveResourceLike('AWS::EC2::Instance', { + LaunchTemplate: { + LaunchTemplateName: stack.resolve(launchTemplate.launchTemplateName), + }, + })); + }); + + test('does not toggle when Instance has a LaunchTemplate', () => { + // GIVEN + const instance = new Instance(stack, 'Instance', { + vpc, + instanceType: new InstanceType('t2.micro'), + machineImage: MachineImage.latestAmazonLinux(), + }); + instance.instance.launchTemplate = { + launchTemplateName: 'name', + version: 'version', + }; + const aspect = new InstanceRequireImdsv2Aspect(); + + // WHEN + cdk.Aspects.of(stack).add(aspect); + + // THEN + // Aspect normally creates a LaunchTemplate for the Instance to toggle IMDSv1, + // so we can assert that one was not created + expectCDK(stack).to(countResources('AWS::EC2::LaunchTemplate', 0)); + expect(instance.node.metadataEntry).toContainEqual({ + data: expect.stringContaining('Cannot toggle IMDSv1 because this Instance is associated with an existing Launch Template.'), + type: 'aws:cdk:warning', + trace: undefined, + }); + }); + + test('suppresses Launch Template warnings', () => { + // GIVEN + const instance = new Instance(stack, 'Instance', { + vpc, + instanceType: new InstanceType('t2.micro'), + machineImage: MachineImage.latestAmazonLinux(), + }); + instance.instance.launchTemplate = { + launchTemplateName: 'name', + version: 'version', + }; + const aspect = new InstanceRequireImdsv2Aspect({ + suppressLaunchTemplateWarning: true, + }); + + // WHEN + aspect.visit(instance); + + // THEN + expect(instance.node.metadataEntry).not.toContainEqual({ + data: expect.stringContaining('Cannot toggle IMDSv1 because this Instance is associated with an existing Launch Template.'), + type: 'aws:cdk:warning', + trace: undefined, + }); + }); + }); + + describe('LaunchTemplateRequireImdsv2Aspect', () => { + test('warns when LaunchTemplateData is a CDK token', () => { + // GIVEN + const launchTemplate = new LaunchTemplate(stack, 'LaunchTemplate'); + const cfnLaunchTemplate = launchTemplate.node.tryFindChild('Resource') as CfnLaunchTemplate; + cfnLaunchTemplate.launchTemplateData = fakeToken(); + const aspect = new LaunchTemplateRequireImdsv2Aspect(); + + // WHEN + aspect.visit(launchTemplate); + + // THEN + expect(launchTemplate.node.metadataEntry).toContainEqual({ + data: expect.stringContaining('LaunchTemplateData is a CDK token.'), + type: 'aws:cdk:warning', + trace: undefined, + }); + }); + + test('warns when MetadataOptions is a CDK token', () => { + // GIVEN + const launchTemplate = new LaunchTemplate(stack, 'LaunchTemplate'); + const cfnLaunchTemplate = launchTemplate.node.tryFindChild('Resource') as CfnLaunchTemplate; + cfnLaunchTemplate.launchTemplateData = { + metadataOptions: fakeToken(), + } as CfnLaunchTemplate.LaunchTemplateDataProperty; + const aspect = new LaunchTemplateRequireImdsv2Aspect(); + + // WHEN + aspect.visit(launchTemplate); + + // THEN + expect(launchTemplate.node.metadataEntry).toContainEqual({ + data: expect.stringContaining('LaunchTemplateData.MetadataOptions is a CDK token.'), + type: 'aws:cdk:warning', + trace: undefined, + }); + }); + + test('requires IMDSv2', () => { + // GIVEN + new LaunchTemplate(stack, 'LaunchTemplate'); + const aspect = new LaunchTemplateRequireImdsv2Aspect(); + + // WHEN + cdk.Aspects.of(stack).add(aspect); + + // THEN + expectCDK(stack).to(haveResourceLike('AWS::EC2::LaunchTemplate', { + LaunchTemplateData: { + MetadataOptions: { + HttpTokens: 'required', + }, + }, + })); + }); + }); +}); + +function fakeToken(): cdk.IResolvable { + return { + creationStack: [], + resolve: (_c) => {}, + toString: () => '', + }; +} diff --git a/packages/@aws-cdk/aws-ec2/test/instance.test.ts b/packages/@aws-cdk/aws-ec2/test/instance.test.ts index 884021f518a84..a3a389d94aa9d 100644 --- a/packages/@aws-cdk/aws-ec2/test/instance.test.ts +++ b/packages/@aws-cdk/aws-ec2/test/instance.test.ts @@ -7,7 +7,7 @@ import * as cxschema from '@aws-cdk/cloud-assembly-schema'; import { Stack } from '@aws-cdk/core'; import { AmazonLinuxImage, BlockDeviceVolume, CloudFormationInit, - EbsDeviceVolumeType, InitCommand, Instance, InstanceArchitecture, InstanceClass, InstanceSize, InstanceType, UserData, Vpc, + EbsDeviceVolumeType, InitCommand, Instance, InstanceArchitecture, InstanceClass, InstanceSize, InstanceType, LaunchTemplate, UserData, Vpc, } from '../lib'; @@ -361,6 +361,36 @@ describe('instance', () => { }); + + test('instance requires IMDSv2', () => { + // WHEN + const instance = new Instance(stack, 'Instance', { + vpc, + machineImage: new AmazonLinuxImage(), + instanceType: new InstanceType('t2.micro'), + requireImdsv2: true, + }); + + // Force stack synth so the InstanceRequireImdsv2Aspect is applied + SynthUtils.synthesize(stack); + + // THEN + const launchTemplate = instance.node.tryFindChild('LaunchTemplate') as LaunchTemplate; + expect(launchTemplate).toBeDefined(); + expect(stack).toHaveResourceLike('AWS::EC2::LaunchTemplate', { + LaunchTemplateName: stack.resolve(launchTemplate.launchTemplateName), + LaunchTemplateData: { + MetadataOptions: { + HttpTokens: 'required', + }, + }, + }); + expect(stack).toHaveResourceLike('AWS::EC2::Instance', { + LaunchTemplate: { + LaunchTemplateName: stack.resolve(launchTemplate.launchTemplateName), + }, + }); + }); }); diff --git a/packages/@aws-cdk/aws-ec2/test/launch-template.test.ts b/packages/@aws-cdk/aws-ec2/test/launch-template.test.ts index 27399affe8149..6243a409bc007 100644 --- a/packages/@aws-cdk/aws-ec2/test/launch-template.test.ts +++ b/packages/@aws-cdk/aws-ec2/test/launch-template.test.ts @@ -509,6 +509,22 @@ describe('LaunchTemplate', () => { }, }); }); + + test('Requires IMDSv2', () => { + // WHEN + new LaunchTemplate(stack, 'Template', { + requireImdsv2: true, + }); + + // THEN + expect(stack).toHaveResourceLike('AWS::EC2::LaunchTemplate', { + LaunchTemplateData: { + MetadataOptions: { + HttpTokens: 'required', + }, + }, + }); + }); }); describe('LaunchTemplate marketOptions', () => {