Skip to content

Commit

Permalink
test org mode markdown readme
Browse files Browse the repository at this point in the history
krysopath committed Apr 20, 2019
1 parent 5b499c1 commit 6acc0fc
Showing 1 changed file with 79 additions and 80 deletions.
159 changes: 79 additions & 80 deletions README.md → README.org
Original file line number Diff line number Diff line change
@@ -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 ([email protected])

* 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 [email protected]: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=<a-provider-of-your-choice>
export VAULTIFY_CONSUMER=<a-consumer-of-your-choice>
export VAULTIFY_LOGLEVEL=<critical|warning|info|debug> # 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 <secretfile>
```
#+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=<passphrase>
```
#+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 <file> -out <file>.enc
#+END_SRC
```

> Do not use aes-256-cbc, if there is aes-256-gcm available in your openssl.
@@ -131,69 +126,73 @@ 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=<passphrase>
```

#### 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=<vault.org.tld>
# set this to nodes in vaults kv engine, where you do have perms for READ
export VAULT_PATHS=<comma-separated-list-of-paths-for-vaults-kv-engine>

# if you do not set $VAULTIFY_SECRET, then
export VAULT_TOKEN=<a-valid-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.

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.

0 comments on commit 6acc0fc

Please sign in to comment.