diff --git a/README.md b/README.org similarity index 68% rename from README.md rename to README.org index c195444..723598e 100644 --- a/README.md +++ b/README.org @@ -1,125 +1,120 @@ -# vaultify - -Our greater purpose is to **never leave any secret file on a persisting -filesystem.** - -`vaultify` allows to integrate various means of secret provision into -any runtime environment, may it be some `containerd`, virtualized box or -bare-metal. Currently, we provide three means of fetching secrets and three -means of consuming them. - - ->see the table in the feature section for more - -## architecture - -vaultify is an extensible program, which is driven by a notion of -providers and consumers. Providers are classes, that are meant to -fetch/generate/decrypt secrets and pass them as a dictionary to a -consumer. The consumer will then digest that dictionary in the way it -has been designed: writing it as a `.env` file, some `.json` or spawn -a new process within vaultify-enriched environment. - - -> You want to store secret environment keys in a gpg encrypted file -> and then provide to it to the environment: use -> the `GPGProvider`-provider and the `EnvRunner`-consumer, e.g. - -vaultify will try to compile all secrets into one dictionary, and then -write those to either a volatile file system or just enrich the -current environment. - -What will be done actually is configurable via the environment, that -executes vaultify. - -## os dependencies - -ubuntu: -``` -apt-get install entr make -``` - -## usage - -### first steps +#+TITLE: vaultify usage +#+OPTIONS: +#+AUTHOR: Georg vom Endt (krysopath@gmail.com) + +* Installation +This section explains different installation methods. +** Requirements + - python3.6, python3.7 + - pip + - docker (obsoletes the above) + +** from pypi +Most implementers will fetch the package from pypi and build their own +things on another layer. +#+BEGIN_SRC shell +pip3 install vaultify +#+END_SRC + +** from git +Alternatively fetch the sources from github to develop your own +adapter classes. +#+BEGIN_SRC shell +git clone git@github.com:krysopath/vaultify.git +#+END_SRC +** os dependencies +These tools can greatly speed up local development, when used in +conjunction via ~make~, so install them. They can overwhelm you with +output, too. + +*** ubuntu +#+BEGIN_SRC shell +apt install make entr yamllint pylint bandit +#+END_SRC + +* usage + +** first steps 1. either create a virtualenv and install requirements.txt or 2. run `docker build .` Before using `vaultify` you need to export these into your environment: -```bash +#+BEGIN_SRC export VAULTIFY_PROVIDER= export VAULTIFY_CONSUMER= export VAULTIFY_LOGLEVEL= # default is info -``` +#+END_SRC >**r**ead **t**he **f**riendly **m**anual for the chosen Provider & Consumer, too Then just run: -```bash +#+BEGIN_SRC ./entry.py -``` +#+END_SRC -## feature overview + +** feature overview In this table you find an info about which Provider/Consumer pairs are supported: -``` - | GPG | OpenSSL | Vault | -|--------------|-----|---------|-------| -| DotEnvWriter | y | y | y | -| EnvRunner | y | y | y | -| JsonWriter | y | y | y | -``` +| pairs | GPG | OpenSSL | Vault | +|--------------+-----+---------+-------| +| DotEnvWriter | y | y | y | +| EnvRunner | y | y | y | +| JsonWriter | y | y | y | + Assuming the pattern holds, we expect always full compatibility between any Provider/Consumer pair. -### providers +** providers Providers are all classes, that create some `vaultify`-compliant dictionary, which then is used by `vaultify` consumers. -#### GPGProvider +*** GPGProvider This Provider can decrypt symmetrically encrypted files, created with `gpg`. Adhere to this format: -```bash +#+BEGIN_SRC KEY1=VAL1 [...] KEYN=VALN -``` +#+END_SRC To encrypt such a file, execute: -```bash +#+BEGIN_SRC gpg --symmetric -``` +#+END_SRC Below are environment variables, that are needed by this provider: -```bash +#+BEGIN_SRC # this will be used as the passphrase to gpg export VAULTIFY_SECRET= -``` +#+END_SRC -#### OpenSSLProvider +*** OpenSSLProvider This provider can decrypt symmetrically encrypted files, created with `openssl` Adhere to this format: -```bash +#+BEGIN_SRC KEY1=VAL1 [...] KEYN=VALN -``` +#+END_SRC To encrypt such a file, execute: ```bash +#+BEGIN_SRC openssl enc -aes-256-cbc -salt -a -in -out .enc +#+END_SRC ``` > Do not use aes-256-cbc, if there is aes-256-gcm available in your openssl. @@ -131,18 +126,20 @@ supports aes-256-gcm, please file a bug report against vaultify. Below are environment variables, that are needed by this provider: ```bash +#+BEGIN_SRC +#+END_SRC # this will be used as the passphrase to openssl export VAULTIFY_SECRET= ``` -#### VaultProvider +*** VaultProvider This provider fetches secrets from HashiCorp Vault API. Below are environment variables, that are needed by this provider: -```bash +#+BEGIN_SRC # set this to a reachable vault API export VAULT_ADDR= # set this to nodes in vaults kv engine, where you do have perms for READ @@ -150,38 +147,38 @@ export VAULT_PATHS= # if you do not set $VAULTIFY_SECRET, then export VAULT_TOKEN= -``` +#+END_SRC `VaultProvider` will use `VAULTIFY_SECRET` or `VAULT_TOKEN` for authentication, in that order. -### consumers +** consumers are all classes that operate on a `vaultify` compliant dictionary, to **somehow** use the secrets in there for the greater good. -#### DotEnvWriter +*** DotEnvWriter This simplest form of vaultification just creates a plaintext file with the form of -```bash +#+BEGIN_SRC export Key1=Value1 [...] export KeyN=ValueN -``` +#+END_SRC for all N keys in the provided dictionary. Below are environment variables, that are needed by this consumer: -```bash +#+BEGIN_SRC # this controls the location of the dotenv file export VAULTIFY_DESTFILE=/a/path/to/where/secrets.env -``` +#+END_SRC -#### JsonWriter +*** JsonWriter This consumer is very similar to the `DotEnvWriter`, but produces a json file instead. @@ -189,11 +186,13 @@ json file instead. Below are environment variables, that are needed by this consumer: ```bash +#+BEGIN_SRC +#+END_SRC # this controls the location of the dotenv file export VAULTIFY_DESTFILE=/a/path/to/where/secrets.json ``` -#### EnvRunner +*** EnvRunner If you want to just execute a process with some secrets, then `EnvRunner` consumer will run a subprocess with an enriched @@ -208,9 +207,9 @@ accidentally persist after a crash Below are environment variables, that are needed by this consumer: -```bash +#+BEGIN_SRC # this controls the invocation of the target process. export VAULTIFY_TARGET='/a/path/where/a/secret/hungry/binary --with-some flag wants-execution' -``` +#+END_SRC Currently `EnvRunner` does not support interactive commands.