Merge pull request #1 from enpaul/enp/docs

Add documentation

README.md

@@ -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:
+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
-1. It only works on vault encrypted files and not on vault encrypted YAML data
+a time. To rekey everything in a large project you'd need to write a script that
-2. It only works on a single vault encrypted file at a time.
+recursively goes through every file and rekeys every encrypted file and YAML variable all
-
+at once.
-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.
 
 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
+> Note: the full command reference is available by running `vault2vault --help`
-and redevelopment. Here are the command line options:
 
-```
+Vault2Vault works with files in any arbitrary directory structures, so there is no need to
-> vault2vault --help
+have your Ansible project(s) structured in a specific way for the tool to work. The
-usage: vault2vault [-h] [--version] [--interactive] [-v] [-b] [-i VAULT_ID] [--ignore-undecryptable]
+simplest usage of Vault2Vault is by passing the path to your Ansible project directory to
-                   [--old-pass-file OLD_PASS_FILE] [--new-pass-file NEW_PASS_FILE]
+the command:
-                   [paths ...]
 
-Recursively rekey ansible-vault encrypted files and in-line variables
+```bash
-
+vault2vault ./my-ansible-project/
-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
 ```
 
-Please report any bugs or issues you encounter on
+The tool will prompt for the current vault password and the new vault password and then
-[Github](https://github.com/enpaul/vault2vault/issues).
+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
 

pyproject.toml

@@ -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"

vault2vault.py

@@ -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
     """