enpaul/vault2vault
1
0
Fork 0
mirror of https://github.com/enpaul/vault2vault.git synced 2024-11-21 17:46:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1 from enpaul/enp/docs

Browse Source 
Add documentation
This commit is contained in:
Ethan Paul 2022-05-07 18:43:33 -04:00 committed by GitHub
commit 4550a73404
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 117 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
README.md
View File

@ -10,11 +10,13 @@ but works recursively on encrypted files and in-line variables
[![Python Supported Versions](https://img.shields.io/pypi/pyversions/vault2vault)](https://www.python.org)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
⚠️ **This project is alpha software and is under active development** ⚠️
⚠️ **This project is beta software and is under active development** ⚠️
- [What is this?](#what-is-this)
- [Installing](#installing)
- [Using](#using)
- [Usage](#usage)
- [Recovering from a failed migration](#recovering-from-a-failed-migration)
- [Roadmap](#roadmap)
- [Developing](#developer-documentation)
## What is this?
@ -27,13 +29,11 @@ terminal. Whatever, these things happen.
The built-in tool Ansible provides,
[`ansible-vault rekey`](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html#rekey),
suffers from two main drawbacks:
1. It only works on vault encrypted files and not on vault encrypted YAML data
2. It only works on a single vault encrypted file at a time.
To rekey everything in a large project you'd need to write a script that goes through
every file and rekeys everything in every format it can find.
suffers from two main drawbacks: first, it only works on vault encrypted files and not on
vault encrypted YAML data; and second, it only works on a single vault encrypted file at
a time. To rekey everything in a large project you'd need to write a script that
recursively goes through every file and rekeys every encrypted file and YAML variable all
at once.
This is that script.
@ -58,44 +58,104 @@ install `vault2vault` using [PipX](https://pypa.github.io/pipx/) and the `ansibl
pipx install vault2vault[ansible]
```
**Note: vault2vault requires an Ansible installation to function. If you are installing to a standalone virtual environment (like with PipX) then you must install it with the `ansible` extra to ensure a version of Ansible is available to the application.**
> Note: vault2vault requires an Ansible installation to function. If you are installing to a
> standalone virtual environment (like with PipX) then you must install it with the
> `ansible` extra to ensure a version of Ansible is available to the application.\*\*
## Using
## Usage
These docs are pretty sparse, largely because this project is still under active design
and redevelopment. Here are the command line options:
> Note: the full command reference is available by running `vault2vault --help`
```
> vault2vault --help
usage: vault2vault [-h] [--version] [--interactive] [-v] [-b] [-i VAULT_ID] [--ignore-undecryptable]
[--old-pass-file OLD_PASS_FILE] [--new-pass-file NEW_PASS_FILE]
[paths ...]
Vault2Vault works with files in any arbitrary directory structures, so there is no need to
have your Ansible project(s) structured in a specific way for the tool to work. The
simplest usage of Vault2Vault is by passing the path to your Ansible project directory to
the command:
Recursively rekey ansible-vault encrypted files and in-line variables
positional arguments:
paths Paths to search for Ansible Vault encrypted content
options:
-h, --help show this help message and exit
--version Show program version and exit
--interactive Step through files and variables interactively, prompting for confirmation before making
each change
-v, --verbose Increase verbosity; can be repeated
-b, --backup Write a backup of every file to be modified, suffixed with '.bak'
-i VAULT_ID, --vault-id VAULT_ID
Limit rekeying to encrypted secrets with the specified Vault ID
--ignore-undecryptable
Ignore any file or variable that is not decryptable with the provided vault secret instead
of raising an error
--old-pass-file OLD_PASS_FILE
Path to a file with the old vault password to decrypt secrets with
--new-pass-file NEW_PASS_FILE
Path to a file with the new vault password to rekey secrets with
```bash
vault2vault ./my-ansible-project/
```
Please report any bugs or issues you encounter on
[Github](https://github.com/enpaul/vault2vault/issues).
The tool will prompt for the current vault password and the new vault password and then
process every file under the provided path. You can also specify multiple paths and
they'll all be processed together:
```bash
vault2vault \
./my-ansible-project/playbooks/ \
./my-ansible-project/host_vars/ \
./my-ansible-project/group_vars/
```
To skip the interactive password prompts you can put the password in a file and have the
tool read it in at runtime. The `--old-pass-file` and `--new-pass-file` parameters work
the same way as the `--vault-password-file` option from the `ansible` command:
```bash
vault2vault ./my-ansible-project/ \
--old-pass-file=./oldpass.txt \
--new-pass-file=./newpass.txt
```
If you use multiple vault passwords in your project and want to roll them you'll need to
run `vault2vault` once for each password you want to change. By default, `vault2vault`
will fail with an error if it encounters vaulted data that it cannot decrypt with the
provided current vault password. To change this behavior and instead just ignore any
vaulted data that can't be decrypted (like, for example, if you have data encrypted with
multiple vault passwords) you can pass the `--ignore-undecryptable` flag to turn the
errors into warnings.
> Please report any bugs or issues you encounter on
> [Github](https://github.com/enpaul/vault2vault/issues).
### Recovering from a failed migration
This tool is still pretty early in it's development, and to be honest it hooks into
Ansible's functionality in some fragile ways. I've tested as best I can to ensure it
covers as many edge cases as possible, but there is still the chance that you might get
partway through a password migration and then have the tool fail out, leaving half of your
data successfully rekeyed and the other half not.
In the spirit of the
[Unix philosophy](https://hackaday.com/2018/09/10/doing-one-thing-well-the-unix-philosophy/)
this tool does not include any built-in way to recover from this state. However, it can
be done very effectively using a version control tool.
If you are using Git to track your project files then you can use the command
`git reset --hard` to restore all files to the state of the currently checked out commit.
This does have the side effect of erasing any other un-committed work in the repository,
so it's recommended to always have a clean working tree when using Vault2Vault.
If you are not using a version control system to track your project files then you can
create a temporary Git repository to use in the event of a migration failure:
```bash
cd my-project/
# Initialize the new repository
git init
# Add and commit all your existing files to the git tree
git add .
git commit -m "initial commit"
# Run vault migrations
vault2vault ...
# If no recovery is necessary, delete the git repository data
rm -rf .git
```
## Roadmap
This project is considered feature complete as of the
[0.1.1](https://github.com/enpaul/vault2vault/releases/tag/0.1.1) release. As a result the
roadmap focuses on stability and user experience ahead of a 1.0 release.
- [ ] Reimplement core vaulted data processing function to enable multithreading
- [ ] Implement multithreading for performance in large environments
- [ ] Add unit tests
- [ ] Add integration tests
- [ ] Redesign logging messages to improve clarity and consistency
## Developer Documentation

2
pyproject.toml
View File

@ -1,6 +1,6 @@
[tool.poetry]
name = "vault2vault"
version = "0.1.1"
version = "0.1.2"
license = "MIT"
authors = ["Ethan Paul <24588726+enpaul@users.noreply.github.com>"]
description = "Recursively rekey ansible-vault encrypted files and in-line variables"

16
vault2vault.py
View File

@ -28,7 +28,7 @@ except ImportError:
__title__ = "vault2vault"
__summary__ = "Recursively rekey ansible-vault encrypted files and in-line variables"
__version__ = "0.1.1"
__version__ = "0.1.2"
__url__ = "https://github.com/enpaul/vault2vault/"
__license__ = "MIT"
__authors__ = ["Ethan Paul <24588726+enpaul@users.noreply.github.com>"]
@ -73,6 +73,19 @@ def _process_file( # pylint: disable=too-many-statements
backup: bool,
ignore: bool,
) -> None:
"""Determine whether a filepath includes vaulted data and if so, rekey it
:param path: Path to the file to check
:param old: VaultLib object with the current (old) vault password encoded in it
:param new: VaultLib object with the target (new) vault password encoded in it
:param interactive: Whether to prompt interactively for confirmation before each
rekey operation
:param backup: Whether to copy the original file to a backup before making any
in-place changes
:param ignore: Whether to ignore any errors that come from failing to decrypt
any vaulted data
"""
logger = logging.getLogger(__name__)
logger.debug(f"Processing file {path}")
@ -348,6 +361,7 @@ def _load_password(
the password will be prompted for interactively.
:param desc: Description text to inject into the interactive password prompt. Useful when using
this function multiple times to identify different passwords to the user.
:param confirm: Whether to prompt twice for the input and check that the two inputs match
:returns: Populated vault secret object with the loaded password
"""