🚀

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+## How to Open a Ticket
+
+* Before you open a ticket or send a pull request, search for previous discussions about the same feature or issue. Add to the earlier ticket if you find one.
+
+* Before sending a pull request for a feature or bug fix, be sure to have the existing tests passing, and additional tests for your feature or fix.
+
+* Use the same coding style as the rest of the codebase.
+
+* All pull requests should be made to the `master` branch.

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2016 Coinbase, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,162 @@
+# assume-role
+
+<img src="./assets/assume-role.png" align="right" alt="assume-role logo" />
+
+`assume-role` is a command line tool that makes it easy to assume IAM roles through an **AWS Bastion** account with **MFA**.
+
+**AWS Bastion** accounts store only IAM users providing a central, isolated account to manage their credentials and access. Trusting AWS accounts create IAM roles that the Bastion users can assume, to allow a single user access to multiple accounts resources. Under this setup, `assume-role` makes it easier to follow the standard security practices of MFA and short lived credentials.
+
+## Installation
+
+### via Homebrew (macOS)
+
+```bash
+brew tap coinbase/assume-role
+brew install assume-role
+```
+
+You can then upgrade at any time by running:
+
+```bash
+brew upgrade assume-role
+```
+
+### via Bash (Linux/macOS)
+
+You can install/upgrade assume-role with this command:
+
+```bash
+curl https://raw.githubusercontent.com/coinbase/assume-role/master/install-assume-role | bash
+```
+
+It will ask for your sudo password only if necessary.
+
+## Getting Started
+
+Make sure that credentials for your AWS bastion account are stored in `~/.aws/credentials`.
+
+Out of the box you can call `assume-role` like:
+
+```bash
+eval $(assume-role account-id role mfa-token)
+```
+
+If your shell supports bash functions (e.g. zsh) then you can add `source $(which assume-role)` to your `rc` file (e.g. `~/.zshrc`), then you can call `assume-role` like:
+
+```bash
+assume-role [account-id] [role] [mfa-token]
+```
+
+`assume-role` this method can be used with arguments or interactively like:
+
+<img src="./assets/assume-role.gif" alt="assume-role usage" />
+
+### Account Aliasing
+
+You can define aliases to account ids in `~/.aws/accounts` which assume-role can use, e.g.
+
+```json
+{
+  "default": 123456789012,
+  "staging": 123456789012,
+  "production": 123456789012
+}
+```
+
+With this file, to assume the `read` role in the `production` account:
+
+```bash
+assume-role production read
+# OR
+assume-role 123456789012 read
+```
+
+## AWS Bastion Account Setup
+
+Here is a simple example of how to set up a **Bastion** AWS account with an id `0987654321098` and a **Production** account with the id `123456789012`.
+
+In the **Production** account create a role called `read`, with the trust relationship:
+
+```json
+{
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::0987654321098:root"
+      },
+      "Action": "sts:AssumeRole",
+      "Condition": {
+        "Bool": {
+          "aws:SecureTransport": "true",
+          "aws:MultiFactorAuthPresent": "true"
+        },
+        "NumericLessThan": {
+          "aws:MultiFactorAuthAge": "54000"
+        }
+      }
+    }
+  ]
+}
+```
+
+The conditions `aws:MultiFactorAuthPresent` and `aws:MultiFactorAuthAge` forces the use of temporary credentials secured with MFA.
+
+In the **Bastion** account, create a group called `assume-read` with the policy:
+
+```json
+{
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [ "sts:AssumeRole" ],
+      "Resource": [ "arn:aws:iam::123456789012:role/read" ],
+      "Condition": {
+        "Bool": {
+          "aws:MultiFactorAuthPresent": "true",
+          "aws:SecureTransport": "true"
+        },
+        "NumericLessThan": {
+          "aws:MultiFactorAuthAge": "54000"
+        }
+      }
+    }
+  ]
+}
+```
+
+Attach this group to **Bastion** users that should be able use `read`'s policies in the **Production** account.
+
+You can assume the `read` role in **Production** by running:
+
+```
+assume-role 123456789012 read
+```
+
+Then entering a MFA token on request.
+
+## Prompt
+
+If you are using `zsh` you can get a sweet prompt by adding to your `.zshrc` file:
+
+```bash
+# AWS ACCOUNT NAME
+function aws_account_info {
+  [ "$AWS_ACCOUNT_NAME" ] && [ "$AWS_ACCOUNT_ROLE" ] && echo "%F{blue}aws:(%f%F{red}$AWS_ACCOUNT_NAME:$AWS_ACCOUNT_ROLE%f%F{blue})%F$reset_color"
+}
+
+# )ofni_tnuocca_swa($ is $(aws_account_info) backwards
+PROMPT=`echo $PROMPT | rev | sed 's/ / )ofni_tnuocca_swa($ /'| rev`
+```
+
+## Testing
+
+assume-role is tested with [BATS](https://github.com/sstephenson/bats) (Bash Automated Testing System). To run the tests first you will need `bats`, `jq` and `shellcheck` installed. On macOS this can be accomplished with `brew`:
+
+```bash
+brew install bats
+brew install jq
+brew install shellcheck
+```
+
+Then run `bats test/assume-role.bats`;