setup

Amazon Web Services (AWS)

tip

Set up with an AI agent Using Claude Code, Cursor, Codex CLI, or another coding agent? The subimage-setup:connect-aws skill walks the agent through every choice on this page. Paste this into your agent:

Use curl to download, read and follow: https://skills.subimage.io/plugins/subimage-setup/skills/connect-aws/SKILL.md

Or install the marketplace once with claude plugin marketplace add subimagesec/skills. Full instructions on Agent Skills.

Purpose

Inventories AWS resources and IAM relationships across one or more accounts. AWS is the foundation most other security analyses build on: connect every account you want to cover.

How It Works

Each account needs a read-only IAM role named SubImageScanRole that trusts the Subimage principal for your tenant. Every sync calls sts:AssumeRole on that role and reads the account. If one configured account is the AWS Organizations management account or a delegated administrator account, Subimage also uses it once per sync to map the organization, roots, OUs, and account placement before scanning per-account resources.

Deploy the role as an AWS Organizations StackSet so that:

  • every existing account receives the role automatically
  • new accounts created later pick it up with no extra work
important

Service-managed StackSets do not deploy to the organization's management account, even when you target the org root. To scan the management account, deploy the same template there as a standalone stack.

One-click deployment

Open Modules → AWS and select Deploy across the organization. The CloudFormation link pre-fills the IAM principal for this Subimage deployment. Enter the AWS Organizations root or OU IDs and one Region for the StackSet instances (IAM roles are account-global; extra regions would try to create the same named role and fail), then create the bootstrap stack. It creates a service-managed StackSet with automatic deployment enabled for accounts added later.

AWS Organizations trusted access for service-managed StackSets must already be enabled. Run the Deploy to one account option separately in the management account, which service-managed StackSets cannot target.

If the scan role is already managed by a StackSet or standalone stack, update that existing deployment instead of creating a second stack with the same role name.

One-time steps

  1. Confirm the Subimage principal ARN. When you view these docs inside your authenticated tenant, Subimage auto-fills your tenant AWS account ID in the snippets below. The principal looks like:

    arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly
  2. Deploy the scanning role using CloudFormation (service-managed StackSet) or Terraform below.

  3. Target All AWS accounts. Deploy the StackSet in a single Region.

  4. If you want to scan the management account, deploy the same template there as a standalone stack.

Use the SubImageScanRole template below unchanged. SecurityAudit covers most of what Subimage reads, and each inline policy adds only read actions that SecurityAudit does not cover, including the EKS OIDC identity provider reads needed by EKS rows in the Kubernetes module and read access to AWS-managed public SSM parameters when that optional catalog ingestion is enabled. If you deployed this role from an older copy of the template, update the existing StackSet or standalone stack so every scanned account receives the current inline policies. The template has one optional parameter, EnableVMScanning (default false). Set it to true only if you want the Scan module to scan EC2 root volumes; it is the only setting that grants write access, limited to EBS snapshots tagged subimage:scan=true.

Option A – CloudFormation

AWSTemplateFormatVersion: "2010-09-09"
Description: >
  IAM role used by SubImage to inventory this AWS account.

Parameters:
  TrustedPrincipalArns:
    Type: CommaDelimitedList
    Default: "arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly"
    Description: IAM role ARNs for the SubImage deployments allowed to assume this role.
  RoleName:
    Type: String
    Default: "SubImageScanRole"
    Description: Name of the customer-side IAM role SubImage assumes.
    AllowedPattern: '^[\w+=,.@-]{1,64}$'
  EnableVMScanning:
    Type: String
    Default: "false"
    AllowedValues:
      - "false"
      - "true"
    Description: >
      Set to true to let SubImage scan EC2 root volumes for vulnerabilities.
      Adds permission to create, read, and delete EBS snapshots tagged
      subimage:scan=true.

Conditions:
  VMScanningEnabled: !Equals [!Ref EnableVMScanning, "true"]

