Why a role, not access keys
Access keys are long-lived secrets that have to be stored, rotated and eventually leak. A cross-account role gives the scanner short-lived credentials each time it scans, and you can remove access at once by deleting the role. Nothing secret is shared in either direction.
What the external ID is for
The role's trust policy allows one principal, the scanner's role in its own AWS account, and requires an external ID that is unique to your organization. Without it, anyone else using the same scanner could ask it to scan your account if they learned your role's ARN (the confused-deputy problem). With it, only scans made for your organization can assume your role.
Which permissions it needs
Two AWS managed policies cover it:
- SecurityAudit: read access to security configuration across services: IAM policies, security groups, encryption, logging settings.
- ViewOnlyAccess: list and describe access to resources across services, without reading their data.
Neither policy allows create, update or delete actions, and neither lets the scanner read the contents of S3 objects, databases or Secrets Manager secrets. Using AWS's managed policies also means they stay current as AWS adds services.
Connecting, step by step
- In the scanner, start connecting AWS. It shows its AWS account ID and your external ID.
- Launch the CloudFormation stack it gives you (or apply the equivalent Terraform). The stack creates one IAM role, AlyeSecurityReadOnly, with the trust policy and the two managed policies.
- Copy the role ARN from the stack's Outputs tab back into the scanner.
- The scanner checks it can assume the role and read, then starts the first scan.
Every account in an AWS Organization
Deploy the same template as a service-managed CloudFormation StackSet to the organization root. New accounts get the role automatically. StackSets skip the management account, so deploy the stack there once by hand if you want it scanned too.
Auditing and removing access
Every API call the scanner makes appears in your CloudTrail under the role's name, so you can see exactly what was read and when. To remove access, delete the CloudFormation stack, or the role itself. The next scan fails to assume the role and stops. For what the scan does with the configuration it reads, see what CSPM is.