AWS Collector Configuration

Authentication

The AWS collector supports multiple authentication methods. The auth_mode option controls how the collector assumes IAM roles:

• oidc - Uses GitHub Actions OIDC to assume roles via AssumeRoleWithWebIdentity (recommended for GitHub Actions)
• assume_role - Uses standard AssumeRole with optional external_id (default for backward compatibility)

1. GitHub Actions OIDC (Recommended)

When running in GitHub Actions, OIDC provides secure, credential-free authentication. The collector obtains a JWT token from GitHub and exchanges it for temporary AWS credentials.

Trust Policy (OIDC):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012: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:*"
        }
      }
    }
  ]
}

Configuration:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "oidc"
      role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
    secrets:
      - ACTIONS_ID_TOKEN_REQUEST_URL
      - ACTIONS_ID_TOKEN_REQUEST_TOKEN

GitHub Actions Workflow:

permissions:
  id-token: write  # Required for OIDC
  contents: read

2. IAM Role with AssumeRole

For environments without OIDC support, use standard AssumeRole with bootstrap credentials.

Trust Policy (AssumeRole):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::COLLECTOR_ACCOUNT:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-external-id"
        }
      }
    }
  ]
}

Configuration:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "assume_role"
      role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
      external_id: "your-external-id"

3. Default Credential Chain

If no role_arn is specified, the collector uses the AWS SDK's default credential chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. Shared credentials file (~/.aws/credentials)
3. EC2 instance profile / ECS task role

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      regions:
        - us-east-1

Required IAM Permissions

The collector needs read-only AWS permissions in each target account. The minimum set depends on the level config (see levels.md). Levels are cumulative: audit needs the trust set plus more; internal needs the audit set plus more.

All actions are List, Describe, or Get. Value-reading APIs (secretsmanager:GetSecretValue, ssm:GetParameter, etc.) are intentionally absent and are forbidden in collector source by a build-time lint.

If a surface is missing its required permissions, the collector emits a per-surface AccessDenied diagnostic warning and continues; it does not fail the whole run.

iam:ListOrganizationsFeatures only evaluates centralized root access from the AWS Organizations management account or an IAM delegated administrator account. Member-account roles record the AWS error code in the evidence pack instead of inferring the organization-level state.

Trust level (default)

The minimum policy. Required for every collection level.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",

        "iam:GenerateCredentialReport",
        "iam:GetAccountPasswordPolicy",
        "iam:GetAccountSummary",
        "iam:GetCredentialReport",
        "iam:ListAccountAliases",
        "iam:ListOrganizationsFeatures",
        "iam:ListMFADevices",
        "iam:ListRoles",

        "s3:GetAccountPublicAccessBlock",
        "s3:GetBucketLocation",
        "s3:GetBucketLogging",
        "s3:GetBucketPolicy",
        "s3:GetBucketObjectLockConfiguration",
        "s3:GetBucketPublicAccessBlock",
        "s3:GetBucketVersioning",
        "s3:GetEncryptionConfiguration",
        "s3:GetLifecycleConfiguration",
        "s3:ListAllMyBuckets",

        "ec2:DescribeImages",
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSnapshots",
        "ec2:DescribeVolumes",
        "ec2:DescribeVpcs",

        "cloudfront:ListDistributions",
        "cloudwatch:DescribeAlarms",
        "elasticloadbalancing:DescribeListeners",
        "elasticloadbalancing:DescribeLoadBalancers",
        "sns:ListSubscriptionsByTopic",

        "wafv2:ListWebACLs",
        "wafv2:GetWebACL",
        "wafv2:ListResourcesForWebACL",

        "autoscaling:DescribeAutoScalingGroups",
        "autoscaling:DescribePolicies",
        "application-autoscaling:DescribeScalableTargets",
        "application-autoscaling:DescribeScalingPolicies",
        "ecs:DescribeServices",
        "ecs:ListClusters",
        "ecs:ListServices",
        "elasticloadbalancing:DescribeTargetGroups",

        "ses:GetConfigurationSet",
        "ses:GetEmailIdentity",
        "ses:ListConfigurationSets",
        "ses:ListEmailIdentities",

        "rds:DescribeDBClusters",
        "rds:DescribeDBParameters",
        "rds:DescribeEventSubscriptions",
        "rds:DescribeDBInstances",

        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",

        "config:DescribeConfigurationRecorders",
        "config:DescribeConfigurationRecorderStatus",

        "guardduty:GetDetector",
        "guardduty:ListDetectors",
        "guardduty:ListFindings",

        "securityhub:DescribeHub",
        "securityhub:GetEnabledStandards",
        "securityhub:GetFindings",
        "securityhub:ListEnabledProductsForImport",

        "access-analyzer:ListAnalyzers",
        "access-analyzer:ListFindings",

        "sso:ListInstances",
        "sso:ListPermissionSets",
        "identitystore:ListGroups",
        "identitystore:ListUsers",

        "lambda:ListFunctions",
        "logs:DescribeLogGroups",

        "kms:DescribeKey",
        "kms:GetKeyRotationStatus",
        "kms:ListKeys",

        "secretsmanager:ListSecrets",
        "ssm:DescribeParameters"
      ],
      "Resource": "*"
    }
  ]
}