Resources:
  SubImageScanRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Ref RoleName
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: !Ref TrustedPrincipalArns
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/SecurityAudit
      Policies:
        - PolicyName: AllowSSOGlobalActions
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  # SecurityAudit covers the Identity Center and Identity Store
                  # list and describe calls. AWS also evaluates
                  # sso:GetPermissionSet for DescribePermissionSet.
                  - "sso:GetPermissionSet"
                Resource: "*"
        - PolicyName: AllowEKSIdentityRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  # SecurityAudit already covers eks:DescribeCluster,
                  # eks:ListAccessEntries, and eks:DescribeAccessEntry. These
                  # are the EKS OIDC identity provider reads SubImage needs.
                  - "eks:ListIdentityProviderConfigs"
                  - "eks:DescribeIdentityProviderConfig"
                Resource: "*"
        - PolicyName: AllowPublicSSMParameterRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: "ssm:GetParametersByPath"
                Resource: !Sub "arn:${AWS::Partition}:ssm:*::parameter/aws/service/*"
        - PolicyName: AllowECRRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - "ecr:GetAuthorizationToken"
                  - "ecr:BatchCheckLayerAvailability"
                  - "ecr:GetDownloadUrlForLayer"
                  - "ecr:BatchGetImage"
                  # Not covered by SecurityAudit; needed by the Cartography
                  # AWS ECR pull through cache rule sync stage.
                  - "ecr:DescribePullThroughCacheRules"
                Resource: "*"
        - PolicyName: AllowGlueInspectorRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  # Not covered by SecurityAudit; needed by the Cartography
                  # AWS glue and inspector sync stages.
                  - "glue:GetConnections"
                  - "inspector2:ListMembers"
                Resource: "*"
        - PolicyName: AllowSESRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  # Not covered by SecurityAudit; needed by the Cartography
                  # AWS SES email identity sync stage.
                  - "ses:ListEmailIdentities"
                Resource: "*"

        - PolicyName: AllowCodeBuildBuildRead
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  # Not covered by SecurityAudit; needed by the Cartography
                  # AWS CodeBuild sync stage to confirm the builds that pushed
                  # ECR images.
                  - "codebuild:BatchGetBuilds"
                Resource: "*"

  # Agentless VM scanning is the only write access SubImage requests, so it is
  # opt-in and limited to snapshots carrying the subimage:scan=true tag.
  SubImageVMScanPolicy:
    Type: AWS::IAM::RolePolicy
    Condition: VMScanningEnabled
    Properties:
      RoleName: !Ref SubImageScanRole
      PolicyName: AllowVMSnapshotScanning
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Sid: SnapshotAnyVolume
            Effect: Allow
            Action: "ec2:CreateSnapshot"
            Resource: !Sub "arn:${AWS::Partition}:ec2:*:*:volume/*"
          - Sid: CreateOnlyTaggedSnapshots
            Effect: Allow
            Action: "ec2:CreateSnapshot"
            Resource: !Sub "arn:${AWS::Partition}:ec2:*::snapshot/*"
            Condition:
              StringEquals:
                "aws:RequestTag/subimage:scan": "true"
          - Sid: TagSnapshotsOnCreate
            Effect: Allow
            Action: "ec2:CreateTags"
            Resource: !Sub "arn:${AWS::Partition}:ec2:*::snapshot/*"
            Condition:
              StringEquals:
                "ec2:CreateAction": "CreateSnapshot"
          - Sid: ReadAndDeleteOnlyScanSnapshots
            Effect: Allow
            Action:
              - "ec2:DeleteSnapshot"
              - "ebs:ListSnapshotBlocks"
              - "ebs:GetSnapshotBlock"
            Resource: !Sub "arn:${AWS::Partition}:ec2:*::snapshot/*"
            Condition:
              StringEquals:
                "aws:ResourceTag/subimage:scan": "true"
          # Decrypt only through EC2, only for EBS volume and snapshot data,
          # and only with keys in this account.
          - Sid: DecryptSnapshotBlocksVolContext
            Effect: Allow
            Action: "kms:Decrypt"
            Resource: !Sub "arn:${AWS::Partition}:kms:*:*:key/*"
            Condition:
              StringEquals:
                "aws:ResourceAccount": "${aws:PrincipalAccount}"
              StringLike:
                "kms:ViaService": "ec2.*.amazonaws.com"
                "kms:EncryptionContext:aws:ebs:id": "vol-*"
          - Sid: DecryptSnapshotBlocksSnapContext
            Effect: Allow
            Action: "kms:Decrypt"
            Resource: !Sub "arn:${AWS::Partition}:kms:*:*:key/*"
            Condition:
              StringEquals:
                "aws:ResourceAccount": "${aws:PrincipalAccount}"
              StringLike:
                "kms:ViaService": "ec2.*.amazonaws.com"
                "kms:EncryptionContext:aws:ebs:id": "snap-*"
          - Sid: DescribeKeysForEbsOperations
            Effect: Allow
            Action: "kms:DescribeKey"
            Resource: !Sub "arn:${AWS::Partition}:kms:*:*:key/*"
            Condition:
              StringEquals:
                "aws:ResourceAccount": "${aws:PrincipalAccount}"
              StringLike:
                "kms:ViaService": "ec2.*.amazonaws.com"

Outputs:
  SubImageScanRoleArn:
    Description: ARN of the created SubImage scanning IAM Role.
    Value: !GetAtt SubImageScanRole.Arn

The Identity Center collector uses both the sso and identitystore APIs. SecurityAudit covers the actions it calls: sso:ListInstances, sso:ListPermissionSets, sso:DescribePermissionSet, sso:ListAccountAssignmentsForPrincipal, identitystore:ListGroups, identitystore:ListGroupMemberships, and identitystore:ListUsers. AWS also evaluates sso:GetPermissionSet for DescribePermissionSet, and SecurityAudit does not include it, so AllowSSOGlobalActions grants that single action.

Option B – Terraform

variable "trusted_principal_arns" {
  description = "IAM role ARNs for the SubImage deployments allowed to assume this role."
  type        = list(string)
  default     = ["arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly"]
}

variable "role_name" {
  description = "Name of the customer-side IAM role SubImage assumes."
  type        = string
  default     = "SubImageScanRole"
}

variable "enable_vm_scanning" {
  description = "Let SubImage scan EC2 root volumes through EBS snapshots tagged subimage:scan=true."
  type        = bool
  default     = false
}

resource "aws_iam_role" "subimage_scan_role" {
  name = var.role_name

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { AWS = var.trusted_principal_arns }
      Action    = "sts:AssumeRole"
    }]
  })
}

resource "aws_iam_role_policy_attachment" "attach_security_audit" {
  role       = aws_iam_role.subimage_scan_role.name
  policy_arn = "arn:aws:iam::aws:policy/SecurityAudit"
}

resource "aws_iam_role_policy" "allow_sso_global_actions" {
  name = "AllowSSOGlobalActions"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["sso:GetPermissionSet"]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_eks_identity_read" {
  name = "AllowEKSIdentityRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "eks:ListIdentityProviderConfigs",
        "eks:DescribeIdentityProviderConfig"
      ]
      Resource = "*"
    }]
  })
}

data "aws_partition" "current" {}

resource "aws_iam_role_policy" "allow_public_ssm_parameter_read" {
  name = "AllowPublicSSMParameterRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "ssm:GetParametersByPath"
      Resource = "arn:${data.aws_partition.current.partition}:ssm:*::parameter/aws/service/*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_ecr_read" {
  name = "AllowECRRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:DescribePullThroughCacheRules"
      ]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_glue_inspector_read" {
  name = "AllowGlueInspectorRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "glue:GetConnections",
        "inspector2:ListMembers"
      ]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_ses_read" {
  name = "AllowSESRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["ses:ListEmailIdentities"]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_codebuild_build_read" {
  name = "AllowCodeBuildBuildRead"
  role = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "codebuild:BatchGetBuilds"
      ]
      Resource = "*"
    }]
  })
}

