Skip to content

Commit 8e85121

Browse files
gsavagegsavage
committed
Improve the readme
Remove a lot of text that isn't relevant and point our staff at the internal KnowledgeBase
1 parent 9f073aa commit 8e85121

File tree

1 file changed

+3
-187
lines changed

1 file changed

+3
-187
lines changed

‎README.md‎

Lines changed: 3 additions & 187 deletions
Original file line numberDiff line numberDiff line change
@@ -1,190 +1,6 @@
1-
Since the original repository seems to be no longer maintained (no updates for over a year) and this tool is a critical security component that should be updated regularly to address known CVEs, we decided to fork it under the kosli-dev organization and update dependencies ourselves.
1+
## Kosli's Fork
22

3-
For macOS, the aws-vault binary should be notarized. Since we haven't implemented this yet, you will need to build the binary yourself on your local machine and then move it to replace the one you installed:
4-
```
5-
$ aws-vault --version
6-
v7.2.0
7-
$ location=$(which aws-vault) # /opt/homebrew/bin/aws-vault
8-
$ cd somewhere && git clone https://github.com/kosli-dev/aws-vault.git
9-
$ cd aws-vault
10-
$ go build .
11-
$ mv aws-vault $location
12-
$ aws-vault --version
13-
dev
14-
```
3+
Kosli forked the original AWS Vault project, before it was adopted by [ByteNess](https://github.com/ByteNess/aws-vault)
154

16-
# Original README:
5+
Instructions and background information, for Kosli employees, can be found within the Knowledge Base
176

18-
# AWS Vault
19-
20-
[![Downloads](https://img.shields.io/github/downloads/99designs/aws-vault/total.svg)](https://github.com/99designs/aws-vault/releases)
21-
[![Continuous Integration](https://github.com/99designs/aws-vault/workflows/Continuous%20Integration/badge.svg)](https://github.com/99designs/aws-vault/actions)
22-
23-
AWS Vault is a tool to securely store and access AWS credentials in a development environment.
24-
25-
AWS Vault stores IAM credentials in your operating system's secure keystore and then generates temporary credentials from those to expose to your shell and applications. It's designed to be complementary to the AWS CLI tools, and is aware of your [profiles and configuration in `~/.aws/config`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files).
26-
27-
Check out the [announcement blog post](https://99designs.com.au/tech-blog/blog/2015/10/26/aws-vault/) for more details.
28-
29-
## Installing
30-
31-
You can install AWS Vault:
32-
- by downloading the [latest release](https://github.com/99designs/aws-vault/releases/latest)
33-
- on macOS with [Homebrew Cask](https://formulae.brew.sh/cask/aws-vault): `brew install --cask aws-vault`
34-
- on macOS with [MacPorts](https://ports.macports.org/port/aws-vault/summary): `port install aws-vault`
35-
- on Windows with [Chocolatey](https://chocolatey.org/packages/aws-vault): `choco install aws-vault`
36-
- on Windows with [Scoop](https://scoop.sh/): `scoop install aws-vault`
37-
- on Linux with [Homebrew on Linux](https://formulae.brew.sh/formula/aws-vault): `brew install aws-vault`
38-
- on [Arch Linux](https://www.archlinux.org/packages/community/x86_64/aws-vault/): `pacman -S aws-vault`
39-
- on [Gentoo Linux](https://github.com/gentoo/guru/tree/master/app-admin/aws-vault): `emerge --ask app-admin/aws-vault` ([enable Guru first](https://wiki.gentoo.org/wiki/Project:GURU/Information_for_End_Users))
40-
- on [FreeBSD](https://www.freshports.org/security/aws-vault/): `pkg install aws-vault`
41-
- on [OpenSUSE](https://software.opensuse.org/package/aws-vault): enable devel:languages:go repo then `zypper install aws-vault`
42-
- with [Nix](https://search.nixos.org/packages?show=aws-vault&query=aws-vault): `nix-env -i aws-vault`
43-
- with [asdf-vm](https://github.com/karancode/asdf-aws-vault): `asdf plugin-add aws-vault https://github.com/karancode/asdf-aws-vault.git && asdf install aws-vault <version>`
44-
45-
## Documentation
46-
47-
Config, usage, tips and tricks are available in the [USAGE.md](./USAGE.md) file.
48-
49-
## Vaulting Backends
50-
51-
The supported vaulting backends are:
52-
53-
* [macOS Keychain](https://support.apple.com/en-au/guide/keychain-access/welcome/mac)
54-
* [Windows Credential Manager](https://support.microsoft.com/en-au/help/4026814/windows-accessing-credential-manager)
55-
* Secret Service ([Gnome Keyring](https://wiki.gnome.org/Projects/GnomeKeyring), [KWallet](https://kde.org/applications/system/org.kde.kwalletmanager5))
56-
* [KWallet](https://kde.org/applications/system/org.kde.kwalletmanager5)
57-
* [Pass](https://www.passwordstore.org/)
58-
* Encrypted file
59-
60-
Use the `--backend` flag or `AWS_VAULT_BACKEND` environment variable to specify.
61-
62-
## Quick start
63-
64-
```shell
65-
# Store AWS credentials for the "jonsmith" profile
66-
$ aws-vault add jonsmith
67-
Enter Access Key Id: ABDCDEFDASDASF
68-
Enter Secret Key: %%%
69-
70-
# Execute a command (using temporary credentials)
71-
$ aws-vault exec jonsmith -- aws s3 ls
72-
bucket_1
73-
bucket_2
74-
75-
# open a browser window and login to the AWS Console
76-
$ aws-vault login jonsmith
77-
78-
# List credentials
79-
$ aws-vault list
80-
Profile Credentials Sessions
81-
======= =========== ========
82-
jonsmith jonsmith -
83-
84-
# Start a subshell with temporary credentials
85-
$ aws-vault exec jonsmith
86-
Starting subshell /bin/zsh, use `exit` to exit the subshell
87-
$ aws s3 ls
88-
bucket_1
89-
bucket_2
90-
```
91-
92-
## How it works
93-
94-
`aws-vault` uses Amazon's STS service to generate [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) via the `GetSessionToken` or `AssumeRole` API calls. These expire in a short period of time, so the risk of leaking credentials is reduced.
95-
96-
AWS Vault then exposes the temporary credentials to the sub-process in one of two ways
97-
98-
1. **Environment variables** are written to the sub-process. Notice in the below example how the AWS credentials get written out
99-
```shell
100-
$ aws-vault exec jonsmith -- env | grep AWS
101-
AWS_VAULT=jonsmith
102-
AWS_DEFAULT_REGION=us-east-1
103-
AWS_REGION=us-east-1
104-
AWS_ACCESS_KEY_ID=%%%
105-
AWS_SECRET_ACCESS_KEY=%%%
106-
AWS_SESSION_TOKEN=%%%
107-
AWS_CREDENTIAL_EXPIRATION=2020-04-16T11:16:27Z
108-
```
109-
2. **Local metadata server** is started. This approach has the advantage that anything that uses Amazon's SDKs will automatically refresh credentials as needed, so session times can be as short as possible.
110-
```shell
111-
$ aws-vault exec --server jonsmith -- env | grep AWS
112-
AWS_VAULT=jonsmith
113-
AWS_DEFAULT_REGION=us-east-1
114-
AWS_REGION=us-east-1
115-
AWS_CONTAINER_CREDENTIALS_FULL_URI=%%%
116-
AWS_CONTAINER_AUTHORIZATION_TOKEN=%%%
117-
```
118-
119-
The default is to use environment variables, but you can opt-in to the local instance metadata server with the `--server` flag on the `exec` command.
120-
121-
## Roles and MFA
122-
123-
[Best-practice](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#delegate-using-roles) is to [create Roles to delegate permissions](https://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html). For security, you should also require that users provide a one-time key generated from a multi-factor authentication (MFA) device.
124-
125-
First you'll need to create the users and roles in IAM, as well as [setup an MFA device](https://docs.aws.amazon.com/IAM/latest/UserGuide/GenerateMFAConfigAccount.html). You can then [set up IAM roles to enforce MFA](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-mfa).
126-
127-
Here's an example configuration using roles and MFA:
128-
129-
```ini
130-
[default]
131-
region = us-east-1
132-
133-
[profile jonsmith]
134-
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith
135-
136-
[profile foo-readonly]
137-
source_profile = jonsmith
138-
role_arn = arn:aws:iam::22222222222:role/ReadOnly
139-
140-
[profile foo-admin]
141-
source_profile = jonsmith
142-
role_arn = arn:aws:iam::22222222222:role/Administrator
143-
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith
144-
145-
[profile bar-role1]
146-
source_profile = jonsmith
147-
role_arn = arn:aws:iam::333333333333:role/Role1
148-
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith
149-
150-
[profile bar-role2]
151-
source_profile = bar-role1
152-
role_arn = arn:aws:iam::333333333333:role/Role2
153-
mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith
154-
```
155-
156-
Here's what you can expect from aws-vault
157-
158-
| Command | Credentials | Cached | MFA |
159-
|------------------------------------------|-----------------------------|---------------|-----|
160-
| `aws-vault exec jonsmith --no-session` | Long-term credentials | No | No |
161-
| `aws-vault exec jonsmith` | session-token | session-token | Yes |
162-
| `aws-vault exec foo-readonly` | role | No | No |
163-
| `aws-vault exec foo-admin` | session-token + role | session-token | Yes |
164-
| `aws-vault exec foo-admin --duration=2h` | role | role | Yes |
165-
| `aws-vault exec bar-role2` | session-token + role + role | session-token | Yes |
166-
| `aws-vault exec bar-role2 --no-session` | role + role | role | Yes |
167-
168-
## Development
169-
170-
The [macOS release builds](https://github.com/99designs/aws-vault/releases) are code-signed to avoid extra prompts in Keychain. You can verify this with:
171-
```shell
172-
$ codesign --verify --verbose $(which aws-vault)
173-
```
174-
175-
If you are developing or compiling the aws-vault binary yourself, you can [generate a self-signed certificate](https://support.apple.com/en-au/guide/keychain-access/kyca8916/mac) by accessing Keychain Access > Certificate Assistant > Create Certificate -> Certificate Type: Code Signing. You can then sign your binary with:
176-
```shell
177-
$ go build .
178-
$ codesign --sign <Name of certificate created above> ./aws-vault
179-
```
180-
181-
## References and Inspiration
182-
183-
* https://github.com/pda/aws-keychain
184-
* https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html
185-
* https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html#create-iam-users
186-
* https://github.com/makethunder/awsudo
187-
* https://github.com/AdRoll/hologram
188-
* https://github.com/realestate-com-au/credulous
189-
* https://github.com/dump247/aws-mock-metadata
190-
* https://boto.readthedocs.org/en/latest/boto_config_tut.html

0 commit comments

Comments
 (0)