From 20b8afc04e604a79febeab4a0143040599e2346d Mon Sep 17 00:00:00 2001 From: Naftuli Kay Date: Wed, 18 Jan 2023 15:33:44 -0800 Subject: [PATCH] Update README --- LICENSE-APACHE | 13 ++++ LICENSE-MIT | 14 ++++ README.md | 179 +++++++++++++++++++++++++++++-------------------- 3 files changed, 134 insertions(+), 72 deletions(-) create mode 100644 LICENSE-APACHE create mode 100644 LICENSE-MIT diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..c71e08b --- /dev/null +++ b/LICENSE-APACHE @@ -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. \ No newline at end of file diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..e5e9157 --- /dev/null +++ b/LICENSE-MIT @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index 4b0ade4..7827688 100644 --- a/README.md +++ b/README.md @@ -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] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + --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 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 -##### System Install +FLAGS: + -h, --help Prints help information + -V, --version Prints version information -To install `aws-env` system-wide: +ARGS: + 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