GitHub
commit
4550a73404
142
README.md
142
README.md
|
|
@ -10,11 +10,13 @@ but works recursively on encrypted files and in-line variables
|
|||
[](https://www.python.org)
|
||||
[](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
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
"""
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue