IAM Roles & Security

The IAM module (createIamRoles) creates 3 IAM roles following the principle of least privilege. Each role is scoped to the minimum permissions needed for its specific workload — no wildcard ** resources on sensitive actions, no over-provisioned policies.

Module overview

1. Role Summary

export function createIamRoles(scope: Construct, input: IamInput): IamOutput {
  const { db, storage } = input;

  const ecsTaskExecutionRole = new iam.Role(scope, 'EcsTaskExecutionRole', {
    assumedBy: new iam.ServicePrincipal('ecs-tasks.amazonaws.com'),
  });

  const ecsTaskRole = new iam.Role(scope, 'EcsTaskRole', {
    assumedBy: new iam.ServicePrincipal('ecs-tasks.amazonaws.com'),
  });

  const lambdaExecutionRole = new iam.Role(scope, 'LambdaExecutionRole', {
    assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
  });

  // ... policy attachments ...

  return { ecsTaskExecutionRole, ecsTaskRole, lambdaExecutionRole };
}

2. Role 1: ECS Task Execution Role

This role is used by the ECS agent (not the application) to pull container images, write logs, and retrieve secrets at container startup.

Permissions

Why three separate ECR permissions?

The ECS agent needs three distinct ECR permissions to pull an image:

1. GetAuthorizationToken — obtain temporary Docker login credentials
2. BatchCheckLayerAvailability — check which image layers already exist locally (avoids re-download)
3. GetDownloadUrlForLayer + BatchGetImage — download missing layers and the image manifest

These are provided by the AWS-managed AmazonECSTaskExecutionRolePolicy. The Secrets Manager permission is the only custom addition — scoped to the single awsplace/app-secrets secret.

3. Role 2: ECS Task Role

This role is assumed by the Go application container (and the RaftDB sidecar) at runtime. It grants access to application data services.

Permissions

a) DynamoDB resource scoping

function allTableArns(db: DatabaseOutput): string[] {
  const tables = [db.configTable, db.bansTable, db.milestonesTable, db.historyTable];
  return tables.flatMap((t) => [t.tableArn, `${t.tableArn}/index/*`]);
}

// Each table gets its own grant — CDK generates minimal, scoped policies
db.configTable.grantReadWriteData(ecsTaskRole);
db.bansTable.grantReadWriteData(ecsTaskRole);
db.milestonesTable.grantReadWriteData(ecsTaskRole);
db.historyTable.grantReadWriteData(ecsTaskRole);

Using grantReadWriteData() (rather than hand-writing policies) is important: CDK resolves the exact table ARN and index ARNs at synthesis time. If a table name changes, the policy updates automatically.

This prevents the application from accessing any DynamoDB table other than the four application tables — a misconfigured BACKEND env var pointing to a wrong table name would fail with an IAM error, not silently read/write the wrong data.

b) S3 resource scoping

storage.canvasBucket.grantReadWrite(ecsTaskRole);
storage.exportsBucket.grantReadWrite(ecsTaskRole);

Again using CDK grant methods — permissions are scoped to the exact bucket ARNs and their object paths. The task role cannot access any other S3 bucket in the account.

c) EFS condition key

ecsTaskRole.addToPrincipalPolicy(new iam.PolicyStatement({
  actions: ['elasticfilesystem:ClientMount', 'elasticfilesystem:ClientWrite'],
  resources: [raftDbFileSystem.fileSystemArn],
  conditions: {
    StringEquals: {
      'elasticfilesystem:AccessPointArn': raftDbAccessPoint.accessPointArn,
    },
  },
}));

The EFS permission is doubly scoped:

1. Resource-level: Only the specific filesystem ARN
2. Condition-level: Only when accessed through the specific access point ARN

This means even if the task role were somehow granted EFS access to another filesystem, the mount would fail unless the access point condition also matched.

4. Role 3: Lambda Execution Role

This role is assumed by the Lambda function for authentication and admin proxy operations.

Permissions

a) Lambda is NOT in a VPC

// Lambda does NOT receive vpcConfig — it runs outside the VPC
const apiFunction = new lambda.Function(scope, 'ApiFunction', {
  // ... no vpc or vpcSubnets property ...
});

The Lambda has **no ec2:DescribeNetworkInterfaces permission and no VPC attachment. It reaches DynamoDB and S3 over public AWS API endpoints. This is a deliberate design choice:

Since the Lambda only needs DynamoDB and S3 (both public AWS APIs), and it makes outbound calls to Discord’s OAuth API, the VPC would add cost and latency with no security benefit.

b) S3 write-only for exports

The Lambda only has PutObject on the exports bucket — no GetObject, no DeleteObject, no ListBucket. It writes PNG exports but never reads them. The admin dashboard reads exports directly from the S3 bucket (via the ECS task role or a pre-signed URL), not through the Lambda.

5. Security Architecture Diagram

┌────────────────────────────────────────────────────────────────────┐
│                             AWS Cloud                              │
│                                                                    │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │    Lambda    │    │     ALB      │    │     ECS Fargate      │  │
│  │   (no VPC)   │    │   (public)   │    │   (public subnet)    │  │
│  │              │    │              │    │                      │  │
│  │ Role:        │    │ SG:          │    │ Execution Role:      │  │
│  │ Lambda Exec  │    │ 0.0.0.0/0    │    │ - ECR pull           │  │
│  │              │    │ :80, :443    │    │ - CW Logs            │  │
│  │ Perms:       │    │              │    │ - Secrets Manager    │  │
│  │ - DDB CRUD   │    │              │    │                      │  │
│  │ - S3 Put     │    │              │    │ Task Role:           │  │
│  │ - CW Logs    │    │              │    │ - DDB CRUD (4 tbl)   │  │
│  │              │    │              │    │ - S3 R/W (2 bkt)     │  │
│  │              │    │              │    │ - EFS mount          │  │
│  └──────┬───────┘    └──────┬───────┘    └──────────┬───────────┘  │
│         │                   │                       │              │
│         ▼                   ▼                       ▼              │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                   AWS Services (public APIs)                 │  │
│  │                                                              │  │
│  │    DynamoDB (4 tables)      S3 (2 buckets)     Secrets Mgr   │  │
│  │    ECR (1 repo)             EFS (1 fs)         CloudWatch    │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

Key security properties