Skip to main content

AWS

The AWS integration reads your account through a cross-account IAM role you create and let the platform assume. It is read-only - every call is a Describe, List or Get. Nothing is deployed into your account and nothing is changed.

One connection covers several sync types, each enabled individually under Integrations:

Sync typeReads
Resource inventoryEC2, AMIs, volumes and snapshots, VPCs, subnets, security groups, load balancers and Auto Scaling groups, S3, RDS, EKS, container and serverless resources
CloudTrail activityManagement-event history
CloudWatch logsLogs AWS pushes to a CloudWatch log group, picked up as a registered log source - set up separately from this role (see below)
GuardDuty findingsDetector findings
Posture assessmentThe cloud configuration checks behind Cloud Exposure

A missing permission fails only the sync types that depend on it and leaves the rest working, so an integration that returns AccessDenied on one sync type while the others collect is a policy that is too narrow, not a broken connection.

How the role is secured​

The platform assumes your role from its own AWS account. Two things make that safe:

  • Role delegation. You never hand over a long-lived access key. You create a role, grant the platform's AWS principal permission to assume it, and the platform receives only short-lived session credentials each time it runs.
  • An external ID. The platform generates a unique external ID for your integration and requires it on every assume-role call. Your role's trust policy demands the same value, so no other tenant - and no third party who learns your role ARN - can assume the role. This is the AWS-recommended guard against the "confused deputy" problem.

Create the read-only role​

  1. Under Integrations → Available Integrations, start adding AWS. The connect form shows the AWS principal to trust and a unique external ID. Keep both open for the next steps.

  2. In the AWS console, create an IAM role with a custom trust policy that trusts that principal and requires the external ID:

    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Effect": "Allow",
    "Principal": { "AWS": "<the AWS principal the connect form shows>" },
    "Action": "sts:AssumeRole",
    "Condition": {
    "StringEquals": { "sts:ExternalId": "<the external ID the connect form shows>" }
    }
    }
    ]
    }
  3. Attach a read-only permissions policy. The simplest is the AWS managed ReadOnlyAccess policy, which covers the resource inventory, CloudTrail, GuardDuty and posture sync types.

    To withhold data-plane reads, attach SecurityAudit instead: it covers resource inventory and posture assessment, but the CloudTrail and GuardDuty sync types then need their own read grants - cloudtrail:LookupEvents and guardduty:ListFindings / guardduty:GetFindings.

    CloudWatch log collection is not performed through this role - see CloudWatch logs are collected, not read.

  4. Back in the connect form, enter the role's ARN and the external ID, then submit. The integration appears under Active Integrations and discovery starts within a few minutes.

A whole organization at once​

Connect at the management or delegated-admin account and one connection covers the member accounts without connecting each one.

The role you connect lists the organization's accounts (organizations:ListAccounts) and assumes a same-named read-only role in each member account. Deploy that member- account role with a CloudFormation StackSet so every account - including ones created later - has it.

Connect at the highest scope you can

An organization-level connection picks up accounts created later without anyone remembering to add them. Account-by-account connections drift the moment someone provisions a new one, and the account nobody connected is exactly the one worth looking at.

CloudWatch logs are collected, not read​

The other sync types read your account through the role above. CloudWatch logs work differently: AWS pushes the logs you choose into a CloudWatch log group, and the platform collects that log group as a registered log source. It is a forwarding setup, not a read performed by this read-only role, so turning it on is separate from creating the role, and its volume is a SIEM cost worth setting deliberately. See Detection engineering for how log sources are tiered and priced.

Troubleshooting​

SymptomCauseFix
AccessDenied when the integration assumes the roleThe trust policy's external ID does not match, or it trusts the wrong principalRe-copy both values from the connect form into the role's trust policy
A sync type returns AccessDenied while others collectThe attached read-only policy does not cover that serviceUse ReadOnlyAccess, or add the service's read actions if you scoped the policy down
Member accounts are not discoveredThe member-account role is missing, or the connected role lacks organizations:ListAccounts or cannot assume itDeploy the member-account role everywhere (StackSet) and confirm the org-level role can list and assume
RAM-shared VPC resources are not storedThe resources live in another account shared in through AWS Resource Access ManagerAdd the owning account to the integration so the VPC is discovered there
Data stopped updating with no errorThe role was deleted or its policy narrowed on the AWS sideConfirm the role still exists and still carries read access

Legacy access-key setup​

Older connections authenticated with an IAM user's access key plus a cross-account assume-role name rather than a role ARN and external ID. That path still works, but role delegation with an external ID is preferred: an access key is a long-lived credential that has to be stored and rotated, and the external ID closes the confused-deputy gap that a bare role name leaves open. New connections should use the role ARN and external ID.

Next​

  • Cloud Exposure - connecting the account and what is assessed
  • Azure - the Azure app registration permissions each sync type needs
  • Integrations - every integration and what each contributes