AWS Setup

This guide walks you through setting up OIDC authentication between GitHub Actions and AWS. LeftSize uses federated credentials so no IAM access keys are stored in your repository – GitHub Actions requests a short-lived token for each scan.

Prerequisites

• An AWS account with resources to scan
• Permission to create IAM roles and OIDC providers
• A GitHub repository with LeftSize installed

Step 1: Create the OIDC provider

If your AWS account doesn’t already have a GitHub Actions OIDC provider, create one:

1. Go to the IAM Console > Identity providers > Add provider
2. Select OpenID Connect
3. Configure:
   • Provider URL: https://token.actions.githubusercontent.com
   • Audience: sts.amazonaws.com
4. Click Add provider

If you already use GitHub Actions OIDC for other workflows, you can skip this step – the existing provider works for LeftSize too.

Step 2: Create an IAM role

1. Go to IAM > Roles > Create role
2. Select Web identity as the trusted entity type
3. Choose the GitHub OIDC provider you created and audience sts.amazonaws.com
4. Click Next
5. Attach the ReadOnlyAccess managed policy
6. Name the role leftsize-scanner (or any name you prefer)
7. Click Create role

Restrict the trust policy

Edit the role’s trust policy to limit access to your specific repository:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:*"
        }
      }
    }
  ]
}

Replace ACCOUNT_ID with your AWS account ID and YOUR_ORG/YOUR_REPO with your GitHub repository.

Step 3: Add secrets and variables to GitHub

In your GitHub repository, go to Settings > Secrets and variables > Actions.

Secrets

Variables

If AWS_REGIONS is not set, LeftSize will attempt to scan all accessible regions.

Scanning multiple AWS accounts

LeftSize supports scanning multiple AWS accounts using a matrix strategy. Edit your workflow to add environments:

strategy:
  fail-fast: false
  matrix:
    environment: [MAIN, PROD, DEV]

For each environment, create a matching secret:

• AWS_ROLE_ARN_PROD – Role ARN in your production account
• AWS_ROLE_ARN_DEV – Role ARN in your development account

Each account needs its own IAM role with the OIDC trust policy and ReadOnlyAccess.

Verifying the setup

1. Go to your repository’s Actions tab
2. Select LeftSize Cost Optimization Scan
3. Click Run workflow
4. Check the workflow logs for successful AWS authentication

If authentication fails, verify:

• The OIDC provider exists in your AWS account
• The IAM role trust policy references the correct repository
• The role has ReadOnlyAccess attached
• The AWS_ROLE_ARN_MAIN secret contains the full ARN

Using a custom policy instead of ReadOnlyAccess

If ReadOnlyAccess is too broad for your security requirements, you can create a custom policy. LeftSize needs these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "rds:Describe*",
        "rds:ListTagsForResource",
        "s3:GetBucketLocation",
        "s3:GetBucketTagging",
        "s3:GetEncryptionConfiguration",
        "s3:GetBucketPublicAccessBlock",
        "s3:GetLifecycleConfiguration",
        "s3:ListBucket",
        "s3:ListAllMyBuckets",
        "elasticloadbalancing:Describe*",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics",
        "lambda:List*",
        "lambda:GetFunction",
        "dynamodb:Describe*",
        "dynamodb:ListTables",
        "dynamodb:ListTagsOfResource",
        "elasticache:Describe*",
        "elasticache:ListTagsForResource",
        "eks:Describe*",
        "eks:List*",
        "ecr:DescribeRepositories",
        "ecr:GetLifecyclePolicy",
        "logs:DescribeLogGroups",
        "secretsmanager:ListSecrets",
        "secretsmanager:DescribeSecret",
        "acm:ListCertificates",
        "acm:DescribeCertificate",
        "tag:GetResources",
        "iam:ListAccountAliases"
      ],
      "Resource": "*"
    }
  ]
}

Minimal permissions

LeftSize operates with read-only access. The scan:

• Reads resource metadata via AWS APIs
• Reads CloudWatch metrics for utilization analysis
• Never creates, modifies, or deletes any resources
• Never accesses data stored in your resources (no S3 object contents, no database queries)