CLI that provides on-demand secrets access for common DevOps tools
Clone or download
Latest commit e0ddaa9 Dec 7, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
acceptance Fixed up the acceptance tests Dec 6, 2018
bin Converted summon to fully use go modules (vgo) Dec 6, 2018
cmd Moved command package to internal/command Dec 6, 2018
docs Update gopass URL Oct 1, 2018
internal/command Moved command package to internal/command Dec 6, 2018
output/acceptance Fixed up the acceptance tests Dec 6, 2018
pkg/summon Converted summon to fully use go modules (vgo) Dec 6, 2018
provider Add a default provider path for Windows (#76) Aug 21, 2018
script Adds copyright info Jun 23, 2015
secretsyml fix: replace conjurinc with cyberark + move github pages from branch … Aug 23, 2017
.dockerignore Converted summon to fully use go modules (vgo) Dec 6, 2018
.gitignore Fixed up the acceptance tests Dec 6, 2018
.gitlab-ci.yml Fixed up the acceptance tests Dec 6, 2018
.goreleaser.yml Converted summon to fully use go modules (vgo) Dec 6, 2018
.kateconfig Add kate editor config May 22, 2015
CHANGELOG.md v0.6.9 (#86) Dec 7, 2018
Dockerfile Converted summon to fully use go modules (vgo) Dec 6, 2018
Dockerfile.acceptance Fixed up the acceptance tests Dec 6, 2018
Jenkinsfile Made tests be used even if the test step fails Dec 6, 2018
LICENSE Add MIT license Jun 22, 2015
README.md Converted summon to fully use go modules (vgo) Dec 6, 2018
build Converted summon to fully use go modules (vgo) Dec 6, 2018
go.mod Converted summon to fully use go modules (vgo) Dec 6, 2018
go.sum Converted summon to fully use go modules (vgo) Dec 6, 2018
install.sh Converted summon to fully use go modules (vgo) Dec 6, 2018
secrets_publish.yml publish to bintray May 30, 2015
test Converted summon to fully use go modules (vgo) Dec 6, 2018
test_acceptance Fixed up the acceptance tests Dec 6, 2018
test_unit Converted summon to fully use go modules (vgo) Dec 6, 2018

README.md

summon

GitHub release pipeline status

Github commits (since latest release)


summon is a command-line tool to make working with secrets easier.

It provides an interface for

  • Reading a secrets.yml file
  • Fetching secrets from a trusted store
  • Exporting secret values to a sub-process environment

Install

Note installing summon alone is not sufficient; you need to also install a provider of your choice before it's ready for use.

Pre-built binaries and packages are available from GitHub releases here.

Homebrew

brew tap cyberark/tools
brew install summon

Linux (Debian and Red Hat flavors)

deb and rpm files are attached to new releases. These can be installed with dpkg -i summon.deb and rpm -ivh summon.rpm, respectively.

Auto Install

Note Check the release notes and select an appropriate release to ensure support for your version of Conjur.

Use the auto-install script. This will install the latest version of summon. The script requires sudo to place summon in /usr/local/bin.

curl -sSL https://raw.githubusercontent.com/cyberark/summon/master/install.sh | bash

Manual Install

Otherwise, download the latest release and extract it to /usr/local/bin/summon.

Usage

By default, summon will look for secrets.yml in the directory it is called from and export the secret values to the environment of the command it wraps.

Example

You want to run script that requires AWS keys to list your EC2 instances.

Define your keys in a secrets.yml file

AWS_ACCESS_KEY_ID: !var aws/iam/user/robot/access_key_id
AWS_SECRET_ACCESS_KEY: !var aws/iam/user/robot/secret_access_key

The script uses the Python library boto, which looks for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the environment.

import boto
botoEC2 = boto.connect_ec2()
print(botoEC2.get_all_instances())

Wrap the Python script in summon:

summon python listEC2.py

python listEC2.py is the command that summon wraps. Once the Python program exits, the secrets stored in temp files and in the Python process environment are gone.

Flags

summon supports a number of flags.

  • -p, --provider specify the path to the provider summon should use

    If the provider is in the default path, /usr/local/lib/summon/ you can just provide the name of the executable. If not, use a full path.

  • -f <path> specify a location to a secrets.yml file, default 'secrets.yml' in current directory.

  • -D 'var=value' causes substitution of value to $var.

    You can use the same secrets.yml file for different environments, using -D to substitute variables. This flag can be used multiple times.

    Example

    summon -D ENV=production --yaml 'SQL_PASSWORD: !var env/$ENV/db-password' deploy.sh
    
  • -i, --ignore A secret path for which to ignore provider errors

    This flag can be useful for when you have secrets that you don't need access to for development. For example API keys for monitoring tools. This flag can be used multiple times.

  • -I, --ignore-all A boolean to ignore any missing secret paths

    This flag can be useful when the underlying system that's going to be using the values implements defaults. For example, when using summon as a bridge to confd.

  • -e, --environment Specify section (environment) to parse from secret YAML

    This flag specifies which specific environment/section to parse from the secrets YAML file (or string). In addition, it will also enable the usage of a common (or default) section which will be inherited by other sections/environments. In other words, if your secrets.yaml looks something like this:

common:
  DB_USER: db-user
  DB_NAME: db-name
  DB_HOST: db-host.example.com

staging:
  DB_PASS: some_password

production:
  DB_PASS: other_password

Doing something along the lines of: summon -f secrets.yaml -e staging printenv | grep DB_, summon will populate DB_USER, DB_NAME, DB_HOST with values from common and set DB_PASS to some_password.

Note: default is an alias for common section. You can use either one.

View help and all flags with summon -h.

env-file

Using Docker? When you run summon it also exports the variables and values from secrets.yml in VAR=VAL format to a memory-mapped file, its path made available as @SUMMONENVFILE.

You can then pass secrets to your container using Docker's --env-file flag like so:

summon docker run --env-file @SUMMONENVFILE myorg/myimage

This file is created on demand - only when @SUMMONENVFILE appears in the arguments of the command summon is wrapping. This feature is not Docker-specific; if you have another tools that reads variables in VAR=VAL format you can use @SUMMONENVFILE just the same.

Development

Run the project with:

go run cmd/main.go

Testing

Tests are written using GoConvey. Run tests with go test -v ./... or ./test (for CI).

Building and packaging

To build versions for Linux, OSX and Windows:

./build

Binaries will be placed in output/.