sopstool is a multi-file wrapper around sops. It uses the sops binary to encrypt and decrypt files, and piggybacks off the .sops.yaml configuration file.
sopstool provides functionality to manage multiple secret files at once, and even use as an entrypoint to decrypt at startup, for container images. Much of this behavior is inspired by the great blackbox project.
1.0.0 release of sopstool
introduces M1 / darwin-arm64 support. We also want to match build artifacts produced by GoReleaser to what sops
produces. Therefore, this version introduces a breaking change where we no longer produce artifacts like sopstool_linux.(deb|rpm|tar.gz)
and sopstool_darwin.tar.gz
. Instead, you'll see artifacts like sopstool_darwin_(arm64|amd64)_(deb|rpm|tar.gz)
and sopstool_linux_(arm64|amd64)_(deb|rpm|tar.gz)
in future releases.
sopstool is available in the following repositories
Ibotta/public
tap: brew install Ibotta/public/sopstool
sopstool
plugin: asdf plugin add sopstool
Images are tagged with the same version numbering as the releases, and latest
always gets the latest release. Note that your image will need root CA certificates (typically installed with curl, or a ca-certificates
package).
To use sopstool from container (avoiding doing binary installs):
docker run --rm -v $(pwd):/work -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION -e AWS_SECURITY_TOKEN -e AWS_SESSION_TOKEN ghcr.io/ibotta/sopstool:latest $COMMAND
sopstool
is the entrypoint, so any sopstool subcommand can be run./work
is the default WORKDIR - this should be mounted to the root where .sops.yml
is stored.Or, use as a install source in your Dockerfile. sops
and sopstool
are in /usr/local/bin/
:
COPY --from=ghcr.io/ibotta/sopstool:latest usr/local/bin/sops usr/local/bin/sopstool /usr/local/bin/
Check the Releases for the latest artifacts
sops
installed manually)All artifacts have their sha256 checksums recorded in sopstool_checksums.txt
, and SPDX SBOM artifacts are available.
The most direct install uses a shell script hosted in this repository. This script will install the latest sops (if the command does not exist) and sopstool to ./bin
by default.
curl https://raw.githubusercontent.com/Ibotta/sopstool/main/install.sh | bash
-s
argument-t
argument-b
argument
sudo
or root access if you are installing to /usr/*
Example with overrides:
curl https://raw.githubusercontent.com/Ibotta/sopstool/main/install.sh | bash -s -- -b /usr/local/bin -s 3.0.0 -t 0.3.0
sopstool requires sops. You can use one of the following methods:
The install script above uses a separate script to download sops
curl https://raw.githubusercontent.com/Ibotta/sopstool/main/sopsinstall.sh | bash
/.bin
)To avoid needing to find the 'latest' binary by hand or by script, use our https server to download the binary. The latest binary is uploaded automatically whenever sopstool is deployed. The file has the pattern sops_$OS_$ARCH
, except for windows
linux
, darwin
amd64
, arm64
sops_$OS_$ARCH.tar.gz
windows
amd64
onlysops_windows.zip
https://oss-pkg.ibotta.com/sops/$filename
https://oss-pkg.ibotta.com/sops/$TAG/$filename
Following the lead of sops, we only build 64bit binaries.
The install script above uses a separate script to download sopstool
curl https://raw.githubusercontent.com/Ibotta/sopstool/main/sopstoolinstall.sh | bash
/.bin
)To avoid needing to find the 'latest' binary by hand or by script, use our https server to download the binary. The latest binary is uploaded automatically whenever sopstool is deployed.
linux
, darwin
amd64
, arm64
sopstool_$OS_$ARCH.tar.gz
windows
amd64
, arm64
sopstool_windows_$ARCH.zip
https://oss-pkg.ibotta.com/sopstool/$filename
https://oss-pkg.ibotta.com/sopstool/$TAG/$filename
Additionally, all other release assets are also within this folder. This includes the checksums, packages, sboms, as well as installers:
https://oss-pkg.ibotta.com/sopstool/install.sh
for the combined installerhttps://oss-pkg.ibotta.com/sopstool/sopsinstall.sh
for the sops installerhttps://oss-pkg.ibotta.com/sopstool/sopstoolinstall.sh
for the sopstool installerThis is a package that builds a single binary (per architecture) for wrapping sops with multi-file capabilities.
for more details, use the built-in documentation on commands:
sopstool -h
to get the shell completion helpers:
#!/usr/bin/env bash
sopstool completion
#!/usr/bin/env zsh
sopstool completion --sh zsh
use a .sops.yaml
file
this will be at the root of your project. this file is used to both configure keys as well as hold the list of files managed.
it needs to specify at least one KMS key accessible by your environment
creation_rules:
- kms: arn:aws:kms:REGION:ACCOUNT:key/KEY_ID
it can specify more complex cases of patterns vs keys too (see link)
.sops.yaml
file at the root directory where your scripts will run.
.sops.yaml
configuration file..yaml
if you wish to do the ENTIRE file), or create a yaml file with key: value
pairs(and make sure it's extension is .yaml
). Sops will encrypt the values, but not it's keys.
sopstool
is ready and you can now sopstool add filename
. You'll notice it will create a filename.sops.extension
. This is your newly encrypted file.
sopstool clean
to remove the original plain text secret files.sopstool edit filename.sops.extension
. You can also use your original filename too! sopstool edit filename.extension
sopstool list
sopstool remove filename.extension
sopstool cat filename.extension
In this walkthrough, we will go through the steps required to get a secure yaml configuration file running.
Configure your .sops.yaml
# .sops.yaml
creation_rules:
- kms: arn:aws:kms:REGION:ACCOUNT:key/KEY_ID
Create a secrets yaml configuration file
# credentials.yaml
database.password: supersecretdb
database.user: supersecretpassword
redshift:
user: my.user.name
password: my.password
Encrypt the newly created file
sopstool add credentials.yaml
Create a sample script
# myscript.py
import yaml
with open('credentials.yaml', 'r') as f:
credentials = yaml.load(f)
print credentials["database.user"]
print credentials["database.password"]
print credentials["redshift"]["user"]
print credentials["redshift"]["password"]
Here is what your folder structure would look like to this point(after deleting the unencrypted credentials.yaml file)
my-project/
├── .sops.yaml
├── credentials.sops.yaml
└── myscript.py
Accessing credentials
The flow should be as follows: unencrypt credentials -> run script -> destroy credentials. You can use the sopstool entrypoint
to achieve this.
sopstool entrypoint python myscript.py
Bug reports and pull requests are welcome at https://github.com/Ibotta/sopstool
Generate markdown docs for the commands via
sopstool docs