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

Verified

This commit was signed with the committer’s verified signature.
krysopath krysopath
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.