ansible-vars 1.0.12__py3-none-any.whl → 1.0.14__py3-none-any.whl

ansible_vars/cli.py

@@ -29,11 +29,6 @@ from pygments.lexers.templates import YamlJinjaLexer
 from pygments.formatter import Formatter
 from pygments.formatters import TerminalFormatter, Terminal256Formatter, TerminalTrueColorFormatter
 
-# If we need to change the working directory, we have to do it before loading the Ansible vault library
-# Else, keys will not be detected correctly
-ANSIBLE_HOME: str = os.environ.get('ANSIBLE_HOME', os.getcwd())
-os.chdir(ANSIBLE_HOME)
-
 # Internal module imports
 from .vault import VaultFile, EncryptedVar, ProtoEncryptedVar
 from .vault_crypt import VaultKey, VaultKeyring
@@ -203,11 +198,18 @@ Deletes a node from a vault if it exists.
 '''
 }
 
-DEFAULT_EDITOR: str = os.environ.get('EDITOR', 'notepad.exe' if os.name == 'nt' else 'vi')
-DEFAULT_COLOR_MODE: str = os.environ.get('AV_COLOR_MODE', '256' if sys.stdout.isatty() else 'none')
-DEFAULT_TEMP_DIR: str = os.environ.get('AV_TEMP_DIR', gettempdir())
-DEFAULT_CREATE_PLAIN: bool = os.environ.get('AV_CREATE_PLAIN', 'no').lower() in [ 'yes', 'y', 'true', 't', '1' ]
-DEFAULT_SALT: str | None = os.environ.get('AV_SALT', None)
+# Not using defaults directly because we also want to ignore empty values
+DEFAULT_EDITOR: str = os.environ.get('EDITOR', None) or ('notepad.exe' if os.name == 'nt' else 'vi')
+DEFAULT_COLOR_MODE: str = os.environ.get('AV_COLOR_MODE', None) or ('256' if sys.stdout.isatty() else 'none')
+DEFAULT_TEMP_DIR: str = os.environ.get('AV_TEMP_DIR', None) or gettempdir()
+DEFAULT_CREATE_PLAIN: bool = (os.environ.get('AV_CREATE_PLAIN', None) or 'no').lower() in [ 'yes', 'y', 'true', 't', '1' ]
+DEFAULT_SALT: str | None = os.environ.get('AV_SALT', None) or None
+DEFAULT_SECRETS_ROOT: str | None = os.environ.get('AV_SECRETS_ROOT', None) or os.environ.get('ANSIBLE_HOME', None) or None
+DEFAULT_RESOLVER_ROOT: str | None = os.environ.get('AV_RESOLVER_ROOT', None) or None
+
+# Resolve all paths as if the caller is in the resolver root
+if DEFAULT_RESOLVER_ROOT:
+    os.chdir(DEFAULT_RESOLVER_ROOT)
 
 args: ArgumentParser = ArgumentParser(
     prog = 'ansible-vars',
@@ -251,7 +253,12 @@ key_args = args.add_argument_group('vault key management', description=HELP['key
 key_args.add_argument(
     '--add-key', '-k', type=str, nargs=2, action='append', dest='keys', default=[], metavar=('<identifier>', '<passphrase>'), help='add a vault key'
 )
-key_args.add_argument('--no-detect-keys', '-D', action='store_false', dest='detect_keys', help='disable automatic key detection')
+key_mutex = key_args.add_mutually_exclusive_group()
+key_mutex.add_argument('--no-detect-keys', '-D', action='store_false', dest='detect_keys', help='disable automatic key detection')
+key_mutex.add_argument(
+    '--detection-source', type=str, metavar='<secrets root>', default=DEFAULT_SECRETS_ROOT,
+    help=f"use this directory or config file to detect keys (default: { DEFAULT_SECRETS_ROOT or 'CWD' })"
+)
 key_args.add_argument('--encryption-key', '-K', type=str, metavar='<identifier>', help='which of the loaded keys to use for encryption')
 key_args.add_argument(
     '--fixed-salt', '-S', type=str, metavar='<salt>', default=DEFAULT_SALT,
@@ -587,7 +594,10 @@ sys.excepthook = _exc_hook
 # Load vault keys
 
 _explicit_keys: list[VaultKey] = [ VaultKey(passphrase, vault_id=id) for id, passphrase in config.keys ]
-keyring = VaultKeyring(_explicit_keys.copy(), detect_available_keys=config.detect_keys, default_salt=config.fixed_salt)
+keyring: VaultKeyring = VaultKeyring(
+    _explicit_keys.copy(), default_salt=config.fixed_salt,
+    detect_available_keys=config.detect_keys, detection_source=config.detection_source
+)
 
 if config.encryption_key:
     keyring.default_encryption_key = keyring.key_by_id(config.encryption_key)

ansible_vars/vault.py

@@ -239,7 +239,7 @@ class Vault():
             return (-1, default) if with_index else default
 
     def set(
-            self, path: DictPath, value: Any, overwrite: bool | Type[ThrowError] = True,
+            self, path: DictPath, value: Any, overwrite: bool | Type[ThrowError] = True, # type: ignore
             create_parents: bool | Type[ThrowError] = True, encrypt: bool = False
         ) -> bool:
         '''
