AWS Organizations#

Cartography models an AWS organization separately from normal account-scoped resource syncs. The hierarchy consists of AWSOrganization, AWSOrganizationRoot, AWSOrganizationalUnit, and AWSAccount nodes.

Account lifecycle and placement#

Accounts discovered through AWS Organizations retain the lifecycle information returned by AWS:

  • state is the current AWS Organizations lifecycle state.

  • status is the legacy status value. AWS recommends using state.

  • joined_method and joined_timestamp describe how and when the account joined.

  • org_id identifies the organization that contains the account.

Configured sync accounts are marked inscope=true. An account discovered only through AWS Organizations is not automatically marked in scope. Use org_id and the placement relationships when querying organization membership.

Only active organization accounts are placed beneath a root or organizational unit and receive a synced AWS account root principal. Suspended and closed accounts remain as AWSAccount nodes with their organization metadata, but they are not attached to the active root/OU hierarchy.

Placement is represented in both directions:

(:AWSOrganizationRoot)-[:RESOURCE]->(:AWSAccount)
(:AWSOrganizationalUnit)-[:RESOURCE]->(:AWSAccount)
(:AWSAccount)-[:PARENT]->(:AWSOrganizationRoot)
(:AWSAccount)-[:PARENT]->(:AWSOrganizationalUnit)

Organizational units can be nested beneath a root or another OU. Root and OU IDs are scoped to an organization, so Cartography IDs use {org_id}/{root_id} and {org_id}/{ou_id}.

Find active account placement:

MATCH (org:AWSOrganization)-[:RESOURCE]->(root:AWSOrganizationRoot)
MATCH path = (root)-[:RESOURCE*1..]->(account:AWSAccount)
RETURN org.id, account.id, account.name, account.state,
       [node IN nodes(path) WHERE node:AWSOrganizationalUnit | node.name] AS organizational_units
ORDER BY org.id, account.name

Find organization accounts that are retained but not currently placed in the active hierarchy:

MATCH (account:AWSAccount)
WHERE account.org_id IS NOT NULL
  AND NOT (account)-[:PARENT]->(:AWSOrganizationRoot)
  AND NOT (account)-[:PARENT]->(:AWSOrganizationalUnit)
RETURN account.org_id, account.id, account.name, account.state, account.status
ORDER BY account.org_id, account.name

Failure-safe cleanup#

Cartography cleans up Organizations hierarchy data only after successfully enumerating the complete hierarchy. If the Organizations API is unavailable, access is denied, or enumeration is incomplete, cleanup is skipped so that a transient failure does not erase the previously known hierarchy.

Organizations cleanup removes stale placement metadata, roots, OUs, and hierarchy relationships. It does not delete AWSAccount nodes or their account-scoped resources when accounts move, leave the organization, or become inactive.

For reliable hierarchy syncs, use credentials for the management account or a delegated administrator account. See AWS Configuration for credential and multi-account behavior.