{"id":15517321,"url":"https://github.com/skx/aws-utils","last_synced_at":"2025-07-02T17:02:56.920Z","repository":{"id":39969908,"uuid":"438941922","full_name":"skx/aws-utils","owner":"skx","description":"A small collection of AWS utilities, packaged as a single standalone binary.","archived":false,"fork":false,"pushed_at":"2023-08-23T17:19:24.000Z","size":113,"stargazers_count":14,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-17T19:18:11.330Z","etag":null,"topics":["aws","aws-ec2","ec2","golang","security-automation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"skx","custom":"https://steve.fi/donate/"}},"created_at":"2021-12-16T10:03:05.000Z","updated_at":"2023-09-01T16:48:17.000Z","dependencies_parsed_at":"2024-06-19T04:00:52.288Z","dependency_job_id":"0235fdf0-29a9-4eee-bb04-86edf173a207","html_url":"https://github.com/skx/aws-utils","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Faws-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Faws-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Faws-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Faws-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skx","download_url":"https://codeload.github.com/skx/aws-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250369120,"owners_count":21419190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-ec2","ec2","golang","security-automation"],"created_at":"2024-10-02T10:12:30.063Z","updated_at":"2025-04-23T04:26:44.811Z","avatar_url":"https://github.com/skx.png","language":"Go","funding_links":["https://github.com/sponsors/skx","https://steve.fi/donate/"],"categories":[],"sub_categories":[],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/skx/aws-utils)](https://goreportcard.com/report/github.com/skx/aws-utils)\n[![license](https://img.shields.io/github/license/skx/aws-utils.svg)](https://github.com/skx/aws-utils/blob/master/LICENSE)\n[![Release](https://img.shields.io/github/release/skx/aws-utils.svg)](https://github.com/skx/aws-utils/releases/latest)\n\n# AWS Utils\n\nThis repository contains a simple CLI utility with a number of useful sub-commands for working with AWS, particularly for scripting and automation purposes.\n\n\n## Motivation\n\nSeveral of the things that this tool does are possible via existing AWS utilities, such as the `aws-cli` package.  However the difference in this tool is that it allows working across roles as a single command - so rather than running an export/list command 20+ times in the traditional way, you can run one command passing the list of roles to use, and all output will be created at once.\n\nOther sub-commands are just more useful, for example listing the available cloudformation stack-names with `aws-cli` will include deleted ones too, which need to be filtered out.  Or allowing all stacks to be updated with a stack protection policy as a single command is just a time-saver.\n\n\n\n## Installation\n\nIf you the golang development tools installed upon your host, and you're running a recent version, you should be able to download and install via:\n\n```\ngo install github.com/skx/aws-utils@latest\n```\n\nOr, after having cloned [this repository](https://github.com/skx/aws-utils) to your system, you can build from source with a simple:\n\n```\ngo build .\ngo install .\n```\n\nIf you don't wish to build from source you should be able to find precompiled binaries for several operating systems upon our [releases page](https://github.com/skx/aws-utils/releases/)\n\nThe binary contains embedded support for bash-completion, to enable this add the following to your bash startup-file:\n\n```\nsource \u003c(aws-utils bash-completion)\n```\n\n\n\n## Help\n\nThere is integrated help for each sub-command, for example running with no arguments will show you available commands:\n\n```sh\n$ aws-utils\nPlease specify a valid subcommand, choices are:\n\n\tbash-completion Generate and output a bash completion-script.\n\tcommands        Show all available sub-commands.\n\tcsv-instances   Export a summary of running instances.\n\thelp            Show usage information.\n\tip              Show the private IP of the given instance.\n\tinstances       Export a summary of running instances.\n\torphaned-zones  Show orphaned Route53 zones.\n\trotate-keys     Rotate your AWS access keys.\n\tsg-grep         Security-Group Grep\n\tstacks          List all cloudformation stack-names.\n\tsubnets         List subnets in all VPCs.\n\tversion         Show the version of this binary.\n\twhitelist-self  Update security-groups with your external IP.\n\twhoami          Show the current AWS user or role name.\n```\n\nReading the help text, recommended, is down via the `help` sub-command:\n\n```\n$ aws-utils help whitelist-self\n\nSynopsis:\n\tUpdate security-groups with your external IP.\n\nDetails:\n\nAssume you have some security-groups which contain allow-lists of single IPs.\nThis command allows you to quickly and easily update those to keep your own\nentry current.\n\n...\n```\n\n\n## Common Features\n\nAll of the commands accept the use of AWS credentials in the way you'd expect, be it from `~/.aws/credentials` or via the use of environmental-variables:\n\n* For authentication\n   * `AWS_ACCESS_KEY_ID`\n   * `AWS_SECRET_ACCESS_KEY`\n   * `AWS_SESSION_TOKEN` (optionally)\n* `AWS_SHARED_CREDENTIALS_FILE`\n  * The path to a credentials file (`~/.aws/credentials` by default).\n  * Only used by the [rotate-keys](#rotate-keys) sub-command.\n* `AWS_REGION`\n  * The region to use.\n\nThese values are documented in the Golang SDK page:\n\n* https://docs.aws.amazon.com/sdk-for-go/api/aws/session/\n\nMany of the utilities also allow you to operate upon an arbitrary number of AWS roles.  In that case you'd specify the path to a file containing roles to assume, via the `-roles` argument.\n\nFor example:\n\n```\n$ aws-utils csv-instances -roles=/path/to/roles\n```\n\nThe format of the file is one-role per line, such as:\n\n```\narn:aws:iam::123457000001:role/foo-AdministratorAccessFromInt-1ABCDEFGHIJKL\narn:aws:iam::123457000002:role/foo-AdministratorAccessFromInt-2ABCDEFGHIJKL\narn:aws:iam::123457000003:role/tst-AdministratorAccessFromInt-3ABCDEFGHIJKL\narn:aws:iam::123457000004:role/tst-AdministratorAccessFromInt-4ABCDEFGHIJKL\n\n# Lines prefixed with \"#\" are comments, and are ignored (as are empty-lines).\n```\n\n\n\n## SubCommands\n\nThe following sub-commands are available:\n\n* [csv-instances](#csv-instances)\n* [instances](#instances)\n* [ip](#ip)\n* [orphaned-zones](#orphaned-zones)\n* [rotate-keys](#rotate-keys)\n* [sg-grep](#sg-grep)\n* [stacks](#stacks)\n* [subnets](#subnets)\n* [whitelist-self](#whitelist-self)\n* [whoami](#whoami)\n\n\n\n\n\n### `csv-instances`\n\nOutput a list of running instances, as CSV.  The output may be changed, but by default we show:\n\n* Account ID\n* Instance ID\n* Instance Name\n* AMI ID\n\nUsage:\n\n```sh\n$ aws-utils csv-instances [-roles=/path/to/roles]\n```\n\nThe fields displayed may be changed via the `format` argument, for example:\n\n```sh\n$ aws-utils csv-instances --format=\"name,id,subnet,subnetid,vpc,vpcid\"\n```\n\nThe list of available field-names can be viewed via `aws-utils help csv-instances`.\n\n\n### `instances`\n\nShow a human-readable list of all the EC2 instances you have running, along\nwith details of the volumes associated with each instance.\n\nSample output:\n\n```\ni-01066633e12345567 - prod-fooapp-uk\n------------------------------------\n\tAMI          : ami-01234567890abcdef\n    AMI Age      : 4 days\n\tInstance type: t3.medium\n\tKey name     : sysadmin1\n\tPrivate IPv4 : 10.30.44.105\n\tVolumes:\n\t\t/dev/sda1\tvol-01234567890abcdef\t100Gb\tgp2\tEncrypted:true\tIOPs:300\n```\n\nUsage:\n\n```sh\n$ aws-utils instances [-json] [-roles=/path/to/roles]\n```\n\nThe output is defined by a simple golang template.  If you wish to change the template you can do so:\n\n```sh\n$ aws-utils instances -dump-template \u003e foo.tmpl\n$ vi foo.tmpl\n$ aws-utils instances -template=./foo.tmpl\n```\n\n\n\n### `ip`\n\nShow the private IPv4 address of the instance which matches the given\nregular expression.\n\n```sh\n$ aws-utils ip *live*manager\n10.13.14.32\n```\n\nThis sub-command is useful for tab-completion against instance names, for\nconnecting via SSH/RDP/similar.\n\n\n\n### `orphaned-zones`\n\nThis sub-command examines all domains which have DNS hosted in Route53,\nand reports those which have nameservers configured which do __not__\nbelong to AWS.\n\nThis is designed to identify domains which have expired, or had their\nDNS-hosting moved to an external system (such as cloudflare, or similar).\n\nUsage:\n\n```sh\n$ aws-utils orphaned-zones\nVALID  - dhcp.io.\nORPHAN - example.com.\n```\n\n\n\n### `rotate-keys`\n\nThis sub-command uses the AWS API to regenerate a new set of AWS access-keys,\nand updates your `~/.aws/credentials` file with the new values.\n\n**NOTE**:\n\n* You may only have two sets of AWS Access Keys at a time\n  * So if you have two already one must be removed.\n  * You will be prompted prior to the removal of one, or you can add `-force` to avoid that interactive prompt.\n* `~/.aws/credentials` is the default file to use as the template for updating\n  * If that file is missing your keys will be removed/created but they will then be lost.\n  * This is because the output is achieved by reading the existing file and replacing existing keys, rather than blindly overwriting.\n  * We want to do this to avoid data-loss on things like your profile(s) and other configuration values.\n* **Take a backup** before running this tool for the first time.\n\n\n\n### `sg-grep`\n\nShow security-groups which match a particular regular expression.\n\n```\n$ aws-utils sg-grep 0.0.0.0/0\nsg-01234567890abcdef [eu-central-1] - launch-wizard-1 created 2021-11-19T09:39:15.473+02:00\n\t{\n\t  Description: \"launch-wizard-1 created 2021-11-19T09:39:15.473+02:00\",\n\t  GroupId: \"sg-sg-01234567890abcdef\",\n\t  GroupName: \"launch-wizard-1\",\n\t  IpPermissions: [{\n\t      FromPort: 22,\n\t      IpProtocol: \"tcp\",\n\t      IpRanges: [{\n\t          CidrIp: \"0.0.0.0/0\",\n\t          Description: \"\"\n\t        }],\n\t      ToPort: 22\n\t    }],\n\n```\n\nUsage:\n\n```sh\n$ aws-utils sg-grep [-roles=/path/to/roles] search-term1 search-term2 ..\n```\n\n\n\n### `stacks`\n\nShow the names, and optionally the statuses of all cloudformation stacks.\n\nThis is useful for applying stack-policies to a list of stacks, for example, and avoids the use of more complex CLI invocations when using the AWS CLI.\n\nYou can also update all stacks with a protection policy in a single operation.\n\nUsage:\n\n```sh\n$ aws-utils stacks\nStackSet-09c62176-4401-4c2e-b018-b3983c37619d\nmy-prod--iam\nmy-prod--lifecycel-manager\nmy-prod--route53\n..\n\n$ aws-utils stacks -policy ./my-stack-policy.json\n```\n\nOptionally you may display the stack-status, and include deleted-stacks.\n\n\n\n\n### `subnets`\n\nShow the subnets, along with associated CIDR ranges, available within all VPCs.\n\nThis is useful when you're running a penetration test, or want a quick overview of all the available subnets across a bunch of accounts.\n\nUsage:\n\n```sh\n$ aws-utils subnets\nAccount, VPC, Subnet Name, Subnet ID, Cidr\n207250808959,vpc-bbe705d2,default-eu-central-1a,subnet-b4df30dd,172.31.16.0/20\n207250808959,vpc-bbe705d2,default-eu-central-1b,subnet-406c6238,172.31.0.0/20\n207250808959,vpc-bbe705d2,default-eu-central-1a,subnet-44fad80e,172.31.32.0/20\n```\n\n\n\n\n### `whitelist-self`\n\nThis sub-command allows you to quickly update Ingress rules, with your current external IP address.\n\nImagine you have a number of security-groups which permit access to resources via a small list of permitted source IPs this command will let you update your own entry in that list easily.\n\nSample input file:\n\n```\n$ cat input.json\n[\n  { \"SG\": \"sg-12344\", \"Name\": \"[aws-utils] Steve's Home IP\", \"Port\": 443 },\n  { \"SG\": \"sg-12345\", \"Name\": \"[aws-utils] Steve's Home IP\", \"Port\": 22 }\n]\n```\n\nValid values for the JSON object are:\n\n* `Display`\n  * A message to display when the group is updated, good for documentation.\n* `SG`\n  * The ID of the security-group to update.\n* `Name`\n  * The name of the rule to add (i.e. description)\n  * This **must** be unique within the security-group.\n* `Port`\n  * The port to permit.\n* `Role`\n  * Optionally you may specify an ARN of a role to assume.\n  * example : `arn:aws:iam::123456789010:role/devops-access`\n\n\nAs you can see each rule allows you to whitelist a single port, and only a single port.  Of course if you wish you can repeat rules with different ports like so:\n\n```json\n[\n    {\n        \"SG\": \"sg-12345\",\n        \"Name\": \"[aws-utils] ${USER} home: HTTPS\",\n        \"Port\": 443\n    },\n    {\n        \"SG\": \"sg-12345\",\n        \"Name\": \"[aws-utils] ${USER} home: SSH\",\n        \"Port\": 22\n    }\n]\n```\n\nOnce you run the tool, with a suitable JSON input file, you'll get output like so:\n\n```\n$ ./aws-utils whitelist-self ./prod.json\nYour remote IP is 191.145.83.183/32\n  SecurityGroupID: sg-12345\n  IP:              191.145.83.183/32\n  Port:            443\n  Description:     [aws-utils] steve home: HTTPS\n  Found existing entry, and deleted it.\n  Added entry with current details.\n```\n\nUsage:\n\n```sh\n$ aws-utils whitelist-self /path/to/rules.json\n```\n\n\n### `whoami`\n\nShow the current user, or assumed role.\n\n```\n$ aws-utils whoami\naws-company-devops-prd\n```\n\nOr having assumed a role:\n\n```\n$ aws-utils whoami\naws-company-role-prod-ro\n```\n\n\n\n## Github Setup\n\nThis repository is configured to run tests upon every commit, and when\npull-requests are created/updated.  The testing is carried out via\n[.github/run-tests.sh](.github/run-tests.sh) which is used by the\n[github-action-tester](https://github.com/skx/github-action-tester) action.\n\nReleases are automated in a similar fashion via [.github/build](.github/build),\nand the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Faws-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskx%2Faws-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Faws-utils/lists"}