AWS - OpenSRE Documentation

Overview

OpenSRE uses AWS to map your environment: Lambda functions, EKS clusters, S3 buckets, and more. It reads infrastructure state to build investigation context when cloud-related alerts fire. Related AWS tool pages (same credentials, no separate setup): EC2, ELB, S3, Lambda, and CloudTrail.

Prerequisites

AWS account with IAM permissions
Either a role ARN (recommended) or static access keys. A role ARN is assumed using your ambient AWS credentials — environment keys, an aws configure profile, or an attached instance/task role — so one of those must exist on the machine running OpenSRE

Setup

Option 1: Interactive CLI

opensre integrations setup aws

Provide a role ARN or static access keys when prompted. If you pick a role and this machine has no base AWS credentials, setup offers to switch to access keys, pause so you can run aws configure, or continue anyway (for EC2/ECS/Lambda with an attached role).

Option 2: Environment variables (IAM role)

AWS_ROLE_ARN=arn:aws:iam::123456789012:role/OpenSREReadOnly
AWS_EXTERNAL_ID=your-external-id     # optional
AWS_REGION=us-east-1

Option 3: Environment variables (static keys)

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=...                # optional, for temporary credentials
AWS_REGION=us-east-1

Variable	Default	Description
`AWS_ROLE_ARN`	—	IAM role to assume (recommended)
`AWS_EXTERNAL_ID`	—	External ID for role assumption
`AWS_REGION`	`us-east-1`	AWS region
`AWS_ACCESS_KEY_ID`	—	Static access key (if not using role)
`AWS_SECRET_ACCESS_KEY`	—	Static secret key
`AWS_SESSION_TOKEN`	—	Session token for temporary credentials

Either AWS_ROLE_ARN or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY is required. AWS_ROLE_ARN alone is not enough on a laptop: the role is assumed with whatever credentials boto3 finds (env keys, ~/.aws/credentials, or an instance/task role), and that identity needs sts:AssumeRole on the role.

For multiple AWS accounts or regions, use multi-instance with AWS_INSTANCES.

Option 4: Persistent store

{
  "version": 1,
  "integrations": [
    {
      "id": "aws-prod",
      "service": "aws",
      "status": "active",
      "credentials": {
        "role_arn": "arn:aws:iam::123456789012:role/OpenSREReadOnly",
        "external_id": "your-external-id",
        "region": "us-east-1"
      }
    }
  ]
}

Credentials

IAM role (recommended)

Create an IAM role that OpenSRE can assume (or attach to the host).
Attach read-only permissions (see below).
Set AWS_ROLE_ARN (and optional AWS_EXTERNAL_ID) or enter the ARN in opensre integrations setup aws.

Static access keys

Create an IAM user with the same read-only permissions.
Create an access key and set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN if temporary).

IAM permissions

OpenSRE needs read-only access. Attach the AWS managed ReadOnlyAccess policy, or a custom policy scoped to the services you want OpenSRE to inspect. For least privilege, the minimum services used are:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",
        "ec2:Describe*",
        "ecs:Describe*",
        "ecs:List*",
        "eks:Describe*",
        "eks:List*",
        "lambda:List*",
        "lambda:Get*",
        "s3:ListBucket",
        "s3:GetObject",
        "logs:FilterLogEvents",
        "logs:GetLogEvents",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "cloudtrail:LookupEvents",
        "elasticloadbalancing:DescribeTargetGroups",
        "elasticloadbalancing:DescribeTargetHealth"
      ],
      "Resource": "*"
    }
  ]
}

opensre integrations verify aws assumes AWS_ROLE_ARN when set. Many AWS investigation tools (S3, CloudTrail, EC2, ELB, Lambda) call AWS through the ambient credential chain (environment keys, shared profile, or instance/task role) and do not assume that role for the API call. Give S3/CloudTrail/EC2 permissions to the identity the OpenSRE process actually runs as.

Investigation tools

Area	Tools / capability
Core AWS	`execute_aws_operation` (manual / advanced; not auto-planned)
EC2	`ec2_instances_by_tag` — see EC2
ELB	`get_elb_target_health` — see ELB
S3	`list_s3_objects`, `inspect_s3_object`, `get_s3_object`, `check_s3_marker` — see S3
Lambda	`get_lambda_configuration`, `inspect_lambda_function`, `get_lambda_invocation_logs`, `get_lambda_errors` — see Lambda
CloudTrail	`lookup_cloudtrail_events` — see CloudTrail

Verify

opensre integrations verify aws

Expected output (role example):

Service: aws
Status: passed
Detail: Authenticated via assume-role in us-east-1 as arn:aws:iam::123456789012:role/OpenSREReadOnly (account 123456789012)

Expected output (static keys example):

Service: aws
Status: passed
Detail: Connected to AWS STS via static-creds in us-east-1; caller identity account=123456789012 arn=arn:aws:iam::123456789012:user/opensre.

Inside the REPL: /integrations verify aws or /verify aws. Aliases such as eks also map to this check.

Troubleshooting

Symptom	Fix
Unable to locate credentials (role ARN setup)	You chose IAM Role ARN but nothing on this machine has base AWS credentials. The setup wizard detects this when you pick the role option and offers to switch to Access Key + Secret, or to pause while you run `aws configure` / export `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` for an identity allowed to assume the role. If you set `AWS_ROLE_ARN` by hand instead of through the wizard, provide one of those base credentials
AccessDenied on STS	Ensure the caller has `sts:AssumeRole` permission on the target role
InvalidClientTokenId	Check that `AWS_ACCESS_KEY_ID` is correct and the key is active
Could not connect to endpoint	Check `AWS_REGION` and network connectivity
ExpiredTokenException	Refresh your session token or rotate the access key
Verify passes but S3/CloudTrail/EC2 tools fail	Those tools use the ambient credential chain, not only the role assumed during verify — attach the needed IAM actions to that identity

Security

Prefer IAM roles over static keys wherever possible.
Scope IAM permissions to only the AWS services OpenSRE needs to inspect.
Rotate static access keys regularly.
Enable CloudTrail so all OpenSRE API calls are auditable.
Store keys in .env or your secret manager — not in source control.

​Overview

​Prerequisites

​Setup

​Option 1: Interactive CLI

​Option 2: Environment variables (IAM role)

​Option 3: Environment variables (static keys)

​Option 4: Persistent store

​Credentials

​IAM role (recommended)

​Static access keys

​IAM permissions

​Investigation tools

​Verify

​Troubleshooting

​Security

Overview

Prerequisites

Setup

Option 1: Interactive CLI

Option 2: Environment variables (IAM role)

Option 3: Environment variables (static keys)

Option 4: Persistent store

Credentials

IAM role (recommended)

Static access keys

IAM permissions

Investigation tools

Verify

Troubleshooting

Security