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.

SecurityAudit includes the EKS Access Entry actions (eks:ListAccessEntries and eks:DescribeAccessEntry) and the AWS Identity Center and Identity Store actions that Cartography calls: sso:ListInstances, sso:ListPermissionSets, sso:DescribePermissionSet, sso:ListAccountAssignmentsForPrincipal, identitystore:ListUsers, identitystore:ListGroups, and identitystore:ListGroupMemberships.

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. Service control policy ingestion also calls ListPolicies, DescribePolicy, and ListTargetsForPolicy. A delegated administrator needs a delegation policy that allows these actions.

Optional Permissions#

SecurityAudit does not include the following actions. Grant them to ingest the corresponding data.

  • AWS Identity Center permission set ingestion requires sso:GetPermissionSet, which AWS evaluates together with sso:DescribePermissionSet.

  • Inspector ingestion requires inspector2:ListMembers. SecurityAudit includes inspector2:ListFindings.

  • SES email identity ingestion requires ses:ListEmailIdentities.

  • ECR pull through cache rule ingestion requires ecr:DescribePullThroughCacheRules.

  • AWS Glue connection ingestion requires glue:GetConnections.

  • Confirming the CodeBuild build named by an ECR image’s build ID tag requires codebuild:BatchGetBuilds, which SecurityAudit does not grant. Without it, images are still linked to their source through CodeBuild labels on the image or the same-named CodeBuild project, but no build-confirmed edges are created. When the build lookup is attempted and denied, build-confirmed edges from earlier syncs are left in place. See Build provenance from CodeBuild.

  • 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.

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

If neither is set, public parameter ingestion is disabled because AWS-managed namespaces can contain tens of thousands of parameters in every region. Set the CLI option or environment variable to opt in to the prefixes your deployment needs. Existing deployments that rely on Bottlerocket or EKS optimized AMI parameters must configure the previous default explicitly before upgrading: /aws/service/bottlerocket/,/aws/service/eks/optimized-ami/.

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.

AWS GovCloud (US) and Other Partitions#

Cartography supports accounts in AWS GovCloud (US). Set a GovCloud region, for example us-gov-west-1, on each profile or with AWS_DEFAULT_REGION. AWS_DEFAULT_REGION overrides the profile’s region. Without a GovCloud region, boto3 sends the account discovery and IAM calls to the commercial endpoints, and GovCloud credentials fail there.

When the AWS sync builds an ARN itself, it uses the partition of the regions it syncs, for example aws-us-gov. These ARNs then match the ARNs that AWS returns. All regions in --aws-regions must be in one partition, so sync each partition in a separate run. --aws-regions applies to every account in the run, so when you use it with --aws-sync-all-profiles, give each partition its own AWS config file. Use the GovCloud form of the managed policy ARN, for example arn:aws-us-gov:iam::aws:policy/SecurityAudit.

CloudFront is not available in AWS GovCloud (US), so Cartography skips the cloudfront sync for GovCloud accounts.

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#