Skip to content

Latest commit

 

History

History
148 lines (90 loc) · 5.23 KB

README.md

File metadata and controls

148 lines (90 loc) · 5.23 KB
Raw

Hyperdrive Skuld

Introduction

The skuld command-line utility is meant to be used by developers interacting with the AWS SDK and wanting/needing to use temporary credentials generated with Two-Factor authentication. skuld uses the AWS Security Token Service together with a named profile and a code from an MFA device to generate another named profile with temporary credentials.

Together with appropriate IAM policies, skuld can enforce the use of an MFA device to manipulate the AWS SDK from a developer's machine.

Installation

There are many ways that you can install skuld. Below are 3 options given:

Option 1: Binaries

On macOS, you can use Nix to install skuld.

$ nix profile install github:DEEP-IMPACT-AG/skuld

On Windows, you can use scoop to install skuld.

$ scoop bucket add hyperdrive https://github.com/DEEP-IMPACT-AG/scoop-hyperdrive.git
$ scoop install skuld

Option 2: Easy, with Docker

For all platforms (Linux, macOS, Windows, Raspberry Pi, Nvidia Jetson, etc) that have docker installed, this is the zero installation method. Just run once to add the alias in your ${HOME}/.profile or ${HOME}/.bashrc file:

echo "alias skuld='docker run -it --rm -v ${HOME}/.aws:/root/.aws deepimpact/skuld:latest skuld'" >> ${HOME}/.profile

That's it! You can call skuld from the command line, like it was installed natively on your system.

Option 3: Manual installation

You can also install it manually by downloading from latest release page.

On Nix/NixOS you can add an overlay that calls default.nix to add the binary to your path. You can use the provided Flake to run it easily with:


nix run github:DEEP-IMPACT-AG/skuld

# or install with:

nix profile install github:DEEP-IMPACT-AG/skuld

You can try building it locally via:


nix-build -E '(import <nixpkgs> {}).callPackage ./default.nix {}'

Finally, you can install it from the sources via go get. You will need Go 1.10.

Preparation

Before using skuld, you must create an IAM user, assign an MFA device to it and create an Access Key for it. Refer to the IAM documentation of AWS.

Copy the Access Key to a named profiled in the credentials file. Choose the region according to your most frequent usage.

[<profile-name>]
aws_access_key_id     = ??????
aws_secret_access_key = ??????
region                = us-east-1

You can check the IAM user of the named profile by using the aws command-line utility.

 $ aws --profile=<profile-name> sts get-caller-identity

You can also check the existence of your MFA device.

$ aws --profile=<profile-name> iam list-mfa-devices --user-name <iam-user-name>

Usage

To request temporary credentials, use skuld at the shell as follows:

$ skuld <profile-name>
Enter your token:

When prompted by Enter your token: , enter the token of your MFA device and press the enter key.

skuld will fetch temporary credentials and create a new profile named <profile-name>-skuld with them (i.e. the new profile's name is the original profile name with the suffix -skuld). If the skuld profile already exists, it will be overwritten with the new temporary credentials.

skuld also ouputs the expiring time of the temporary credentials in UTC:

Credentials valid until: 2018-01-02 20:00:01 +0000 UTC

The temporary credentials are valid for 10 hours but if the profile name ends with -adm; in that case, the temporary credentials are valid for 1 hour.

The new profile, respectively updated profile, can now be used normally. For instance, to describe ec2 instances:

$ aws --profile=<profile-name>-skuld ec2 describe-instances

Or used in the credentials file to be used as reference in other named profiles:

[other-profile-name]
source_profile = <profile-name>-skuld
role_arn       = arn:aws:iam::xxxxxx:role/admin
region         = us-east-1

The region of the skuld profile is given by the profile from which it is derived. For instance, if the base profile is in the us-east-2 region, the skuld profile will be also configured to be in the us-east-2. Beside the configuration in the credentials file, skuld will also generate an entry in the configuraion ~/.aws/config with the region.

The flag -r <region> can be used to override the region.

Enforcing MFA Devices

skuld by itself does not enforce the use of MFA devices; it just simplifies the creation of temporary credentials with MFA devices.

To actually enforce the use of MFA Devices, you need to assign a proper IAM policy to your IAM user.

AWS has a tutorial to that purpose: Enable Your Users to Configure Their Own Credentials and MFA Settings.

Appendix

For maintainers of the project

To cross compile and upload the latest version of skuld to Docker Hub, do:

  1. Log in to the docker hub with the deepimpact account, if you did not so already.
  2. Update the git tag version in the file buildx.sh
  3. Run buildx.sh