resource "aws_iam_role_policy" "allow_vm_snapshot_scanning" {
  count = var.enable_vm_scanning ? 1 : 0
  name  = "AllowVMSnapshotScanning"
  role  = aws_iam_role.subimage_scan_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid      = "SnapshotAnyVolume"
        Effect   = "Allow"
        Action   = "ec2:CreateSnapshot"
        Resource = "arn:aws:ec2:*:*:volume/*"
      },
      {
        Sid       = "CreateOnlyTaggedSnapshots"
        Effect    = "Allow"
        Action    = "ec2:CreateSnapshot"
        Resource  = "arn:aws:ec2:*::snapshot/*"
        Condition = { StringEquals = { "aws:RequestTag/subimage:scan" = "true" } }
      },
      {
        Sid       = "TagSnapshotsOnCreate"
        Effect    = "Allow"
        Action    = "ec2:CreateTags"
        Resource  = "arn:aws:ec2:*::snapshot/*"
        Condition = { StringEquals = { "ec2:CreateAction" = "CreateSnapshot" } }
      },
      {
        Sid       = "ReadAndDeleteOnlyScanSnapshots"
        Effect    = "Allow"
        Action    = ["ec2:DeleteSnapshot", "ebs:ListSnapshotBlocks", "ebs:GetSnapshotBlock"]
        Resource  = "arn:aws:ec2:*::snapshot/*"
        Condition = { StringEquals = { "aws:ResourceTag/subimage:scan" = "true" } }
      },
      {
        Sid      = "DecryptSnapshotBlocksVolContext"
        Effect   = "Allow"
        Action   = "kms:Decrypt"
        Resource = "arn:aws:kms:*:*:key/*"
        Condition = {
          StringEquals = { "aws:ResourceAccount" = "$${aws:PrincipalAccount}" }
          StringLike = {
            "kms:ViaService"                   = "ec2.*.amazonaws.com"
            "kms:EncryptionContext:aws:ebs:id" = "vol-*"
          }
        }
      },
      {
        Sid      = "DecryptSnapshotBlocksSnapContext"
        Effect   = "Allow"
        Action   = "kms:Decrypt"
        Resource = "arn:aws:kms:*:*:key/*"
        Condition = {
          StringEquals = { "aws:ResourceAccount" = "$${aws:PrincipalAccount}" }
          StringLike = {
            "kms:ViaService"                   = "ec2.*.amazonaws.com"
            "kms:EncryptionContext:aws:ebs:id" = "snap-*"
          }
        }
      },
      {
        Sid      = "DescribeKeysForEbsOperations"
        Effect   = "Allow"
        Action   = "kms:DescribeKey"
        Resource = "arn:aws:kms:*:*:key/*"
        Condition = {
          StringEquals = { "aws:ResourceAccount" = "$${aws:PrincipalAccount}" }
          StringLike   = { "kms:ViaService" = "ec2.*.amazonaws.com" }
        }
      }
    ]
  })
}

output "subimage_scan_role_arn" {
  description = "ARN of the created SubImage scanning IAM Role."
  value       = aws_iam_role.subimage_scan_role.arn
}

Register AWS in Subimage

Go to Modules → Add → aws and fill in:

Field Example Notes
aws_account_ids 111111111111,222222222222 Selected-account mode: every AWS account ID you want Subimage to scan. Include the management or delegated administrator account ID too if you want hierarchy mapping.
aws_organization_account_ids (optional) 111111111111 AWS management or delegated administrator account IDs that can enumerate AWS Organizations.
aws_scan_all_active_organization_accounts false Org-wide mode: set to true to scan all ACTIVE accounts discovered from aws_organization_account_ids instead of listing selected accounts.
aws_resource_functions (optional) s3,iam,ssm A subset of AWS resource collectors for faster, scoped scans. Select "Sync all resources" for all collectors.