Audit level

Add these actions to the trust-level policy above. They surface the Identity Center access model (permission sets, the user and group roster, membership and account-assignment edges), per-function Lambda configuration, KMS alias enrichment, web ACL logging state, and the organization-membership classification of cross-account role trust.

[
  "sso:DescribePermissionSet",
  "sso:ListAccountsForProvisionedPermissionSet",
  "sso:ListManagedPoliciesInPermissionSet",
  "sso:GetInlinePolicyForPermissionSet",
  "sso:ListAccountAssignments",

  "identitystore:ListGroupMemberships",

  "organizations:ListAccounts",

  "lambda:GetPolicy",
  "lambda:ListFunctionUrlConfigs",

  "kms:ListAliases",

  "wafv2:GetLoggingConfiguration"
]

wafv2:GetLoggingConfiguration is best effort: without it, per-ACL rows report logging_evaluated: false rather than failing the region.

organizations:ListAccounts is optional and best effort: it succeeds only from the Organizations management account or a delegated administrator. Without it, per-role external_trust_in_org determinations are absent rather than guessed, and the run continues.

Internal level

Add these actions on top of the audit-level set. They surface per-rule Config compliance, GuardDuty finding payloads, per-bucket S3 ACL configuration, and per-VPC flow log status.

[
  "config:DescribeConfigRules",
  "config:DescribeComplianceByConfigRule",
  "config:DescribeConfigRuleEvaluationStatus",

  "guardduty:GetFindings",

  "ec2:DescribeFlowLogs",

  "s3:GetBucketAcl"
]

Multi-Account Setup

For organizations with multiple AWS accounts:

With OIDC (Recommended)

Each target account needs a role trusting the GitHub OIDC provider:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "oidc"
      accounts:
        - role_arn: "arn:aws:iam::111111111111:role/EpackCollectorRole"
        - role_arn: "arn:aws:iam::222222222222:role/EpackCollectorRole"
        - role_arn: "arn:aws:iam::333333333333:role/EpackCollectorRole"
      regions:
        - us-east-1
        - us-west-2
        - eu-west-1
    secrets:
      - ACTIONS_ID_TOKEN_REQUEST_URL
      - ACTIONS_ID_TOKEN_REQUEST_TOKEN

With AssumeRole

Each target account needs a role trusting the bootstrap account:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "assume_role"
      accounts:
        - role_arn: "arn:aws:iam::111111111111:role/EpackCollectorRole"
          external_id: "prod-123"
        - role_arn: "arn:aws:iam::222222222222:role/EpackCollectorRole"
          external_id: "staging-456"
        - role_arn: "arn:aws:iam::333333333333:role/EpackCollectorRole"
          external_id: "dev-789"
      regions:
        - us-east-1
        - us-west-2
        - eu-west-1

Note: external_id is ignored in OIDC mode. The OIDC token claims provide equivalent security through repository/branch constraints in the trust policy.

Region Configuration

By default, the collector discovers all enabled regions in the account and scans up to five of them concurrently. AWS rate limits are per region, so concurrent regions do not compete for API quotas. To limit to specific regions:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      regions:
        - us-east-1
        - us-west-2

Troubleshooting

"Access Denied" Errors

1. Verify the IAM role/user has all required permissions
2. Check that the trust policy allows the collector's identity
3. Ensure the external ID matches (if configured)

"Credential Report Not Ready"

The collector automatically retries generating the credential report. If it times out after 10 attempts, check IAM permissions for iam:GenerateCredentialReport.

"Service Not Available in Region"

Some services (like GuardDuty) may not be available in all regions. The collector handles this gracefully and continues with available services.

Rate Limiting

The AWS SDK automatically handles rate limiting with exponential backoff. For large accounts with many resources, collection may take several minutes.

AWS Collector Examples

