awsacc

awsacc

A trusty helper for working with AWS account IDs.

Working with AWS account IDs often involves more manual effort than necessary. Often account IDs in ARNs have to be manually looked up in different files and compared with existing IDs. With a few accounts this can be manageable, but with a large number of accounts to manage it is difficult to keep track.

awsacc allows you to:

• quickly turn account ids into their human-readable names in any file.
• lookup account ids by their corresponding name and vice versa via CLI and thus make them processable.

It's designed to speeds up reviewing changes and finding account ID errors (e.g. misspelled, or unknown IDs) in files. It can also be used as part of a CI/CD pipeline to match used account IDs in files against a defined list of valid IDs.

Installation

You can find the latest release here (Linux, Win, Mac 64-bit).

You can also build awsacc from source (Go 1.16+ required).

git clone git@github.com:cbrgm/awsacc.git && cd awsacc
go mod vendor && make

Another option is to use awsacc inside a container

docker run --rm -it \
   -v ~/.aws/accounts.json:/data/accounts.json \
   -v $(pwd):$(pwd) \
   cbrgm/awsacc:latest -f $(pwd)/file.json

where ~/.aws/accounts.json is your config file and $(pwd)/file.json is the file to check.

Configuration

A configuration file must be created so that the tool can search and substitute AWS account names and IDs. The configuration file is a JSON file consisting of accounts (tuples of names and IDs).

By default, it is stored under the path $HOME/.aws/accounts.json. You can also reference a config file via the environment variable AWSACC_CONFIG (Example: export AWSACC_CONFIG=/path/to/config.json).

~/.aws/accounts.json

{
    "Accounts": [
        {
            "Id": "620791285726",
            "Name": "Foo",
        },
    ]
}

The schema can be created manually or easily obtained using the aws CLI.

aws organizations list-accounts > ~/.aws/accounts.json

Note: This operation can be called only from the organization's management account or by a member account that is a delegated administrator for an AWS service. (API Reference)

Usage

The use of the tool can be accessed through the help subcommand

Usage: awsacc [options] [subcommand] [options] <args>

Replaces AWS account ids with their human-readable names
	-c Colored output. Default: false
	-f Path to the input files. Default: Stdin
	-s Strict mode, return on error. Default: false
	-v Verbose output. Default: false

Subcommand: search, ls
Description: Searches and prints out account ids or account names
	-c Colored output. Default: false
	-s Strict mode, return on error. Default: false
	-v Verbose output. Default: false

Examples

Here are some examples of what you can do with awsacc

Replace and highlight AWS account ids with their names

We assume that a file test.json exists. (Does not have to be JSON only, any kind of text file is possible).

$ cat test.json

Output:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Example`:",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::614912345005:role/somebody",
                "arn:aws:iam::866714215829:role/somebody",
                "arn:aws:iam::012073564612:role/somebody"
            ]
        }
    ]
}

We can now replace the account IDs with the human-readable names, color-code the changed lines and print them out

$ cat test.json | awsacc -c -v

Output:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Example`:",
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole"
      ],
      "Resource": [
+        "arn:aws:iam::production:role/somebody",
-        "arn:aws:iam::614912345005:role/somebody",
+        "arn:aws:iam::integration:role/somebody",
-        "arn:aws:iam::866714215829:role/somebody",
+        "arn:aws:iam::development:role/somebody",
-        "arn:aws:iam::012073564612:role/somebody"
      ]
    }
  ]
}

Or we let only the changed lines be colored, without showing removed lines

$ cat test.json | awsacc -c

Output:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Example`:",
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole"
      ],
      "Resource": [
+        "arn:aws:iam::production:role/somebody",
+        "arn:aws:iam::integration:role/somebody",
+        "arn:aws:iam::development:role/somebody",
      ]
    }
  ]
}

Lookup AWS account ids or names

List all accounts ids of accounts containing dev in their name

awsacc ls dev

List all accounts names of accounts containing 00124 in their account id

awsacc ls 00124

List all accounts names of accounts 312345643213, 612345343211 and 822345643215

awsacc ls 312345643213 612345343211 822345643215

List all accounts ids of accounts containing doesntexist in their name, use strict mode -s to exit with err 1 when no results have been found

awsacc ls -s doesntexist

Count all accounts ids of accounts containing dev or int or prd in their name

awsacc ls dev int prod | wc -l

List all accounts and search for an account or id using fzf and copy the result to your clipboard

awsacc ls -v '*' | fzf | pbcopy

Usage in your CI/CD pipeline

It can also be used as part of a CI/CD pipeline to match used account IDs in files against a defined list of valid IDs from your configuration.

awsacc searches below the path recursively in all directories for matching files and returns an error code 1 if an ID was found that is not stored in the configuration.

awsacc -s -f './path/to/*.json'

is equivalent to

cat './path/to/*.json' | awsacc -s

Contributing & License

Feel free to submit changes! See the Contributing Guide. This project is open-source and is developed under the terms of the Apache 2.0 License.