See what an AWS IAM role can do

What you see for each role

A role's access is spread over its trust policy, managed and inline policies and permissions boundary. The IAM Lab puts it together, from a scan of the account:

• Every action it is allowed, service by service, with the resources and conditions that apply and the policy statement behind each. Actions are marked allowed, scoped to some resources, conditional or denied, and counted by access level: List, Read, Write, Permissions management and Tagging.
• Who can assume it, in plain words: an AWS service, another account or a GitHub Actions workflow through OIDC, with its conditions spelled out, such as “Only GitHub repo acme/app on any branch”.
• Its policies and permissions boundary, and when it was last used.
• Its risks, such as administrator access, privilege escalation and trust from other accounts.
• Exports as JSON, Markdown or CSV, for a review or a ticket.

Read-only, with your own profile

• No role to deploy. Goku uses an AWS profile you already have: access keys, IAM Identity Center (SSO) or assume-role.
• Read-only, always. Every AWS call made with a profile passes a read-only guard, so nothing in the account can change, even when the profile is an administrator. Only these calls can be sent: sts:GetCallerIdentity; IAM operations that start with Get, List or Simulate; the Access Analyzer checks ValidatePolicy, CheckNoNewAccess, CheckAccessNotGranted and CheckNoPublicAccess; Organizations Describe and List calls; and SSO's GetRoleCredentials. sts:AssumeRole runs only to follow an assume-role profile. Anything else fails before it is signed.
• Credentials in memory only. They are never saved, logged or returned by any API, and Goku keeps them only until they expire.
• Your ~/.aws is mounted read-only, and only the IAM Lab reads it.

The profile needs IAM read access: the AWS managed policies IAMReadOnlyAccess, SecurityAudit or ReadOnlyAccess are enough.

Install or update Goku

Role access needs Goku 4.2 and goku CLI 0.6.0 or later. On macOS and Linux:

$ curl -fsSL https://tanuj24.github.io/goku/install.sh | sh

On Windows, in PowerShell:

PS> irm https://tanuj24.github.io/goku/install.ps1 | iex

Already installed? Run goku update --cli, then goku update.

goku start mounts your AWS config folder read-only into Goku (~/.aws, or %USERPROFILE%\.aws on Windows, at /run/goku/aws), so the console can list your profiles. Files that AWS_CONFIG_FILE or AWS_SHARED_CREDENTIALS_FILE name elsewhere are mounted read-only too. goku update recreates an existing container to add the mount, and goku doctor shows whether it is there. GOKU_AWS_PROFILES=off leaves it out.

Running the image with plain Docker? Add the mount to your docker run:

$ mkdir -p ~/.goku/data
docker run -d --name goku \
  -p 8080:80 -p 4566:4566 -p 5500-5524:5500-5524 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.goku/data:/app/data \
  -v /tmp/goku-glue:/tmp/goku-glue \
  -v ~/.aws:/run/goku/aws:ro \
  tanujsoni027/goku:latest

In PowerShell, the mount is -v "$env:USERPROFILE\.aws:/run/goku/aws:ro". The rest of the command is on the install page.

Connect a profile

In the console

Open IAM in the console and choose Role access, http://localhost:8080/iam/roles. Your profiles are listed with their type and region; Connect scans the account's IAM (roles, users and policies) into a snapshot.

From a terminal

$ goku iam profiles                 # type, region, SSO account and role; never keys
goku iam connect --profile prod   # sign in, connect read-only, scan

$ goku iam connect --profile prod
getting credentials for profile prod from the AWS CLI…
connecting profile prod to Goku (read-only)…
  ✔ profile credentials                   terminal session
  ✔ sts:GetCallerIdentity                 arn:aws:sts::123456789012:assumed-role/Admin/me
  ✔ iam:GetAccountAuthorizationDetails    allowed
  – iam:SimulatePrincipalPolicy           optional — AccessDenied: not allowed
Connected acme-prod (123456789012) with profile prod: 213 roles, 45 users, 1,204 policies.

goku iam connect takes the profile from --profile, else AWS_PROFILE, the only profile or default, or asks. It gets the profile's credentials on your machine with the AWS CLI (aws configure export-credentials), so SSO, MFA codes and credential helpers work, and it runs aws sso login first when an SSO sign-in has expired. Goku receives a session in the body of one request, never on a command line, on disk or on screen. Without the AWS CLI, only access-key profiles work.

No goku CLI at hand? Paste temporary credentials in the console takes the output of aws configure export-credentials --profile NAME --format env.

Pick a role and see its access

The roles list shows who each role trusts, when it was last used and its policies, with filters for service roles, cross-account roles, federated (OIDC or SAML) roles and roles not used in 90 days. Service-linked roles are hidden unless you ask for them.

$ goku iam roles                                  # NAME, TRUSTED BY, LAST USED, POLICIES
goku iam roles deploy                           # search name, path, ARN or who it trusts
goku iam access ci-deployer                     # who can assume it, policies, access per service, risks
goku iam access ci-deployer --service s3,iam    # and its S3 and IAM actions
goku iam access ci-deployer --all --json > ci-deployer.json
goku iam access ci-deployer --open              # the role in the console

--profile NAME or --connection ID picks the account; the default is the profile you scanned most recently. The answers come from the scan, not from new calls to AWS, so rescan from the roles list, or run goku iam connect again, to see changes made since. In the console, Export saves a role's access as JSON, Markdown or CSV.

Ask your AI assistant

Goku's MCP server has four tools for the roles of your AWS account:

When a profile needs you, for an SSO sign-in or an MFA code, the tool says which command to run in your terminal. Ask, for example:

• List my AWS profiles and connect dev.
• Which roles in my dev account can another account assume?
• What can ci-deployer do in S3, and who can assume it?

More Goku guides