Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@naftulikay
naftulikay committed Jan 18, 2023
1 parent f342191 commit 20b8afc
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 72 deletions.
13 changes: 13 additions & 0 deletions LICENSE-APACHE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
Copyright © 2023 Naftuli Kay

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.
14 changes: 14 additions & 0 deletions LICENSE-MIT
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Copyright © 2023 Naftuli Kay

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the “Software”), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
179 changes: 107 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,121 +1,156 @@
# aws-env [![Build Status][svg-travis]][travis]
# aws-env [![Build Status][build.svg]][build]

A simple shell utility for exporting a given AWS credentials profile to environment variables. Useful for crossing
A utility for exporting a given AWS credentials profile to environment variables. Useful for crossing
machine boundaries with SSH and Vagrant.

## Usage
## Background

Shamelessly ripped from `aws-env -h`:
The `aws` CLI and other tools such as Terraform can use an INI-format file located at `~/.aws/credentials` to
store different "profiles" and credentials/configuration for each. While this works fairly well, storing all
credentials in a single, unencrypted file is far from ideal.

```
usage: aws-env [-h] [-n] [-l] [profile]
This utility allows users to store profiles in multiple files, optionally using GnuPG for file encryption so that
secrets are never stored in plaintext when stored. `aws-env` will use an ordered loading system to load from:

Extract AWS credentials for a given profile as environment variables.
1. the traditional `~/.aws/credentials` file in plaintext.
2. a GnuPG (`gpp`) encrypted file at `~/.aws/credentials.asc` or `~/.aws/credentials.gpg`.
3. both encrypted and plaintext profiles within the `~/.aws/credentials.d` directory, either with a suffix of
`*.gpg`/`*.asc`/`*.ini`, or without a file suffix.

positional arguments:
profile The profile in ~/.aws/credentials or ~/.aws/credentials.d/
to extract credentials for. Defaults to 'default'.
When using multiple files, `aws-env` creates prefixed names for profiles in case of multiple files containing the
same profile id. See the output of `aws-env list` for more information.

optional arguments:
-h, --help show this help message and exit
-n, --no-export Do not use export on the variables.
-l, --ls List available profiles.
```
Other features, such as the ability to use SSO profiles, are not supported yet, but this work is being tracked
in #19.

