agent-vpc.ts

/**
 *  MIT No Attribution
 *
 *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy of
 *  the Software without restriction, including without limitation the rights to
 *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 *  the Software, and to permit persons to whom the Software is furnished to do so.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 */

import { RemovalPolicy } from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as logs from 'aws-cdk-lib/aws-logs';
import { NagSuppressions } from 'cdk-nag';
import { Construct } from 'constructs';

/**
 * Properties for the AgentVpc construct.
 */
export interface AgentVpcProps {
  /**
   * Maximum number of availability zones to use.
   * @default 2
   */
  readonly maxAzs?: number;

  /**
   * Number of NAT gateways to provision.
   * @default 1
   */
  readonly natGateways?: number;

  /**
   * Removal policy for VPC flow log resources.
   * @default RemovalPolicy.DESTROY
   */
  readonly removalPolicy?: RemovalPolicy;
}

/**
 * VPC with restricted egress for the AgentCore Runtime.
 *
 * Provides HTTPS-only outbound access, VPC endpoints for AWS services,
 * and NAT for GitHub API access. Flow logs are enabled for audit.
 */
export class AgentVpc extends Construct {
  /** The VPC where the Runtime will be deployed. */
  public readonly vpc: ec2.Vpc;

  /** Security group for the Runtime ENIs — allows only TCP 443 egress. */
  public readonly runtimeSecurityGroup: ec2.SecurityGroup;

  constructor(scope: Construct, id: string, props: AgentVpcProps = {}) {
    super(scope, id);

    const maxAzs = props.maxAzs ?? 2;
    const natGateways = props.natGateways ?? 1;
    const removalPolicy = props.removalPolicy ?? RemovalPolicy.DESTROY;

    // --- VPC ---
    this.vpc = new ec2.Vpc(this, 'Vpc', {
      maxAzs,
      natGateways,
      restrictDefaultSecurityGroup: true,
      subnetConfiguration: [
        {
          name: 'Public',
          subnetType: ec2.SubnetType.PUBLIC,
          cidrMask: 24,
        },
        {
          name: 'Private',
          subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
          cidrMask: 24,
        },
      ],
    });

    // --- Flow logs (satisfies AwsSolutions-VPC7) ---
    const flowLogGroup = new logs.LogGroup(this, 'FlowLogGroup', {
      retention: logs.RetentionDays.ONE_MONTH,
      removalPolicy,
    });

    this.vpc.addFlowLog('FlowLog', {
      destination: ec2.FlowLogDestination.toCloudWatchLogs(flowLogGroup),
      trafficType: ec2.FlowLogTrafficType.ALL,
    });

    NagSuppressions.addResourceSuppressions(this.vpc, [
      {
        id: 'AwsSolutions-IAM5',
        reason: 'VPC flow log role requires wildcard permissions for CloudWatch Logs — generated by CDK',
      },
    ], true);

    // --- Security group (HTTPS-only egress) ---
    this.runtimeSecurityGroup = new ec2.SecurityGroup(this, 'RuntimeSG', {
      vpc: this.vpc,
      description: 'AgentCore Runtime - egress TCP 443 only',
      allowAllOutbound: false,
    });

    this.runtimeSecurityGroup.addEgressRule(
      ec2.Peer.anyIpv4(),
      ec2.Port.tcp(443),
      'Allow HTTPS egress (GitHub API via NAT, AWS services via endpoints)',
    );

    // --- Gateway endpoints (free, no ENI cost) ---
    this.vpc.addGatewayEndpoint('S3Endpoint', {
      service: ec2.GatewayVpcEndpointAwsService.S3,
    });

    this.vpc.addGatewayEndpoint('DynamoDBEndpoint', {
      service: ec2.GatewayVpcEndpointAwsService.DYNAMODB,
    });

    // --- Interface endpoints (private DNS enabled, placed in private subnets) ---
    const interfaceEndpoints: Array<{ id: string; service: ec2.InterfaceVpcEndpointAwsService }> = [
      { id: 'EcrApiEndpoint', service: ec2.InterfaceVpcEndpointAwsService.ECR },
      { id: 'EcrDockerEndpoint', service: ec2.InterfaceVpcEndpointAwsService.ECR_DOCKER },
      { id: 'CloudWatchLogsEndpoint', service: ec2.InterfaceVpcEndpointAwsService.CLOUDWATCH_LOGS },
      { id: 'SecretsManagerEndpoint', service: ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER },
      { id: 'BedrockRuntimeEndpoint', service: ec2.InterfaceVpcEndpointAwsService.BEDROCK_RUNTIME },
      { id: 'StsEndpoint', service: ec2.InterfaceVpcEndpointAwsService.STS },
      { id: 'XRayEndpoint', service: ec2.InterfaceVpcEndpointAwsService.XRAY },
      { id: 'EcsEndpoint', service: ec2.InterfaceVpcEndpointAwsService.ECS },
      { id: 'EcsAgentEndpoint', service: ec2.InterfaceVpcEndpointAwsService.ECS_AGENT },
      { id: 'EcsTelemetryEndpoint', service: ec2.InterfaceVpcEndpointAwsService.ECS_TELEMETRY },
      { id: 'StepFunctionsEndpoint', service: ec2.InterfaceVpcEndpointAwsService.STEP_FUNCTIONS },
    ];

    for (const ep of interfaceEndpoints) {
      this.vpc.addInterfaceEndpoint(ep.id, {
        service: ep.service,
        privateDnsEnabled: true,
        subnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
      });
    }
  }
}