summon: handing secrets to a subprocess from the command line

Four jobs, one command

summon is a command line tool to make working with secrets easier, and the README lists the four things it does for you.

It reads a secrets.yml file. It fetches secrets from a trusted store. It exports secret values to a sub-process environment. And it writes secrets to files in various formats, which the list calls push to file.

The second of those is the one that makes the tool possible, and the fourth is the one that people tend to forget. A tool that only exports to an environment covers the case of running a process that reads its configuration from the environment, which is most of them. A tool that can also write a file covers the case of a process that insists on a configuration file, which is a large number of legacy services, and it does that without the secret passing through a shell history or a process listing.

The whole model is that summon wraps a command. You do not run summon and then ask it for a value, you run summon and it starts your program with the values already in place. The classic example in the README is running it with env and filtering the output.

Two practical notes come out of the install section. Installing summon alone is not sufficient, because you also need a provider of your choice before it is ready for use. And pre-built binaries and packages are available from the GitHub releases.

The project is MIT licensed, written in Go, and not archived, with the last push on 2026-09-16. The releases are v0.13.1 and v0.13.0, both on the same day, with v0.11.0 from 2026-03-20 before them. The documentation site is no longer maintained, and the README says explicitly that it is the authoritative source for configuration and usage information, which is worth knowing before you follow a tutorial that points at the old site.

The secrets file, and the var tag

The configuration file is YAML, and the interesting part is the tag that tells summon where a value comes from.

DB_PASSWORD: !var production/db/password
API_KEY: !var production/api/key

The key is the name the value will have in the environment, and the value is a reference to a secret in the store, with the path following the provider's own naming. A database password is requested from the path for production, the database, and the password entry, and an API key from the production API key path.

That indirection is the point of the tool. The file in your repository contains no secret values, only the names of variables and the references to fetch, and the file can therefore be committed and reviewed like any other configuration. The value is resolved at the moment the process starts, from whatever store the provider talks to.

The same file also describes the file output, since the tool writes secrets to files in various formats. That means the mapping from a name in the store to a path on disk is declared in one place, next to the environment mapping, rather than in a script.

The example in the README is small, and it is a YAML file with a custom tag, so a plain YAML parser will not read it without a handler for that tag. That is normal for this kind of tool and is worth knowing before you try to lint the file with a generic YAML checker in your continuous integration.

The built-in Conjur provider, and how it is selected

Summon ships with a built-in Conjur provider, and no separate binary install is needed for it. It activates automatically when the provider directory has no other binaries, or explicitly when you pass the provider flag with the value conjur.

The selection rule is stated precisely, and it is the kind of detail that produces a confusing error when it goes wrong. If the provider directory contains exactly one binary, summon uses that binary automatically. If it contains two or more, summon exits with an error and prompts you to specify one with the provider flag. The built-in Conjur provider is only used as the automatic fallback when the directory is empty.

So there are three states. An empty directory means the built-in Conjur provider. A directory with exactly one binary means that binary. A directory with two or more means an error, because summon cannot guess which one you meant and refuses to pick for you.

The quick start shows the built-in provider in use, and the point is that no provider flag is needed at all, because summon detects it automatically.

export CONJUR_APPLIANCE_URL=https://conjur.example.com
export CONJUR_ACCOUNT=myorg
export CONJUR_AUTHN_LOGIN=host/myapp
export CONJUR_AUTHN_API_KEY=<api-key>

summon -f secrets.yml env | grep -E 'DB_PASSWORD|API_KEY'

That is the whole flow. Four environment variables describe the connection and the identity, the file names the secrets, the command after the file name is what gets launched, and the output of that command is what you see.

There is also guidance about versions. If you use the project with Conjur Open Source, the README strongly recommends choosing the version from the latest Conjur open source suite release, because the Conjur maintainers perform additional testing on the suite release versions to ensure compatibility, and when using integrations you should choose the latest suite release that matches your Conjur version.

Seven ways to authenticate

The built-in provider supports a table of authentication methods, selected through the CONJUR_AUTHN_TYPE variable, and the table is the most useful part of the documentation.

An API key is the default, with the type variable unset, and it needs the login and the API key. An existing token is also selected by leaving the type unset, and takes either the token inline or the path to a token file.

The JWT method takes the type value jwt, and needs a JWT authenticator service ID, plus either the path to a JWT token file or the token inline, plus the host identity, which is required when the token app property is not configured. The default path for the token file is the in-cluster Kubernetes service account path.

