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
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.
brew tap cyberark/tools brew install summon
Linux (Debian and Red Hat flavors)
rpm files are attached to new releases.
These can be installed with
dpkg -i summon.deb and
rpm -ivh summon.rpm, respectively.
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
curl -sSL https://raw.githubusercontent.com/cyberark/summon/master/install.sh | bash
Otherwise, download the latest release and extract it to
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.
You want to run script that requires AWS keys to list your EC2 instances.
Define your keys in a
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_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.
summon supports a number of flags.
-p, --providerspecify 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
You can use the same secrets.yml file for different environments, using
-Dto substitute variables. This flag can be used multiple times.
summon -D ENV=production --yaml 'SQL_PASSWORD: !var env/$ENV/db-password' deploy.sh
-i, --ignoreA 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-allA 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, --environmentSpecify 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
default) section which will be inherited by other sections/environments. In other words, if your
secrets.yamllooks 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_HOST with values from
common and set
default is an alias for
common section. You can use either one.
View help and all flags with
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
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
you can use
@SUMMONENVFILE just the same.
Run the project with:
go run cmd/main.go
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:
Binaries will be placed in