Basic Usage

Collect from the current AWS account using default credentials:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config: {}

Cross-Account Collection

With OIDC (Recommended for GitHub Actions)

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "oidc"
      role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
    secrets:
      - ACTIONS_ID_TOKEN_REQUEST_URL
      - ACTIONS_ID_TOKEN_REQUEST_TOKEN

With AssumeRole

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "assume_role"
      role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
      external_id: "epack-collection-abc123"

Multi-Account Collection

With OIDC

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "oidc"
      accounts:
        - role_arn: "arn:aws:iam::111111111111:role/EpackCollectorRole"
        - role_arn: "arn:aws:iam::222222222222:role/EpackCollectorRole"
        - role_arn: "arn:aws:iam::333333333333:role/EpackCollectorRole"
    secrets:
      - ACTIONS_ID_TOKEN_REQUEST_URL
      - ACTIONS_ID_TOKEN_REQUEST_TOKEN

With AssumeRole

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      auth_mode: "assume_role"
      accounts:
        - role_arn: "arn:aws:iam::111111111111:role/EpackCollectorRole"
          external_id: "prod"
          label: "production"
        - role_arn: "arn:aws:iam::222222222222:role/EpackCollectorRole"
          external_id: "staging"
          label: "staging"
        - role_arn: "arn:aws:iam::333333333333:role/EpackCollectorRole"
          external_id: "dev"
          label: "development"

label is optional, operator-supplied free text (e.g. production, staging,
management). It is carried verbatim onto the account's entries in both
artifacts as account_label (and onto a failed account's failed_accounts
record), so downstream consumers can segment accounts without an external
mapping.

Specific Regions Only

Limit collection to specific regions:

collectors:
  aws:
    source: "locktivity/epack-collector-aws@^0.1.0"
    config:
      role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
      regions:
        - us-east-1
        - us-west-2
        - eu-west-1

Sample Output

Metrics use percentages (0-100), booleans, and counts where appropriate.

{
  "schema_version": "1.0.0",
  "collected_at": "2024-01-15T10:30:00Z",
  "accounts": [
    {
      "account_id": "123456789012",
      "account_alias": "production",
      "regions": ["us-east-1", "us-west-2"],
      "iam": {
        "credential_report_evaluated": true,
        "iam_users_present": true,
        "mfa_enabled": 95,
        "hardware_mfa_enabled": 0,
        "access_keys_rotated": 80,
        "root_credential_state_evaluated": true,
        "root_mfa_enabled": true,
        "root_credentials_present": true,
        "root_password_present": true,
        "root_access_keys_exist": false,
        "root_signing_certificates_present": false,
        "root_access_protected": true,
        "root_organizations_features_evaluated": true,
        "root_organization_id": "o-abc1234567",
        "root_credentials_management_feature_enabled": true,
        "root_sessions_feature_enabled": true
      },
      "s3": {
        "bucket_listing_evaluated": true,
        "account_public_access_block_evaluated": true,
        "bucket_count": 20,
        "public_access_blocked": 100,
        "public_access_block_unknown_count": 0,
        "default_encryption_enabled": 95,
        "default_encryption_evaluated_count": 20,
        "default_encryption_inferred_count": 0,
        "default_encryption_unknown_count": 0,
        "versioning_enabled": 60,
        "logging_enabled": 40,
        "account_public_access_block_enabled": true
      },
      "rds": {
        "regions_evaluated_count": 2,
        "database_count": 6,
        "encrypted_at_rest": 100,
        "publicly_accessible": 0,
        "deletion_protection": 90,
        "backup_retention_adequate": 100,
        "multi_az_enabled": 80
      },
      "network": {
        "regions_evaluated_count": 2,
        "open_to_world_ssh": 2,
        "open_to_world_rdp": 0
      },
      "account_security": {
        "cloudtrail": {
          "trail_listing_evaluated": true,
          "enabled": true,
          "multi_region_enabled": true,
          "organization_trail_enabled": true,
          "trail_status_evaluated_count": 1,
          "trail_status_inferred_count": 0,
          "trail_status_unknown_count": 0
        },
        "config": {
          "enabled": true,
          "recorder_running": true
        },
        "guardduty": {
          "enabled": true,
          "unremediated_findings_over_48h": 1
        },
        "security_hub": {
          "enabled": true,
          "cis_aws_foundations_benchmark_level_1": {
            "enabled": true,
            "compliance_percent": 88,
            "compliance_state": "WARNING",
            "passed_controls": 44,
            "failed_controls": 3,
            "warning_controls": 3,
            "not_available_controls": 1
          },
          "cis_aws_foundations_benchmark_level_2": {
            "enabled": true,
            "compliance_percent": 82,
            "compliance_state": "FAILED",
            "passed_controls": 55,
            "failed_controls": 8,
            "warning_controls": 4,
            "not_available_controls": 2
          },
          "cis_aws_foundations_benchmark_unknown_level": {
            "enabled": true,
            "compliance_percent": 90,
            "compliance_state": "FAILED",
            "passed_controls": 9,
            "failed_controls": 1,
            "warning_controls": 0,
            "not_available_controls": 0
          }
        },
        "inspector": {
          "status_evaluated": true,
          "enabled": true,
          "unpatched_server_percent": 25
        }
      }
    }
  ]
}

CI/CD Integration

GitHub Actions with OIDC (Recommended)

Using OIDC, the collector obtains credentials directly from GitHub without needing aws-actions/configure-aws-credentials:

name: Security Posture Collection

on:
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM UTC
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC token
      contents: read

    steps:
      - name: Install epack
        run: |
          curl -sSL https://install.epack.dev | bash

      - name: Collect AWS posture
        run: |
          epack collect
        # epack.yaml should have:
        # collectors:
        #   aws:
        #     source: "locktivity/epack-collector-aws@^0.1.0"
        #     config:
        #       auth_mode: "oidc"
        #       role_arn: "arn:aws:iam::123456789012:role/EpackCollectorRole"
        #     secrets:
        #       - ACTIONS_ID_TOKEN_REQUEST_URL
        #       - ACTIONS_ID_TOKEN_REQUEST_TOKEN

The secrets field tells epack to pass through the ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables (provided by GitHub when id-token: write permission is set). The collector uses these to obtain an OIDC token.

GitHub Actions with AssumeRole

If OIDC isn't available, use aws-actions/configure-aws-credentials to obtain bootstrap credentials:

name: Security Posture Collection

on:
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::BOOTSTRAP_ACCOUNT:role/BootstrapRole
          aws-region: us-east-1

      - name: Install epack
        run: |
          curl -sSL https://install.epack.dev | bash

      - name: Collect AWS posture
        run: |
          epack collect
        # epack.yaml should have:
        # collectors:
        #   aws:
        #     source: "locktivity/epack-collector-aws@^0.1.0"
        #     config:
        #       auth_mode: "assume_role"
        #       role_arn: "arn:aws:iam::TARGET_ACCOUNT:role/EpackCollectorRole"
        #       external_id: "your-external-id"

Terraform for IAM Role

OIDC Trust Policy (Recommended for GitHub Actions)

# First, create the GitHub OIDC provider (once per account)
resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["ffffffffffffffffffffffffffffffffffffffff"]
}

resource "aws_iam_role" "epack_collector" {
  name = "EpackCollectorRole"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = aws_iam_openid_connect_provider.github.arn
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
          }
          StringLike = {
            "token.actions.githubusercontent.com:sub" = "repo:${var.github_org}/${var.github_repo}:*"
          }
        }
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "epack_collector" {
  role       = aws_iam_role.epack_collector.name
  policy_arn = aws_iam_policy.epack_collector.arn
}

variable "github_org" {
  description = "GitHub organization name"
  type        = string
}

variable "github_repo" {
  description = "GitHub repository name"
  type        = string
}

AssumeRole Trust Policy

resource "aws_iam_role" "epack_collector" {
  name = "EpackCollectorRole"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${var.collector_account_id}:root"
        }
        Action = "sts:AssumeRole"
        Condition = {
          StringEquals = {
            "sts:ExternalId" = var.external_id
          }
        }
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "epack_collector" {
  role       = aws_iam_role.epack_collector.name
  policy_arn = aws_iam_policy.epack_collector.arn
}

variable "collector_account_id" {
  description = "AWS account ID where the collector runs"
  type        = string
}

variable "external_id" {
  description = "External ID for assume role"
  type        = string
  default     = "epack-collector"
}

Collector Policy (shared by both)

The policy file is the trust-level (default) set from the configuration page; add the audit or internal actions listed there when your pipeline collects at those levels.

resource "aws_iam_policy" "epack_collector" {
  name        = "EpackCollectorPolicy"
  description = "Read-only access for epack AWS collector"

  # Save the trust-level policy from the configuration page's Required IAM
  # Permissions section as epack-collector-policy.json next to this module.
  policy = file("${path.module}/epack-collector-policy.json")
}