Connect your AWS account to CloudLens
Your AWS administrator approves the setup in your own AWS account. CloudLens uses IAM roles and short-lived credentials for assessments. You do not need to create or share AWS access keys.
Before you start
- Sign in to the intended CloudLens workspace and the AWS account you want to assess. Confirm its 12-digit account ID in the AWS console.
- Ask an AWS administrator to complete the setup. They need permission to create CloudFormation stacks and IAM roles, and to enable any selected security standards. Organization policies or permission boundaries may require approval from your AWS platform team.
- Review the security standards you want enabled. Security Hub and other AWS services can incur charges in your AWS account. Check AWS pricing and existing service configuration before approving the stack.
1. Give CloudLens assessment access
- In CloudLens, open Connect AWS Account. Enter the AWS account ID if you know it, and select the security standards you want enabled. The current guided connection uses us-east-1.
- Choose Launch CloudFormation Stack. A new AWS console tab opens with your connection settings filled in. Keep the setup link private; it contains connection credentials.
- Confirm you are signed in to the correct AWS account. Review the template, selected standards, trusted CloudLens account, and IAM permissions. Keep the prefilled connection ID and External ID unchanged.
- Acknowledge the creation of named IAM resources, then choose Create stack. Wait for CREATE_COMPLETE. If AWS reports a failure, inspect the CloudFormation Events tab before retrying.
- Return to CloudLens. It checks setup automatically. If it remains pending, compare the stack’s ExternalId output with the CloudLens External ID and choose Check now. Continue when the connection says ACTIVE and shows the expected account ID.
- Run a live pillar or security-standard assessment. A standard may need time to finish provisioning before it can be scanned.
What access are you approving?
| Component | Purpose and access |
|---|---|
| CloudLens assessment role | The reviewed template creates CloudLensSecurityAuditRole-conn_aws_… for your connection. Older integrations use CloudLensSecurityAuditRole. The role trusts the CloudLens AWS account with your unique External ID and uses AWS SecurityAudit plus additional read permissions for findings, configuration, costs, and recommendations. Confirm the exact name in your stack's RoleArn output. |
| Customer setup functions | CloudFormation creates functions in your account to enable selected Security Hub standards and register the connection. Their setup permissions are separate from CloudLens’s assessment role. Removing the stack does not automatically disable Security Hub or the standards you enabled. |
| Information used in CloudLens | CloudLens reads resource identifiers, configuration, findings, and recommendations to generate and store assessment results. Review your organization’s data requirements before granting access. |
2. Optional: enable AWS Well-Architected Agent recommendations
The AWS Agent option appears on an active connection when enabled by CloudLens. It adds AWS-generated recommendations alongside your live scan results.
AWS currently requires Business+ or higher support for the Agent. Business and Developer support plans are not eligible. Profile hosting is limited to us-east-1, us-east-2, or us-west-2. See AWS prerequisites and setup.
- Describe your application in CloudLens. On your active AWS connection, enter its name and a short description, choose how important it is, and select a main priority. Choose Open prefilled AWS setup. A custom goal or a different profile hosting region is available under Advanced options. Do not include passwords, access keys, or sensitive business data.
- Approve one stack in AWS. Sign in to the account displayed in CloudLens. The AWS tab opens a prefilled stack review. Review the template and parameters, keep the connected account and region unchanged, acknowledge creation of IAM resources with custom names, then choose Create stack. The stack configures the profile, goal, application context, scanning roles, and CloudLens reader. You do not need to configure each of these manually in the AWS Agent or IAM consoles.
- Return to CloudLens. Wait for CREATE_COMPLETE. CloudLens verifies and registers access automatically; keep its page open to follow progress or use Check setup status. Connected — preparing recommendations means access is verified, while AWS may still be preparing results.
Closed the AWS tab? Choose Reopen AWS setup. This reuses your pending setup; if a stack is already being created, check that stack instead of creating another. The private template link lasts up to one hour and can be renewed while the two-hour setup remains valid. If setup expires, check the old stack before cancelling and starting again; retained resources from a failed stack may need administrator cleanup.
After AWS generates results, choose Import latest AWS recommendations. Import runs in the background and retrieves existing AWS results; it does not trigger a fresh AWS resource or application analysis. Initial results can take up to 48 hours; an empty import does not establish compliance.
CloudLens delivers your prepared template from encrypted private storage with a temporary signed link; setup values are prefilled without placing callback credentials in the console parameter URL. Treat the link as private. Prepared objects are scheduled for automatic cleanup after one day, and setup authorization expires after two hours. AWS administrators with permission to read the stack template can view its defaults; NoEcho masks parameter values but does not make template source inaccessible. The profile scans only your connected account and approved regions.
The AWS scanning role uses AWS’s managed resource-scanning policy. CloudLens’s separate reader role imports recommendations; this integration does not execute their proposed changes.
If you already have an AWS Agent profile, use Connect an existing agent profile. Select its hosting region, find profiles, and choose one covering only this connected account and approved regions. Your assessment role must allow the required Well-Architected read operations. Profiles containing other accounts are excluded.
3. Read and share the results
Download the assessment report to view its Executive Summary or Technical Deep-Dive. The report identifies the account, scanned regions, evidence source, scan time, cached results, collection limits, and unknown checks. Technical details include control results and resource identifiers.
AWS Agent recommendations appear in their own section with priority, effort, estimated benefit, trade-offs, and AWS record dates. They do not change the CloudLens control score. Import time identifies when CloudLens fetched the recommendations, rather than when AWS scanned or generated them. Save the chosen report view as PDF using Print.
If setup or import needs attention
| Status or issue | Next step |
|---|---|
| Agent section says Not enabled | The optional Agent rollout is not enabled on this CloudLens deployment. Ask your CloudLens administrator to finish rollout. The section appears below your active AWS account on the Connect AWS page; your live scans remain available. |
| AWS tab does not open | Allow the popup or use the setup link displayed in CloudLens. Confirm the AWS account before creating the stack. |
| Pending or expired Agent setup | Use Reopen AWS setup to renew a valid link, or Check setup status if the stack is already running. Template links last up to one hour; setup authorization lasts two hours. Check existing stacks before cancelling or retrying. Retained resources from a failed stack may need administrator cleanup. |
| Profile needs attention | In AWS, review profile validation errors, support eligibility, goals, application context, and the execution/access role trust policies. See AWS profile eligibility checks. |
| Unable to refresh / stale results | Check reader-role trust, External ID, read permissions, organization policies, and profile existence. Prior results may remain available and are marked stale. Retry later; imports are limited to once per hour after success. |
| No open or partial recommendations | Check AWS generation readiness and profile scope. Partial reports disclose missing or bounded content. Review the AWS console for the complete recommendation record. |
Remove or revoke access
- Stop Agent imports: choose Disconnect import in CloudLens. This stops future imports and removes the Agent section from new reports. Previously downloaded reports and stored assessment history remain.
- Revoke Agent reader access in AWS: delete the Agent CloudFormation stack, or have your administrator remove its
CloudLensWAReader-…role. Previously issued temporary sessions can remain valid until expiry; ask your administrator to revoke active role sessions if immediate revocation is required. - Remove the AWS Agent itself: the profile, goal, context, and scanning roles are deliberately retained when its stack is deleted. To stop AWS Agent scanning, remove its scanning-role permissions. If no longer needed, disable profile deletion protection and delete the profile and retained scanning roles in AWS.
- Disconnect the whole AWS account: disconnect it in CloudLens, then remove the original assessment stack or its CloudLens assessment-role trust in AWS. Review Security Hub standards and other services separately to decide whether to keep them enabled.
For help, contact support@cloudlensai.cloud with your account ID, stack status, and sanitized error message. Do not send setup links, External IDs, or AWS credentials.