Save the module, then use Run Sync to trigger an AWS sync immediately or wait for the hourly scheduled run.

For selected-account scans, keep aws_scan_all_active_organization_accounts disabled and list the exact accounts in aws_account_ids. If you set aws_organization_account_ids in this mode, each value must also be listed in aws_account_ids; omit it only as a fallback, in which case Subimage probes the configured scan accounts and uses the first account that can enumerate the hierarchy.

For org-wide scans, set aws_scan_all_active_organization_accounts to true, leave aws_account_ids empty, and provide one or more management or delegated administrator account IDs in aws_organization_account_ids. Subimage enumerates the organization first, scans only ACTIVE accounts, and automatically includes newly active accounts on later syncs. Use selected-account mode instead if you do not want every active account in the organization scanned.

The SecurityAudit managed policy includes AWS Organizations read actions, but AWS still restricts hierarchy APIs such as ListRoots, ListAccountsForParent, and ListOrganizationalUnitsForParent to the management account or a delegated administrator account. In selected-account mode, if no configured account can enumerate the full hierarchy, Subimage skips organization hierarchy cleanup and continues normal account-scoped resource sync. In org-wide mode, Subimage must enumerate the organization to resolve accounts to scan, so the sync fails as a configuration error if the listed org account IDs cannot enumerate the hierarchy.

Subimage also syncs the organization's service control policies (SCPs) with the same account, which calls ListPolicies, DescribePolicy, and ListTargetsForPolicy. The management account can always call these. A delegated administrator account needs an AWS Organizations delegation policy that allows them. Without it, the hierarchy still syncs and Subimage keeps the previously synced SCPs.

Org-wide mode scans every ACTIVE account returned by AWS Organizations, including the management account when AWS reports it as active. Service-managed StackSets do not deploy to the management account automatically, so deploy the template there as a standalone stack before enabling org-wide mode.

Optional AWS-managed public SSM parameters

AWS-managed public SSM parameter ingestion is disabled by default because the catalogs can contain tens of thousands of parameters in every enabled Region. Deployment operators can opt in by setting AWS_SSM_PUBLIC_PARAMETER_PREFIX_ALLOWLIST to a comma-separated list of required prefixes. To preserve the previous Bottlerocket and EKS optimized AMI coverage, set:

/aws/service/bottlerocket/,/aws/service/eks/optimized-ami/

When aws_resource_functions limits the collectors, it must include ssm for this setting to have an effect. Upgrading without an explicit allowlist removes previously ingested AWSPublicSSMParameter nodes during the next complete AWS sync.

Single-account fallback

If you prefer not to use StackSets, deploy the same template as a standalone CloudFormation stack in each account. Repeat for every account you want Subimage to scan.

Troubleshooting

  • AccessDenied on a specific service: the role is missing required read-only permissions. Verify the managed policy and inline policies.
  • AccessDenied from ssm:GetParametersByPath: if public SSM parameter ingestion is enabled, update the StackSet, standalone CloudFormation stack, or Terraform role so it includes AllowPublicSSMParameterRead. If you configured prefixes outside /aws/service/..., expand the policy resource to those exact public parameter paths.
  • AccessDenied from sts:AssumeRole: the trust policy does not list the Subimage principal ARN. Re-deploy the stack or add the principal manually.
  • AWS Organizations hierarchy is missing: in selected-account mode, verify that aws_account_ids includes the management account or a delegated administrator account and that aws_organization_account_ids points at that account for predictable syncs. In org-wide mode, verify that aws_organization_account_ids contains a management or delegated administrator account ID.
  • Management account fails in org-wide mode, StackSet otherwise healthy: expected if SubImageScanRole was only deployed through a service-managed StackSet. Deploy the template in the management account as a standalone stack, or use selected-account mode if you do not want to scan it.