AWS IAM takes the type value iam and needs a service ID and the host identity. Azure takes the type value azure and needs a service ID, the host identity, and optionally a client ID for a managed identity, which selects a specific identity on a host that has more than one. GCP takes the type value gcp and needs the host identity, which is required only when the token is fetched automatically from the GCP metadata service.

The last row is certificate authentication, with the type value cert, and it is implied when the certificate service ID variable is set. It needs the service ID, the certificate file, and the key file, with the host identity optional.

Two details in that table are worth pulling out. The first is that several cloud methods need the same host identity variable, because the workload identity is what the authenticator issues a token for, and the second is that the token file path defaults to the Kubernetes service account location, which is what makes the JWT method work inside a cluster with no configuration at all.

The implication for an operator is that the same summon command works in a laptop, in a continuous integration job, and in a cluster, as long as the environment is arranged for the method that fits, and the method is chosen by a variable rather than by a different command.

Configuration precedence, and the two certificate variables

The provider loads its configuration from three places, and the precedence is worth knowing because the common failure is a setting that is being overridden.

It reads a configuration file in the home directory, in the current directory, or at the path set in the CONJUR_RC variable. It reads the system configuration at /etc/conjur.conf on Linux and macOS, and at the Windows path under the Windows directory. And it reads environment variables, which take precedence over the file based configuration.

So a variable set in your shell always wins, which is the behaviour you want for a one-off override and the behaviour that surprises people when a value set in a profile file is not taking effect.

The connection settings are a short table. The appliance URL, the organisation account, the path to the Conjur SSL certificate file, and an inline PEM encoded certificate.

The precedence between the two certificate variables is spelled out. When both the inline certificate and the certificate file are set, the inline one takes precedence, and the recommendation is to set only one to avoid confusion.

There is a second pair of variables that people mix up, and the README explains them separately. The Conjur certificate file is the server's TLS certificate, used to verify the HTTPS connection. The authentication certificate file is the client certificate presented to Conjur during certificate authentication, which is mutual TLS. They serve different purposes and can both be set at the same time.

The authentication table is longer and worth reading in full, because it is the reference for a dozen variables that only appear in error messages otherwise. There is the login, the API key, the token and its file, the JWT service ID, the host identity, the Azure client ID, the inline JWT token, and the certificate service ID, which implicitly activates certificate authentication and takes precedence over the generic service ID variable.

The repository, the test rig, and the security posture

The repository is a serious Go project with an unusual amount of security tooling for a command line utility.

The module is github.com/cyberark/summon with a go directive of 1.26.7, and the direct dependencies are few. The Conjur API client, the command line framework, the YAML library, and the test assertions. The indirect list is long, because the AWS SDK for Go v2 and its services for STS, SSO, OIDC, and the instance metadata service come in through the cloud authentication methods, and there is a keyring library for the operating system credential store.

The test infrastructure is where the project spends its effort. There is a compose file that brings up a Conjur server against a PostgreSQL database, a mock JWT server for the authentication tests, and a test service that runs the acceptance suite inside the container. The public images stay on Docker Hub while the Conjur images are pulled from a private registry that can be overridden with an environment variable, and the comment in the file explains exactly that.

The hardening is the part that stands out. The database service drops all capabilities and then adds back only the ownership and setuid ones it needs, and every service sets the no-new-privileges security option. The Compose file also carries inline suppressions for a scanning tool, which is the kind of thing you only see in a project that is scanned in continuous integration, and the repository has a KICS configuration, a gitleaks configuration, a Code Climate configuration, and a Jenkinsfile alongside the GitHub workflows.

The Dockerfiles are separate for the test and the acceptance runs, and the main one builds with a vendored dependency tree, which is a supply chain practice worth copying whether or not you use the tool.

The licence is MIT, there is a security policy, a contributing guide, a changelog, and a directory of examples with a Docker setup and a symlinks example, which is a hint about one of the ways the tool is used in practice.

Editorial conclusion

summon fits a team that already runs a secret store, whether Conjur or a provider with its own binary, and that wants one command to wrap a process with the right values in its environment instead of exporting variables by hand in a shell profile. It does not fit a team that has no secret store yet, since installing summon alone is explicitly not sufficient. Verify first that you have a provider, that the provider directory has exactly one binary or that you pass the provider flag, that the authentication method you need is one of the supported ones, and that the two certificate variables are not confused, since one verifies the server and the other is the client identity presented to it.

Frequently asked questions

Official sources

1. cyberark/summon on GitHub
2. License: MIT
3. Project website
4. README
5. Releases