Listing IAM Roles for Your Current AWS Account

Introduction

Ever tried to create or update a resource in the AWS console, only to find out you don't have permission?

If you've worked with AWS, I'm sure you've been there. I know I have - more times than I can count. Each time, I have to check which IAM roles are attached to my account and send a message to our infrastructure team asking for the necessary permissions.

In most organizations, AWS accounts follow the principle of least privilege, which is a security best practice. It minimizes the risk of granting excessive permissions. However, figuring out exactly what permissions each person needs for their specific use case can be tricky.

As your organization grows, so does the frequency of "I don't have permission" requests. When this happens, you'll want a quick way to check what roles your account actually has.

I Built a CLI Tool to List IAM Roles

Since checking IAM manually every time gets tedious, I created a command-line tool that displays all attached roles at once. It's called canido. canido means "Can I do?".

https://github.com/tttol/canido

With canido, you can quickly see all the roles attached to your currently logged-in AWS account.
Here's what it looks like:

% canido

--- Checking AWS credentials ---
Target role: AWSReservedSSO_CanidoInlinePolicy_f1d7ab46757a3473

==================================================
  1. Managed Policies
==================================================
[Policy ARN]: arn:aws:iam::aws:policy/IAMFullAccess
{
  "Statement": [
    {
      "Action": [
        "iam:*",
        "organizations:DescribeAccount",
        "organizations:DescribeOrganization",
        "organizations:DescribeOrganizationalUnit",
        "organizations:DescribePolicy",
        "organizations:ListChildren",
        "organizations:ListParents",
        "organizations:ListPoliciesForTarget",
        "organizations:ListRoots",
        "organizations:ListPolicies",
        "organizations:ListTargetsForPolicy"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ],
  "Version": "2012-10-17"
}
--------------------------------------------------

==================================================
  2. Inline Policies
==================================================
[Policy Name]: AwsSSOInlinePolicy
{
  "Statement": [
    {
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Effect": "Allow",
      "Resource": [
        "*"
      ],
      "Sid": "Statement1"
    },
    {
      "Action": [
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetRandomPassword",
        "secretsmanager:GetResourcePolicy",
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecretVersionIds",
        "secretsmanager:ListSecrets",
        "secretsmanager:BatchGetSecretValue"
      ],
      "Effect": "Allow",
      "Resource": [
        "*"
      ],
      "Sid": "Statement2"
    }
  ],
  "Version": "2012-10-17"
}
--------------------------------------------------

The implementation is straightforward - it calls the following AWS CLI commands in sequence and formats the output:

% aws sts get-caller-identity
% aws iam list-attached-role-policies --role-name MyRole
% aws iam get-policy-version --policy-arn ... --version-id ...

For macOS users, installation is available via Homebrew. You'll need to tap the repository first:

brew tap tttol/tap # Add the tap
brew install canido # Install canido

For Linux, you can install from the binary release. This method also works for macOS:

# For x86_64 (Intel/AMD)
curl -LO https://github.com/tttol/canido/releases/latest/download/canido-x86_64-unknown-linux-gnu.tar.gz
tar xzf canido-x86_64-unknown-linux-gnu.tar.gz
sudo mv canido /usr/local/bin/
canido --version

Windows users can follow the Linux instructions using WSL2. Unfortunately, I haven't prepared binaries for Command Prompt or PowerShell (mainly because I don't have a Windows environment to test with).

Design Decisions

Focused on the Essentials

I kept canido laser-focused on one thing: "display IAM roles attached to the currently logged-in AWS account." Any other features were deliberately left out. I could have added options like checking roles for other account IDs or displaying policies for specific role ARNs, but I decided against it.

My motivation for creating canido was simple: "I want to know what my current account can do." Checking other accounts or roles fell outside that scope. The name "canido" itself comes from "Can I do?" - focusing on your own capabilities, not others'.

--short Option

When you have many IAM roles or a single role contains numerous policies, the output can get long and hard to read. To address this, I added a --short option that displays only the names of attached IAM roles:

❯ canido --short
--- Checking AWS credentials ---
Target role: AWSReservedSSO_CanidoInlinePolicy_f1d7ab46757a3473

==================================================
  1. Managed Policies
==================================================
IAMFullAccess

==================================================
  2. Inline Policies
==================================================
AwsSSOInlinePolicy

Distributed via Homebrew

Since I'm a Mac user, I wanted to distribute canido via Homebrew. This was my first time distributing a tool through Homebrew, so it involved a lot of research and trial and error.

To distribute a package via Homebrew, you typically need to add it to the official homebrew/core repository. This requires meeting certain criteria, including being open source and having some level of popularity (like GitHub stars).

For lesser-known tools like canido, getting into core is a high bar. Instead, I used the "tap" feature, which allows anyone to distribute packages without going through the review process. The trade-off is that users need to add one extra line to tap the repository before installing:

brew tap tttol/tap # Add the tap
brew install canido # Install canido

Wrapping Up

I hope canido becomes useful for AWS users out there. If you find it helpful, please give it a star on GitHub!