`aws-env` looks first at `~/.aws/credentials` and then at all files in `~/.aws/credentials.d/` if found and merges all
of them together in a dictionary of profiles. `~/.aws/credentials` is loaded first and everything loaded from
`~/.aws/credentials.d/` are loaded in alphabetically sorted order and merged in. (See
[Encrypted Credential Files](#Encrypted Credential Files) for instructions on using encrypted credential files.)
## Usage

If you have a profile named `brangus`, you can extract environment variables like so:
Shamelessly ripped from `aws-env -h`:

```shell
$ aws-env brangus
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
```
aws-env 2.0.0
As a shortcut, you can directly source the output of this command to export the variables into your shell session:
USAGE:
aws-env [OPTIONS] <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--log-level <log-level> Set the logging level for the utility [default: error] [possible values: trace,
debug, info, warn, error]
SUBCOMMANDS:
export Export the specified profile
help Prints this message or the help of the given subcommand(s)
list List available profiles
```shell
$ $(aws-env brangus)
```

This will cause your shell to execute the output of `aws-env`, exporting these environment variables.
### Listing Available Profiles

> **WARNING:** This is _potentially very dangerous_ if you don't trust the script you're executing, so use with care and
> establish trust. All commits and releases here are [PGP signed][keybase] with my key, so if you know me and trust me,
> you should be able to use this, but as always, _read the source code_ and check it before you blindly pipe code into
> your shell session.
To list available profiles, use `aws-env list` command:

### Encrypted Credential Files
```text
aws-env-list 2.0.0
List available profiles
`aws-env` now supports encrypted credential files! Stash files ending in `.asc`, `.gpg`, or `.pgp` in
`~/.aws/credentials.d/` and `aws-env` will attempt to decrypt these files using GnuPG. `gpg2` is preferred but `gpg`
will be used as a backup option.
USAGE:
aws-env list [FLAGS] [OPTIONS]
`aws-env` will decrypt files directly into memory. File format should be the same as `~/.aws/credentials`. Here's a
sample `tree` output detailing the directory layout:
FLAGS:
-h, --help Prints help information
--no-header Exclude the header when printing to a TTY
-V, --version Prints version information
OPTIONS:
-F, --format <format> The output format [default: table] [possible values: table, plain, csv, json]
```
/home/naftuli/.aws
├── config
├── credentials
└── credentials.d
└── naftulikay.asc

1 directory, 3 files
Listing profiles will never expose sensitive data, only the presence of profiles within the configuration files.
By default, the `table` format is used to display the profiles:

```text
profile prefix/profile priority file
――――――――― ―――――――――――――― ―――――――― ――――――――――――――――――――――――――――
hello a/hello 00 ~/.aws/credentials.d/a.ini
goodbye a/goodbye 01 ~/.aws/credentials.d/a.ini
encrypted enc/encrypted 02 ~/.aws/credentials.d/enc.asc
default /default 03 ~/.aws/credentials
```

## Installation
The `profile` field is the name of the profile within a file, e.g. `[default]` will yield a name of `default`.
The `prefix/profile` field is a generated, qualified path to a profile, which is useful when multiple profiles
with the same name exist across multiple files. Both the profile name and the `prefix/profile` format are used
during lookup in `aws-env export`. The `priority` field is a generated field showing the load order of profiles,
the larger the value of `priority`, the higher precedence it has when collisions occur.

There already exists an `awsenv` package on PyPI, so this is not published to PyPI. I have a personal frustration with
PyPI in a number of respects, so this module is best installed via pip directly.
Finally, the `file` field simply points to the file from which the given profile was found.

Please visit the [releases page][releases] for a listing of releases and tag names, and use those to install a given
version of the software. Release `1.0.0` is going to have a tag named `v1.0.0`, etc.
### Exporting a Profile

##### User Install
For information on how profiles are loaded, see the previous section.

To install `aws-env` as an ordinary user:
`aws-env export` will dump the specified profile in shell commands to standard output.

```shell
pip install --user git+https://github.com/naftulikay/aws-env@v1.0.0
```
```text
aws-env-export 2.0.0
Export the specified profile
USAGE:
aws-env export <profile_name>
##### System Install
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
To install `aws-env` system-wide:
ARGS:
<profile_name> The profile name to export. This can be either the bare profile name or a URI. See the 'list'
command for URI format
```

For example, to export the `default` profile mentioned above, run `aws-env export default`, and you will see output
like:

```shell
sudo pip install git+https://github.com/naftulikay/aws-env@v1.0.0
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
```

## Building
Additionally, qualified names can be used to resolve collisions. `aws-env export default` and `aws-env export /default`
refer to the same profile as described above.

#### Directly Exporting to Shell

This project uses [`buildout`][buildout] to manage the project. Simply put, to get started you can use a `virtualenv`
if you'd like, then install the requirements:
Simply dumping the profile credentials to standard out does not mean that these are exported to your shell session.
In most shells, to directly export the credentials to the shell session, you can have your shell execute the output
from `aws-env`:

```shell
$ pip install --user -r requirments.txt
$(aws-env export default)
```

Next, build the project:
When you run this in an interactive shell session, you won't see any output from the command, but you should be able
to now see that the environment variables have been set correctly:

```shell
$ buildout
$ env | grep AWS_
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
```

You should now have all dependencies and some scripts in `bin/` such as `bin/test`, `bin/python`, `bin/ipython`, and
`bin/aws-env`. Buildout is rad.
## Installation

To install, clone the Git repository locally, and run `cargo install --path .` to install `aws-env` to your `PATH`
under `~/.cargo/bin`. You'll need a functional Rust compilation environment to install from source like this.

## License

Read the file called `LICENSE`, but it's basically MIT. If you want or need a dual-license for some reason that I have
yet to understand, please ask and I can dual-license it as appropriate.
Licensed at your discretion under either:

- [Apache Software License, Version 2.0](./LICENSE-APACHE)
- [MIT License](./LICENSE-MIT)

[travis]: https://travis-ci.org/naftulikay/aws-env
[svg-travis]: https://travis-ci.org/naftulikay/aws-env.svg?branch=master
[releases]: https://github.com/naftulikay/aws-env/releases
[keybase]: https://keybase.io/naftulikay
[buildout]: https://github.com/buildout/buildout
[build]: https://github.com/naftulikay/aws-env/actions/workflows/rust.yml
[build.svg]: https://github.com/naftulikay/aws-env/actions/workflows/rust.yml/badge.svg

0 comments on commit 20b8afc

Please sign in to comment.