AWS Configuration#

Prerequisites#

Configure ~/.aws/credentials and ~/.aws/config for the AWS identities that Cartography should use. Cartography follows the standard boto3 credential resolution order.

For AWS Organizations hierarchy data, include credentials for the management account or a delegated administrator account.

Authentication#

Single Account#

Configure credentials for an AWS user or role. A single-account sync uses boto3’s normal credential resolution behavior.

Multiple Accounts#

The recommended setup is one named AWS profile for each account and --aws-sync-all-profiles.

For a hub-and-spoke deployment on EC2:

  1. Create a cartography-read-only role in every account.

  2. Allow the hub account to assume that role in each spoke account.

  3. Create a cartography-service role in the hub account that can call sts:AssumeRole on arn:aws:iam::*:role/cartography-read-only and ec2:DescribeRegions.

  4. Attach cartography-service to the EC2 instance running Cartography.

  5. Add a profile for each account to the AWS config file:

    [profile accountname1]
role_arn = arn:aws:iam::<AccountId#1>:role/cartography-read-only
region = us-east-1
output = json
credential_source = Ec2InstanceMetadata

[profile accountname2]
role_arn = arn:aws:iam::<AccountId#2>:role/cartography-read-only
region = us-west-1
output = json
credential_source = Ec2InstanceMetadata

The spoke role trust relationship should allow the hub account to assume it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<HubAccountId>:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Required Permissions#

Attach the AWS managed SecurityAudit policy (arn:aws:iam::aws:policy/SecurityAudit) to every identity or cartography-read-only role used by Cartography.

Full AWS Organizations hierarchy enumeration requires credentials from the management account or a delegated administrator account. Grant organizations:Describe* and organizations:List* permissions. The managed SecurityAudit policy includes these actions, but member accounts cannot call hierarchy APIs such as ListRoots, ListAccountsForParent, and ListOrganizationalUnitsForParent.

Optional Permissions#

  • Inspector ingestion requires the AmazonInspector2ReadOnlyAccess policy.

  • EKS Access Entry ingestion requires eks:ListAccessEntries, which SecurityAudit includes. Grant eks:DescribeAccessEntry to populate detailed fields such as the ARN, username, type, and Kubernetes groups.

  • Allowlisted AWS-managed public SSM parameters require ssm:GetParametersByPath for the applicable /aws/service/... paths. AWSPublicSSMParameter nodes represent shared regional catalog data and are not resources owned by the account performing the sync.

  • The ecr:pull_through_cache_rules requested sync requires ecr:DescribePullThroughCacheRules.

  • AWS Glue connection ingestion requires glue:GetConnections, which SecurityAudit does not include.

Configure Cartography#

For a single account, no AWS-specific selection flag is required after configuring credentials.

For multiple accounts, use --aws-sync-all-profiles. To make Organizations discovery predictable at scale, pass the management or delegated administrator account ID with --aws-organization-account-ids.

Run Cartography#

Run a single-account sync:

cartography --selected-modules aws

Run all configured profiles and use a specific Organizations account:

cartography \
  --selected-modules aws \
  --aws-sync-all-profiles \
  --aws-organization-account-ids 123456789012

Advanced Configuration#

Selective Syncing#

Use --aws-requested-syncs with a comma-separated list of resource identifiers to limit the resource types that Cartography syncs. Cartography handles resource dependencies and sync order.

cartography \
  --selected-modules aws \
  --aws-requested-syncs "ec2:instance,s3,iam"

Additional examples:

cartography --selected-modules aws --aws-requested-syncs "ecr,lambda_function"
cartography --selected-modules aws --aws-requested-syncs "ecr:pull_through_cache_rules"

For the current identifier list, see the RESOURCE_FUNCTIONS dictionary in cartography/intel/aws/resources.py.

SSM Public Parameter Prefixes#

Cartography ingests AWS-managed public SSM parameters only when their names start with an allowlisted prefix. Configure a comma-separated list with --aws-ssm-public-parameter-prefix-allowlist or, when the option is omitted, with AWS_SSM_PUBLIC_PARAMETER_PREFIX_ALLOWLIST.

The configuration priority is:

  1. --aws-ssm-public-parameter-prefix-allowlist

  2. AWS_SSM_PUBLIC_PARAMETER_PREFIX_ALLOWLIST

  3. The built-in defaults: /aws/service/bottlerocket/ and /aws/service/eks/optimized-ami/

Set the CLI option or environment variable to an empty string to disable public parameter ingestion.

export AWS_SSM_PUBLIC_PARAMETER_PREFIX_ALLOWLIST="/aws/service/eks/optimized-ami/,/aws/service/custom/"
cartography --selected-modules aws --aws-requested-syncs ssm

Retry and Timeout Settings#

Cartography-managed AWS clients use these environment variables:

  • CARTOGRAPHY_AWS_RETRY_MODE: standard, adaptive, or legacy. The default is standard.

  • CARTOGRAPHY_AWS_MAX_ATTEMPTS: Maximum retry attempts. The default is 3.

  • CARTOGRAPHY_AWS_READ_TIMEOUT: Read timeout in seconds. The default is 120.

Lambda regional calls use a 30-second read timeout and two attempts while inheriting the shared retry mode. These settings take precedence over ambient AWS retry environment variables for clients configured by Cartography.

Regional STS Endpoints#

To avoid InvalidToken errors when assuming roles across regions, add sts_regional_endpoints = regional to the AWS config file or set AWS_STS_REGIONAL_ENDPOINTS=regional.

Troubleshooting#

If hierarchy APIs are unavailable, Cartography skips AWS Organizations cleanup and continues account resource sync. Verify that the selected Organizations account is the management account or a delegated administrator and can enumerate the complete hierarchy.

References#