Connecting an AWS account
Cloudbrief reads your AWS account via a read-only IAM role that you create in your account and grant sts:AssumeRole to our app's IAM principal. We never get long-lived credentials and never get write access to anything.
What the role can do
Exactly these read-only actions:
| Service | Actions | What it covers |
|---|---|---|
| Cost Explorer | ce:GetCostAndUsage, ce:GetCostAndUsageWithResources | Week-on-week cost regression detection |
| CloudWatch | cloudwatch:GetMetricData, cloudwatch:ListMetrics, cloudwatch:DescribeAlarms | Time-series collection for RDS + ALB + EB |
| CloudTrail | cloudtrail:LookupEvents | Write-event correlation during investigations |
| RDS | rds:DescribeDBInstances, pi:GetResourceMetrics, pi:DescribeDimensionKeys | Performance Insights top SQL during the analysis window |
| ELB | elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeTargetHealth | Load balancer health snapshots |
| Elastic Beanstalk | elasticbeanstalk:DescribeEvents, elasticbeanstalk:DescribeEnvironments | Deploy + scaling event correlation |
| S3 (access logs only) | s3:GetObject, s3:ListBucket (only on the specific access-log bucket you tell us) | HTTP access log mining |
| STS | sts:GetCallerIdentity | Connection health check |
No write actions, no IAM changes, no secret reads. The CloudFormation template that creates the role uses these exact permissions and nothing more.
Walkthrough
Step 1 — copy the CloudFormation template
In the app, Cloudbrief → AWS accounts → "Add account" → "I'll set up the IAM role next". The template that appears is parameterised with our IAM principal ARN (arn:aws:iam::099547753263:user/analyzer-app-runtime) and the external-id we generate per connection.
Step 2 — paste into CloudFormation
In your AWS console:
- CloudFormation → Stacks → Create stack → "With new resources (standard)"
- Template source: Upload a template file (or paste the template body)
- Stack name:
cloudbrief-readonly(any name) - Leave parameters as auto-filled
- Acknowledge the IAM capability checkbox
- Create stack
It takes about 30 seconds. The stack output has the RoleArn — copy it.
Step 3 — paste the role ARN back into the app
In Cloudbrief, paste the role ARN and click Connect. The app does an immediate sts:AssumeRole + sts:GetCallerIdentity to verify the trust relationship works. If it does, the connection turns green and the first daily analysis is scheduled for the next 09:00 IST window.
Multiple accounts
Repeat the same process for each account. Each gets its own role, its own email recipient list, and its own per-account usage tracking. No per-account fee.
Rotating the external-id
The external-id we generated is bound to the connection. If you want to rotate it (e.g. security review request), delete the connection in the app and re-add it — a fresh external-id is generated. You'll need to update the CloudFormation stack's ExternalId parameter or recreate the stack.
Revoking access
Two ways, equivalent end-state:
- Delete the CloudFormation stack in your AWS account. The IAM role is removed; we can no longer assume it. The Cloudbrief app will flag the connection as broken on the next run.
- Delete the AWS account in the Cloudbrief app. We stop attempting to assume the role. The role in your account stays in place (orphan) until you also delete the stack — harmless but tidy people delete both.
What we don't read
For absolute clarity, our role does NOT have permission to:
- Read any S3 bucket other than the access-log buckets you list
- List or read any database contents
- See any secrets in Secrets Manager or SSM
- Read CloudWatch Logs (we use the access-log path on S3 instead)
- See any KMS-encrypted data
- Make any write call to any service
The permissions are enumerated above; nothing more is granted.
Troubleshooting
See Troubleshooting → Connection issues for the common errors and how to fix them.