environment

README

aws-env

A small library and binary for securely handling secrets in environment variables on AWS. Supports KMS, SSM Parameter store and secrets manager. Inspired by ssm-env.

Usage

Both the library and binary versions of aws-env will loop through the environment and exchange any variables prefixed with sm://, ssm:// and kms:// with their secret value from Secrets manager, SSM Parameter store or KMS respectively. In order for this to work, the instance profile (EC2), task role (ECS), or execution role (Lambda) must have the correct privileges in order to retrive the secret values and/or decrypt the secret using KMS.

For instance:

• export SECRETSMANAGER=sm://<path>
• export PARAMETERSTORE=ssm://<path>
• export KMSENCRYPTED=kms://<encrypted-secret>
• export MULTIVALUE=sm://<path>#<key> (if the secret itself contains JSON).

Where <path> is the name of the secret in secrets manager or parameter store. aws-env will look up secrets in the region specified in the AWS_REGION or AWS_DEFAULT_REGION environment variables, and if they are both unset/empty it will contact the EC2 Metadata endpoint (if possible) and use the region where it is deployed.

Required IAM privileges:

• Secrets manager: secretsmanager:GetSecretValue on the resource. And kms:Decrypt if not using the aws/secretsmanager key alias.
• SSM Parameter store: ssm:GetParameter on the resource. kms:Decrypt on the KMS key used to encrypt the secret.
• KMS: kms:Decrypt on the key used to encrypt the secret.

Binary

Install using homebrew:

brew install telia-oss/tap/aws-env

Or grab binary from the releases, and start your process with:

aws-env exec -- <command>

This will populate all the secrets in the environment, and hand over the process to your <command> with the same PID. The populated secrets are only made available to the <command> and 'disappear' when the process exits.

Library

Import the library and invoke it prior to parsing flags or reading environment variables:

package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go/aws/session"
	environment "github.com/telia-oss/aws-env"
)

func main() {
	// New AWS Session
	sess, err := session.NewSession()
	if err != nil {
		panic(fmt.Errorf("failed to create new aws session: %s", err))
	}

	// Populate secrets using aws-env
	env, err := environment.New(sess)
	if err != nil {
		panic(fmt.Errorf("failed to initialize aws-env: %s", err))
	}
	if err := env.Populate(); err != nil {
		panic(fmt.Errorf("failed to populate environment: %s", err))
	}
}

Security

There are a couple of things to keep in mind when using aws-env:

• Spawned processes will inherit their parents environment by default. If your <command> spawns new processes they will inherit the environment with the secrets already populated, unless you hand-roll the environment for the new process.
• The environment for a running process can be read by the root user (and yourself) after secrets have been populated by running cat /proc/<pid>/environ on Linux, and ps eww <pid> on OSX. However, if root or the spawning user is compromised a malicious user can just as easily fetch the secrets directly from the AWS API ¯\(ツ)/¯

Documentation

Index

• type KMSClient
• type Manager
  • func New(sess *session.Session) (*Manager, error)
  • func NewTestManager(sm SMClient, ssm SSMClient, kms KMSClient) *Manager
  • func (m *Manager) Populate() error
• type SMClient
• type SSMClient

Types

type KMSClient

type KMSClient interface {
	Decrypt(*kms.DecryptInput) (*kms.DecryptOutput, error)
}

KMSClient for testing purposes.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles API calls to AWS.

func New

func New(sess *session.Session) (*Manager, error)

New creates a new manager for populating secret values.

func NewTestManager

func NewTestManager(sm SMClient, ssm SSMClient, kms KMSClient) *Manager

NewTestManager for testing purposes.

func (*Manager) Populate

func (m *Manager) Populate() error

Populate environment variables with their secret values from either Secrets manager, SSM Parameter store or KMS.

type SMClient

type SMClient interface {
	GetSecretValue(*secretsmanager.GetSecretValueInput) (*secretsmanager.GetSecretValueOutput, error)
}

SMClient (secrets manager client) for testing purposes.

type SSMClient

type SSMClient interface {
	GetParameter(*ssm.GetParameterInput) (*ssm.GetParameterOutput, error)
}

SSMClient for testing purposes.