Connect an AWS account

This page describes how to give Ctadel access to an AWS account: read permissions for the inventory and the configuration, and, for the content analyses, permissions to create and delete ephemeral resources, which the template grants by default and which you can refuse option by option. It then describes what the collector reads.

Two ways to authenticate

In both cases, the collector checks the identity it obtained with sts:GetCallerIdentity at the start of each scan and derives the account number from it if you did not enter one.

Creating the role with the CloudFormation template

The CloudFormation template aws-ctadel-role.yaml is handed to you by the Ctadel team. Deploy it in every account to scan:

aws cloudformation deploy \
  --template-file aws-ctadel-role.yaml \
  --stack-name ctadel-scanner \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
      CtadelPrincipalArn=<ARN_GIVEN_BY_CTADEL> \
      ExternalId=<EXTERNAL_ID>

The created role carries the managed policies SecurityAudit and job-function/ViewOnlyAccess, plus a read policy CtadelReadExtras for what those two do not cover: the IAM credential report (root account and key hygiene), Shield, load balancer TLS policies, Lambda function code and configuration, ECR repository and EFS file system policies, EKS access entries, transit gateway attachments, Resolver query logging, the Bedrock and SageMaker inventory, and service-specific credentials.

The trust policy accepts only the principal of your Ctadel instance, and only when the call carries the external ID.

Template parameters

With the default values, the role created is therefore not a read-only role: EnableDiskScanning and EnableDatabaseScanning add the creation of snapshots, volumes, instances, key pairs, security groups and temporary RDS instances. Set them to false for a role limited to reading; the inventory, the configuration and bucket reading stay complete, only disks and databases are no longer read. The write permissions these options grant are bounded: deletions (volumes, snapshots, instances, database copy) apply only to resources tagged ctadel-managed=true, and the role can set that tag only while creating a resource. With EnableSSMTransport, commands can only target instances carrying that tag.

The template outputs give RoleArn (to paste into Ctadel), ScannerInstanceProfileName (with SSM) and EnabledCapabilities, a summary of the chosen options.

Declaring the account in Ctadel

1. Open "Settings", tab "Integrations", sub-tab "Cloud Providers", then "Add account" on the Amazon Web Services row.
2. Enter a "Label".
3. Under "How Ctadel authenticates", keep "Assume a role (recommended)".
4. Click "Generate" next to "External ID", then deploy the template with that value.
5. Paste the RoleArn output into "Role ARN".
6. Click "Discover": Ctadel assumes the role and lists the account, or the accounts of the organisation.
7. Click "Create", or "Add the N accounts" if several were discovered.

At the start of each scan, Ctadel assumes the role with the external ID and obtains temporary credentials, used for the inventory and the content analyses. The requested session lasts twelve hours; one hour if the role refuses.

If you switch mode later, the stored credentials are replaced: fill in every field of the new mode.

Access key mode

Create an IAM user, attach SecurityAudit and ViewOnlyAccess, and add the actions listed under CtadelReadExtras in the template for the same coverage. Choose "Access key" in the dialog and fill in "Access Key" and "Secret Key". The content analysis options then correspond to the CtadelDiskScanning, CtadelDatabaseScanning, CtadelBucketScanning and CtadelKubernetesAccess policies of the template, to reproduce on the user.

A whole organisation

If the role is deployed in the management account and may call organizations:ListAccounts, "Discover" returns every active account of the organisation. Ctadel expects a role of the same name in each member account, which a StackSet deployment of the template produces; "Add the N accounts" creates one entry per account with the matching ARN. Without that permission, discovery falls back to the role's own account.

What the collector reads

The collector enumerates the account's enabled regions with ec2:DescribeRegions; if that call fails, it falls back to a fixed list of seventeen regions. Global services (IAM, CloudFront, Route 53) are read in us-east-1.

A region the account has not enabled, that a service control policy denies, or in which a service has no endpoint, is skipped for that service. If some collectors fail, the account goes to the "Partial scan" state with the number of failed collectors; what was read is kept.

Limitations

• Detection on CloudTrail logs (EnableRuntimeEvents option, SQS queue) is under internal validation and is not available to customers. You may leave the option at false.
• The Ctadel principal ARN (CtadelPrincipalArn) is not shown in the interface; the Ctadel team gives it to you.
• If ec2:DescribeRegions fails, only the seventeen regions of the fallback list are read.
• S3 objects larger than 10 MB are not read.
• Without lambda:GetFunction, Lambda function code is not read, only its configuration.
• In a member account that cannot call organizations:ListAccounts, a Lambda layer published by another account of the organisation stays of unknown origin.
• Disk analysis requires a network path to the scanner machine: a public address by default, a private subnet with peering or VPN, or SSM transport. See Scanner settings.
• On the disk copy, host compliance checks that need a running system are reported as skipped; see Hosts.