@@ -263,7 +263,7 @@ class Vault():
           - `True`: Attempt to copy and convert the value('s leaf values) into an `EncryptedVar` before storing it
           - `False`: Store the value as-is
         '''
-        path: tuple[Hashable, ...] = Vault._to_path(path)
+        path: tuple[Hashable, ...] = Vault._to_path(path) # XXX typer complains if not explicitly re-typed
         # Encrypt value if necessary
         if encrypt:
             value = Vault._copy_data(value)

ansible_vars/vault_crypt.py

@@ -1,13 +1,14 @@
 # Vault secret loading and management for ansible-vars
 
 # Standard library imports
-import re
-from typing import Type
+import os, re
+from typing import Type, cast
 
 # External library imports
 import ansible.constants as Ansible
 from ansible.parsing.vault import VaultLib, VaultSecret, AnsibleVaultError
 from ansible.cli import DataLoader, CLI
+from ansible.config.manager import ConfigManager
 
 # Internal module imports
 from .errors import NoMatchingVaultKeyError, NoVaultKeysError, VaultKeyMatchError
@@ -89,7 +90,7 @@ class VaultKey():
 class VaultKeyring():
     '''
     A collection of Ansible vault secrets to be used for en- and decrypting vault data.
-    Tries to infer available secrets from the caller's present working directory, if it is an Ansible home.
+    Tries to infer available secrets from the caller's present working directory or a custom source.
     '''
 
     def __init__(
@@ -97,12 +98,14 @@ class VaultKeyring():
             keys: list[VaultKey] | None = None,
             default_encryption_key: VaultKey | None = None,
             default_salt: str | None = None,
-            detect_available_keys: bool = True
+            detect_available_keys: bool = True,
+            detection_source: str | list[str] | None = None
         ) -> None:
         '''
         Create a new keyring of `VaultKey`s and optionally populate it with the given `keys`.
-        Tries to infer available Ansible vault secrets from the caller's present working directory, if it is an Ansible home.
+        Tries to infer available Ansible vault secrets from the caller's present working directory or a custom `detection_source`.
         This is done using the Ansible CLI module. You can disable key inferral by setting `detect_available_keys` to False.
+        Check the docstring of `VaultKeyring.load_cli_secrets` for details on alternative key detection sources.
         When decrypting vault data, inferred keys are tried after the explicitly supplied ones.
         Note that the inferral process may cause TTY prompts or other unwanted in- and output.
         
@@ -116,7 +119,7 @@ class VaultKeyring():
         self.default_encryption_key: VaultKey | None = default_encryption_key
         self.default_salt: str | None = default_salt
         if detect_available_keys:
-            self.keys.extend(VaultKeyring.load_cli_secrets())
+            self.keys.extend(VaultKeyring.load_cli_secrets(detection_source))
     
     @property
     def encryption_key(self) -> VaultKey:
@@ -169,17 +172,46 @@ class VaultKeyring():
         raise NoMatchingVaultKeyError(f"No matching key found for ID '{ id }' in { self }")
 
     @staticmethod
-    def load_cli_secrets() -> list[VaultKey]:
+    def load_cli_secrets(source: str | list[str] | None = None) -> list[VaultKey]:
         '''
-        Tries to infer available Ansible vault secrets from the caller's present working directory, if it is an Ansible home.
+        Tries to infer available Ansible vault secrets from the given configuration source's `vault_identity_list`.
+        - If `source` is None, check the environment and CWD for a configuration file path and check the file.
+        - If `source` is a file, check the file.
+        - If `source` is a directory, check `<source>/ansible.cfg`.
+        - If `source` is a list, it is used directly as the `vault_identity_list`.
+
+        Due to limitations in the Ansible interface, setting the environment variable `ANSIBLE_VAULT_IDENTITY_LIST`
+        will always override the result of the `source` check, except if `source` is a list of vault IDs.
+
         Inferred secrets are converted into `VaultKey`s and returned.
         Note that the inferral process may cause TTY prompts or other unwanted in- and output.
-        '''
-        # Ansible.DEFAULT_VAULT_IDENTITY_LIST is a list populated with vault IDs inferred from the PWD
-        # (i.e. has to be run in ANSIBLE_HOME, else the value is [])
-        secrets: list[tuple[str | None, VaultSecret]] = \
-            CLI.setup_vault_secrets(DataLoader(), Ansible.DEFAULT_VAULT_IDENTITY_LIST, auto_prompt=False) # type: ignore
-        return list(map(VaultKey.from_ansible_secret, secrets))
+        Not entirely thread-safe, as setting a specific `source` path will temporarily change the global CWD.
+        '''
+        pardir: str = os.getcwd()
+        # Set or discover available vault IDs
+        if isinstance(source, list | tuple):
+            vault_ids: list[str] = source
+        else:
+            if source:
+                if not os.path.exists(source):
+                    raise FileNotFoundError(f"Vault key detection path `{ source }` could not be resolved.")
+                if os.path.isdir(source):
+                    source = os.path.join(source, 'ansible.cfg')
+                pardir: str = os.path.dirname(cast(str, source))
+            vault_ids: list[str] = ConfigManager(conf_file=source).get_config_value('DEFAULT_VAULT_IDENTITY_LIST')
+        # Load secrets for discovered vault IDs
+        if not vault_ids:
+            return []
+        prev_dir: str = os.getcwd()
+        try:
+            # XXX Hacky, but loading a vault ID like 'vaultid@get-password.sh' will be resolved from CWD
+            #     Could possibly be avoided by splitting the detected vault IDs and transforming any right-hand paths
+            os.chdir(pardir)
+            secrets: list[tuple[str | None, VaultSecret]] = \
+                CLI.setup_vault_secrets(DataLoader(), vault_ids, auto_prompt=False, initialize_context=False) # type: ignore
+            return list(map(VaultKey.from_ansible_secret, secrets))
+        finally:
+            os.chdir(prev_dir)
 
     def __repr__(self) -> str:
         return f"VaultKeyring({ ', '.join(map(lambda key: key.id, self.keys)) or 'no keys' })"

{ansible_vars-1.0.12.dist-info → ansible_vars-1.0.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ansible-vars
-Version: 1.0.12
+Version: 1.0.14
 Summary: Manage vaults and variable files for Ansible
 Project-URL: Homepage, https://github.com/xorwow/ansible-vars
 Project-URL: Issues, https://github.com/xorwow/ansible-vars/issues
@@ -24,11 +24,15 @@ Description-Content-Type: text/markdown
 
 *Manage vaults and variable files for Ansible.*
 
+## TL;DR
+
+Replaces the `ansible-vault` command with `ansible-vars`, which supports encrypting individual variables, not just entire files. Also provides a CLI and Python interface for querying and modifying Ansible variable files and vaults.
+
 ## Introduction
 
 This project was motivated by a need to have Ansible vaults readable to humans and external programs like `grep` without a manual decryption step, while keeping secret values in these vaults secure from prying eyes. Ansible actually supports keeping vaults plain-text and only encrypting individual string variables, but this feature is not widely known or used and editing such files is not supported by the `ansible-vault` tool.
 
-`ansible-vars` allows you to do the same things `ansible-vault` does (and more!), but not just for fully encrypted vaults, but also plain variable files and vaults with hybrid encryption (encrypted variables and/or full encryption). This is significantly more complex, as `ansible-vault` can be agnostic to the contents of the file it en-/decrypts, while hybrid encryption requires full round-trip parsing of a vault's Jinja2 YAML code.
+`ansible-vars` allows you to do the same things `ansible-vault` does (and more!), but not just for fully encrypted vaults, but also plain variable files and vaults with hybrid encryption (individually (un)encrypted variables). This is significantly more complex, as `ansible-vault` can be agnostic to the contents of the file it en-/decrypts, while hybrid encryption requires full round-trip parsing of a vault's Jinja2 YAML code.
 
 The main features are:
 - Create and edit vaults and variable files with hybrid encryption support.
@@ -63,8 +67,8 @@ Note that the virtual environment must be active when using the command.
 ### Using [pipx](https://github.com/pypa/pipx)
 
 ```sh
-# Install pipx
-pip install pipx
+# Install pipx, e.g. like this on Debian
+sudo apt install pipx
 # Install pip package globally using pipx
 pipx install ansible-vars
 ```
@@ -93,21 +97,31 @@ When editing a vault or variable file using `ansible-vars`, you can prefix any s
 my_message: !enc this is a super secret message
 ```
 
-Encrypted variables will be displayed using this tag when editing, making it easy to view, modify, or decrypt their value.
+The variable will turn into an Ansible encryption string when saving the file:
+
+```yaml
+my_message: !vault |-
+  $ANSIBLE_VAULT;1.2;AES256;someid
+  333533...
+```
+
+Encrypted variables will be displayed using this tag when editing, making it easy to view, modify, or decrypt their value on the fly.
 
 ### Vault secrets
 
 **TL;DR:** Run `ansible-vars` from your Ansible home to auto-detect configured secrets. Add a custom secret using `-k <identifier> <passphrase>`.
 
-To use any functions of `ansible-vars` that require encrypting or decrypting data, you need to provide one or multiple vault secret(s). If you're in an Ansible home directory when running the command, it tries to auto-detect configured vault secrets by calling the Ansible CLI API. You can also specify your own secrets as pairs of identifier and passphrase using `--add-key|-k <identifier> <passphrase>`. The identifier can be anything you want, although it should ideally be unique. Consider using an environment variable or in-line command to retrieve the passphrase from a secure location.
+To use any functions of `ansible-vars` that require encrypting or decrypting data, you need to provide one or multiple vault secret(s). If you're in an Ansible home directory when running the command, it tries to auto-detect configured vault secrets by calling the Ansible CLI API, which looks for a `vault_identity_list` in the Ansible configuration. You can also specify your own secrets as pairs of identifier and passphrase using `--add-key|-k <identifier> <passphrase>`. The identifier can be anything you want, although it should ideally be unique. Consider using an environment variable or in-line command to retrieve the passphrase from a secure location.
 
 By default, the first loaded key is used for all encryption tasks. Note that auto-detected keys are inserted into the application's keyring *after* your explicitly added ones, so the first key you add will usually be the encryption key. If you want to make sure a certain key is used, reference its identifier using `--encryption-key|-K <identifier>`.
 
 You can disable automatic key detection by flagging `--no-detect-keys|-D`. Use `ansible-vars keyring` to view all available keys.
 
+You can customize the configuration file used for key detection via `--detection-source` or the environment. When a configuration file path is given, the file will be searched for a `vault_identity_list` and the corresponding secrets get loaded. When a directory path is given, `ansible-vars` will look for an `ansible.cfg` in that directory and perform the same loading procedure on that file. When left unset, Ansible checks if a configuration file path is set via its standard environment variable, and otherwise uses the current working directory for auto-detection. Note that setting Ansible's `DEFAULT_VAULT_IDENTITY_LIST` environment variable will override this behavior.
+
 #### Encryption salts
 
-Each time you edit a vault or otherwise encrypt a value, a randomly generated salt is used so even identical plain values will result in unique ciphers. However, this also means that each time a single encrypted variable is edited, all other ciphers in the vault will change as well. You can avoid this by passing a fixed salt via `--fixed-salt|-S <salt>` or the environment. Note that it should be at least 32 characters long and sufficiently random for Ansible's AES-256 encryption, and that you won't benefit from unique ciphers for identical plaintexts anymore.
+Each time you edit a vault or otherwise encrypt a value, a randomly generated salt is used to avoid identical plain values resulting in identical ciphers. One side-effect of this is that each time a single encrypted variable is edited, all other ciphers in the vault will change as well, possibly making changelogs (e.g. from git) less useful. You can avoid this by passing a fixed salt via `--fixed-salt|-S <salt>` or the environment. Note that it should be at least 32 characters long and sufficiently random for Ansible's AES-256 encryption, and that you won't benefit from unique ciphers for identical plaintexts anymore.
 
 ### Diff logging
 
@@ -213,9 +227,15 @@ Creates, updates, or deletes a key-value pair from a vault or variable file. Whe
 
 ### Environment variables
 
-#### ANSIBLE_HOME
+#### AV_SECRETS_ROOT (or ANSIBLE_HOME)
+
+If this variable is set to a file or directory path, the program will use its value to auto-detect configured vault secrets if detection is not disabled via `--no-detect-keys|-D`. When a configuration file path is given, the file will be searched for a `vault_identity_list` and the corresponding secrets get loaded. When a directory path is given, `ansible-vars` will look for an `ansible.cfg` in that directory and perform the same loading procedure on that file. Note that setting Ansible's `DEFAULT_VAULT_IDENTITY_LIST` environment variable will skip this step entirely.
+
+When running the script from somewhere else, this way vault secrets will be resolved as if you were in this directory or using this configuration file. When left unset, Ansible checks if a configuration file path is set via its standard environment variable, and otherwise uses the current working directory for auto-detection. It is equivalent to setting the `--detection-source` flag.
+
+#### AV_RESOLVER_ROOT
 
-If this variable is set, the program will use its value as the working directory. When running the script from somewhere else, this way keys will be detected and paths will be resolved as if you were in your Ansible root directory.
+If this variable is set, the program will use its value as the working directory. When running the script from somewhere else, this way paths will be resolved as if you were in this directory.
 
 #### AV_COLOR_MODE
 

ansible_vars-1.0.14.dist-info/RECORD

@@ -0,0 +1,12 @@
+ansible_vars/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ansible_vars/cli.py,sha256=0RScnMrG__L5mXu_OmEgxB3x4lTJ1lAyowlOJvQNcrE,66476
+ansible_vars/constants.py,sha256=VNr78qbzdJ0Vn0psbzjjQngNG3VbHhk6NXTz30VNUno,1622
+ansible_vars/errors.py,sha256=6dzyksPKWira9O2-Ir3MIOwr4XjN9MSBiRp5e6siY6Q,1256
+ansible_vars/util.py,sha256=UwGPBT19pee7lBpWuBzLPAvcrHUBAn6i1MrJvzM9OQ4,21265
+ansible_vars/vault.py,sha256=aGTU_GmJLw0QGjBQiNlRE_E-rRMEVVbwdr8IV2U2duk,47011
+ansible_vars/vault_crypt.py,sha256=58CECQrjHSKubUGL38TLuYF9h8KmO2e70swRgkS-Rn0,11870
+ansible_vars-1.0.14.dist-info/METADATA,sha256=iGS5L6S7IQF8agJHlDDvL5NvAv3eFcjbBhS9XtkIogA,21050
+ansible_vars-1.0.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ansible_vars-1.0.14.dist-info/entry_points.txt,sha256=RrhkEH0MbfRzflguVrfYfthsFC5V2fkFnizUG3uHMtQ,55
+ansible_vars-1.0.14.dist-info/licenses/LICENSE,sha256=ocyJHLG5wD12qB4uam2pqWTHIJmzloiyNyTex6Q2DKo,1062
+ansible_vars-1.0.14.dist-info/RECORD,,

ansible_vars-1.0.12.dist-info/RECORD

@@ -1,12 +0,0 @@
-ansible_vars/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ansible_vars/cli.py,sha256=u9kuZN304BQ5NGd8-dWnogmxXlnWl0_eD9iLcQEvbdQ,65917
-ansible_vars/constants.py,sha256=VNr78qbzdJ0Vn0psbzjjQngNG3VbHhk6NXTz30VNUno,1622
-ansible_vars/errors.py,sha256=6dzyksPKWira9O2-Ir3MIOwr4XjN9MSBiRp5e6siY6Q,1256
-ansible_vars/util.py,sha256=UwGPBT19pee7lBpWuBzLPAvcrHUBAn6i1MrJvzM9OQ4,21265
-ansible_vars/vault.py,sha256=ZrlUIjSBKQPjQg5NqbpfTzkhca7x-tvMrH9gFn1g2xE,46947
-ansible_vars/vault_crypt.py,sha256=nh2k686nTI3yERIp-qzx5iDE1kZKg10YG019QeZDnLM,10019
-ansible_vars-1.0.12.dist-info/METADATA,sha256=6Qy4OTNpY28l6B4AaUok0Fv_SSzvImMcVmyy1ScjyGU,18830
-ansible_vars-1.0.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ansible_vars-1.0.12.dist-info/entry_points.txt,sha256=RrhkEH0MbfRzflguVrfYfthsFC5V2fkFnizUG3uHMtQ,55
-ansible_vars-1.0.12.dist-info/licenses/LICENSE,sha256=ocyJHLG5wD12qB4uam2pqWTHIJmzloiyNyTex6Q2DKo,1062
-ansible_vars-1.0.12.dist-info/RECORD,,