Skip to content

cloudg

aws

morpheuslord/cloudg

`aws`¶

Credentials, regions and accounts for the AWS collectors. Any auth method can be combined with role assumption.

Keys¶

Key	Type	Default	Description
`regions`	`list`	`[us-east-1, eu-west-1]`	Regions to collect. `ALL` discovers every region enabled for the account.
`access_key_id`	`null`	`null`	AWS access key ID (direct credential)
`secret_access_key`	`null`	`null`	AWS secret access key (direct credential)
`session_token`	`null`	`null`	AWS session token (for temporary credentials)
`web_identity_token_file`	`null`	`null`	Path to an OIDC token file for AssumeRoleWithWebIdentity (GitHub Actions, EKS, GitLab CI)
`profile`	`null`	`null`	AWS CLI profile name (fallback if no direct keys)
`role_arn`	`null`	`null`	Full ARN of a role to assume (single-account AssumeRole or OIDC target)
`external_id`	`null`	`null`	ExternalId for AssumeRole (third-party auditor pattern)
`role_session_name`	`str`	`cloudg-scan`	Session name used when cloudg assumes a role.
`accounts`	`list`	`[]`	Target account IDs (only if cross-account scanning)
`role_name`	`null`	`null`	IAM role to assume in target accounts (optional, for cross-account)
`organization`	`map`		AWS Organizations / Control Tower discovery (`cloudg map --org`). Run with management-account credentials; every selected member account is mapped by assuming role_name there. AWSControlTowerExecution is admin: prefer a read-only role (SecurityAudit + ViewOnlyAccess) deployed to all accounts with a StackSet.
`organization.enabled`	`bool`	`false`	Discover and map every account in the org
`organization.role_name`	`null`	`null`	Role assumed in member accounts. Falls back to aws.role_name, then AWSControlTowerExecution. A dedicated read-only role (SecurityAudit + ViewOnlyAccess) deployed with a StackSet is recommended.
`organization.include_ous`	`list`	`[]`	Only accounts under these OUs (ID, ARN or name; nested OUs included)
`organization.exclude_accounts`	`list`	`[]`	Account IDs to leave out of an Organizations run.
`organization.include_management_account`	`bool`	`true`	Map the management account as well as the members.
`organization.include_suspended`	`bool`	`false`	Include suspended accounts.
`organization.use_governed_regions`	`bool`	`true`	With regions=['ALL'], scan only the Control Tower governed regions
`organization.control_tower`	`bool`	`true`	map the landing zone, controls and baselines
`organization.home_region`	`null`	`null`	Control Tower home region (auto-detected when unset)
`organization.map_structure`	`bool`	`true`	Emit org, OU, account, SCP and control nodes on the map
`max_retries`	`int`	`10`	botocore retries per API call after the first attempt
`retry_mode`	`str`	`adaptive`	legacy \| standard \| adaptive (botocore client-side rate limiting)

In config.yaml¶

config.yaml (aws)

aws:
  regions:
    - us-east-1
    - eu-west-1
    # - ALL              # Uncomment to auto-discover and scan ALL enabled regions

  # Auth method 1: direct credentials (useful for third-party access)
  # Can also be set via env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
  access_key_id: null      # Your AWS access key ID
  secret_access_key: null  # Your AWS secret access key
  session_token: null      # Optional: for temporary/STS credentials

  # Auth method 2: OIDC / web identity federation (GitHub Actions, EKS, GitLab CI)
  # Set role_arn together with web_identity_token_file.
  web_identity_token_file: null   # Path to the OIDC token file

  # Auth method 3: AWS CLI profile (plain or SSO)
  profile: null            # AWS CLI profile name (used if no direct keys)

  # Auth method 4: nothing at all; the default chain picks up env vars,
  # the EC2/ECS instance role (inherited role), or cached SSO credentials.

  # Role assumption (optional, layered on top of any method above)
  role_arn: null           # Full ARN of a role to assume via STS
  external_id: null        # ExternalId for the third-party auditor pattern
  role_session_name: cloudg-scan

  # Cross-account fan-out (optional)
  accounts: []             # Target account IDs (only if cross-account scanning)
  role_name: null          # IAM role to assume in each account

  # AWS Organizations / Control Tower discovery (`cloudg map --org`).
  # Run with management-account credentials; every selected member account
  # is mapped by assuming role_name there. AWSControlTowerExecution is admin:
  # prefer a read-only role (SecurityAudit + ViewOnlyAccess) deployed to all
  # accounts with a StackSet.
  organization:
    enabled: false
    role_name: null        # default: aws.role_name, then AWSControlTowerExecution
    include_ous: []        # OU IDs, ARNs or names (nested OUs included)
    exclude_accounts: []
    include_management_account: true
    include_suspended: false
    use_governed_regions: true   # regions [ALL] -> Control Tower governed regions
    control_tower: true    # map the landing zone, controls and baselines
    home_region: null      # Control Tower home region (auto-detected)
    map_structure: true    # org / OU / account / SCP / control nodes on the map

  max_retries: 10          # botocore retries per API call after the first attempt
  retry_mode: adaptive     # legacy | standard | adaptive (botocore client-side rate limiting)

Read from the annotated example config.yaml and the CloudGConfig models in cloudg/config.py.