ansible-vars 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

ansible_vars/cli.py

@@ -4,7 +4,7 @@
 # CLI entry point for ansible-vars
 
 # Standard library imports
-import os, re, json, atexit, signal
+import sys, os, re, json, atexit, signal
 from glob import glob
 from time import sleep
 from enum import StrEnum
@@ -12,7 +12,7 @@ from pathlib import Path
 from shutil import rmtree
 from builtins import print as std_print
 from subprocess import run as sys_command
-from tempfile import NamedTemporaryFile, mkdtemp
+from tempfile import NamedTemporaryFile, gettempdir
 from typing import Iterator, Type, Hashable, Callable, Any
 from argparse import ArgumentParser, RawDescriptionHelpFormatter
 
@@ -51,6 +51,7 @@ ansible-vars --add-key my_key '<passphrase>' --add-key other_key '<passphrase>'
 # Check if a string value is encrypted (no keys need to be loaded for this)
 ansible-vars is-encrypted string '<value>'
 # Recursively search the directory `./host_vars` of vault files for decrypted text matches on a regex pattern
+# `h:` is a shorthand for `./host_vars`, see tips section below for more information about advanced path resolution
 ansible-vars grep '# TODO' h:
 # Get the diff of two vaults
 ansible-vars diff my_vault.yml.old my_vault.yml
@@ -123,7 +124,7 @@ Encrypt a string and return it or fully encrypt a file in-place. This uses the c
 Decrypt a string and return it or fully decrypt a file in-place. Uses the first matching one of the loaded keys.
 ''',
     'cmd_is_enc': '''
-Check if a string or file is vault-encrypted. Works without any loaded keys.
+Check if a string or file is (fully) vault-encrypted.
 ''',
     'cmd_convert': '''
 Switch a file between full outer and full inner encryption for convenient migrating between encryption schemes.
@@ -189,6 +190,9 @@ 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')
+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' ]
 
 args: ArgumentParser = ArgumentParser(
     prog = 'ansible-vars',
@@ -201,7 +205,7 @@ args: ArgumentParser = ArgumentParser(
 def _prefixed_path_completer(prefix: str, **_) -> list[str]:
     has_prefix: bool = len(prefix) > 1 and prefix[:2] in ( 'h:', 'g:', 'v:' )
     resolved_prefix: str | None = { 'h:': 'host_vars', 'g:': 'group_vars', 'v:': 'vars' }[prefix[:2]] if has_prefix else None
-    if resolved_prefix and os.path.isdir(os.path.abspath(resolved_prefix + 'x')):
+    if resolved_prefix and os.path.isdir(os.path.abspath(resolved_prefix)):
         # Replace prefix with actual path
         path_prefix: str = prefix[:3] if (len(prefix) > 2 and prefix[2] == os.path.sep) else prefix[:2]
         new_prefix: str = os.path.join(resolved_prefix, prefix[len(path_prefix):])
@@ -218,7 +222,14 @@ def _prefixed_path_completer(prefix: str, **_) -> list[str]:
 # Base args
 
 args.add_argument('--debug', '-d', action='store_true', help='print debug information')
-args.add_argument('--color-mode', '-C', type=str, choices=['none', 'basic', '256', 'truecolor'], default='256', help='set terminal color capability (default: 256)')
+args.add_argument(
+    '--color-mode', '-C', type=str, choices=['none', 'basic', '256', 'truecolor'], default=DEFAULT_COLOR_MODE,
+    help=f"set terminal color capability (default: { DEFAULT_COLOR_MODE })"
+)
+args.add_argument(
+    '--temp-dir', '-T', type=str, metavar='<path>', default=DEFAULT_TEMP_DIR,
+    help=f"use this directory for vault staging instead of the system\'s TMP directory (default: { DEFAULT_TEMP_DIR })"
+)
 
 key_args = args.add_argument_group('vault key management', description=HELP['key_args'])
 # This arg can be repeated (results in [ [id, passphrase], ... ])
@@ -232,7 +243,7 @@ log_args = args.add_argument_group('logging vault changes', description=HELP['lo
 log_mutex = log_args.add_mutually_exclusive_group()
 log_mutex.add_argument('--log', '-l', type=str, metavar='<log path>', help='log to an encrypted logfile (uses the encryption key)')
 log_mutex.add_argument('--log-plain', '-L', type=str, metavar='<log path>', help='log to a plain logfile (dangerous!)')
-log_args.add_argument('--logging-key', type=str, metavar='<identifier>', help='use this loaded key for logging instead of the encryption key')
+log_args.add_argument('--logging-key', '-Q', type=str, metavar='<identifier>', help='use this loaded key for logging instead of the encryption key')
 
 # Commands
 commands = args.add_subparsers(dest='command', metavar='<command>', required=True)
@@ -244,7 +255,11 @@ cmd_keyring.add_argument('--keys-only', '-o', action='store_false', dest='show_p
 cmd_create = commands.add_parser('create', help='create a new vault', description=HELP['cmd_create'])
 cmd_create.add_argument('vault_path', type=str, metavar='<vault path>', help='path to create a new vault at') \
     .completer = _prefixed_path_completer # type: ignore
-cmd_create.add_argument('--plain', '-p', action='store_false', dest='encrypt_vault', help='create without full file encryption')
+# Invert flag if the user wants plain mode by default
+if DEFAULT_CREATE_PLAIN:
+    cmd_create.add_argument('--no-plain', '-P', action='store_true', dest='encrypt_vault', help='create with full file encryption')
+else:
+    cmd_create.add_argument('--plain', '-p', action='store_false', dest='encrypt_vault', help='create without full file encryption')
 cmd_create.add_argument('--make-parents', '-m', action='store_true', help='create all directories in the given path')
 cmd_mutex = cmd_create.add_mutually_exclusive_group()
 cmd_mutex.add_argument('--no-edit', '-n', action='store_false', dest='open_edit_mode', help='just create the file, don\'t open it for editing')
@@ -318,8 +333,8 @@ cmd_changes.add_argument('new_vault', type=str, metavar='<new vault vault path>'
     .completer = _prefixed_path_completer # type: ignore
 cmd_changes.add_argument('--json', '-j', action='store_true', dest='as_json', help='print added/changed/removed/decrypted vars as JSON and nothing else')
 
-cmd_daemon = commands.add_parser('file-daemon', help='create a folder and sync decrypted vaults to it', description=HELP['cmd_daemon'])
-cmd_daemon.add_argument('target_root', type=str, metavar='<target root path>', help='root path the decrypted files and folders should be synced into') \
+cmd_daemon = commands.add_parser('file-daemon', help='sync decrypted vault copies into a folder', description=HELP['cmd_daemon'])
+cmd_daemon.add_argument('target_root', type=str, metavar='<target root path>', help='root folder the decrypted files and folders should be synced into (non-existent or empty)') \
     .completer = _prefixed_path_completer # type: ignore
 # This arg can be repeated (results in [ [source, rel_target], ... ])
 cmd_daemon.add_argument(
@@ -328,14 +343,16 @@ cmd_daemon.add_argument(
 ).completer = _prefixed_path_completer # type: ignore
 cmd_daemon.add_argument('--no-recurse', '-n', action='store_false', dest='recurse', help='don\'t recurse into source folders\' subfolders')
 cmd_daemon.add_argument('--no-default-dirs', '-N', action='store_false', dest='include_default_dirs', help='don\'t include default sync sources')
-cmd_daemon.add_argument('--force', '-f', action='store_true', help='if the target root already exists, delete it')
+cmd_daemon.add_argument('--force', '-f', action='store_true', help='if the target root already exists and is not empty, delete its contents')
 
 cmd_get = commands.add_parser('get', help='get a key\'s (decrypted) value if it exists', description=HELP['cmd_get'])
 cmd_get.add_argument('vault_path', type=str, metavar='<vault path>', help='path of vault to get value from') \
     .completer = _prefixed_path_completer # type: ignore
 cmd_get.add_argument('key_segments', type=str, nargs='+', metavar='<key segment> [<key segment> ...]', help='segment(s) of the key to look up (`[<num>]` for numbers)')
 cmd_get.add_argument('--no-decrypt', '-n', action='store_false', dest='decrypt_value', help='don\'t decrypt the value if it is encrypted')
-cmd_get.add_argument('--json', '-j', action='store_true', dest='as_json', help='print only value as JSON and set the rc to 0 if the key exists or 100 if it doesn\'t')
+get_mutex_format = cmd_get.add_mutually_exclusive_group()
+get_mutex_format.add_argument('--quiet', '-q', action='store_true', help='only output the raw YAML value or set the rc to 100 if the key doesn\'t exist')
+get_mutex_format.add_argument('--json', '-j', action='store_true', dest='as_json', help='print the value as JSON or set the rc to 100 if the key doesn\'t exist')
 
 cmd_set = commands.add_parser('set', help='update a key\'s value or add a new key (experimental!)', description=HELP['cmd_set'])
 cmd_set.add_argument('vault_path', type=str, metavar='<vault path>', help='path of vault to set value in') \
@@ -483,6 +500,15 @@ def resolve_vault_path(search_path: str, create_mode: bool = False, allow_dirs:
 
 ## CLI logic
 
+# Print all exceptions unless we're in debug mode
+def _exc_hook(exctype, value, traceback) -> None:
+    if config.debug:
+        sys.__excepthook__(exctype, value, traceback)
+    else:
+        print(f"{ value.__class__.__name__ }: { value }", Color.BAD)
+        print('Use --debug to get the full stacktrace')
+sys.excepthook = _exc_hook
+
 # Load vault keys
 
 _explicit_keys: list[VaultKey] = [ VaultKey(passphrase, vault_id=id) for id, passphrase in config.keys ]
@@ -556,7 +582,7 @@ if config.command in [ 'create', 'edit' ]:
     if getattr(config, 'open_edit_mode', True):
         print(f"Editing vault at { vault_path }")
         # Create a secure temporary file to host the editable content
-        with NamedTemporaryFile(mode='w+', prefix='vault_', suffix='.yml') as edit_file:
+        with NamedTemporaryFile(mode='w+', dir=config.temp_dir, prefix='vault_', suffix='.yml') as edit_file:
             # Write vault contents to temp file
             editable: str = vault.as_editable()
             edit_file.write(editable)
@@ -586,6 +612,17 @@ if config.command in [ 'create', 'edit' ]:
                     if (changes := new_vault.changes(vault))[0]:
                         print(f"\n[!] The following vars have been decrypted in this edit:", Color.MEH)
                         print('\n'.join([ f"- { format_key_path(path) }" for path in changes[0] ]))
+                    # Inform about new plain leaf variables
+                    new_plain_leaves: list[tuple[Hashable, ...]] = []
+                    def _find_new_plain_vars(path: tuple[Hashable, ...], value: Any) -> Any:
+                        if path != ( SENTINEL_KEY, ) and type(value) is not EncryptedVar:
+                            if vault.get(path, default=Unset) is Unset:
+                                new_plain_leaves.append(path)
+                        return value
+                    vault._transform_leaves(new_vault._data, _find_new_plain_vars, tuple())
+                    if new_plain_leaves:
+                        print(f"\n[!] The following plain vars have been added in this edit:", Color.MEH)
+                        print('\n'.join([ f"- { format_key_path(path) }" for path in new_plain_leaves ]))
                     # Log changes
                     if log_enabled:
                         logger.add_log_entry(vault, new_vault, comment=f"{ config.command } command via CLI")
@@ -654,7 +691,7 @@ if config.command in [ 'encrypt', 'decrypt', 'is-encrypted' ]:
             if config.quiet:
                 exit(0 if vault.full_encryption else 100)
             else:
-                print(f"Vault is { 'encrypted' if vault.full_encryption else 'plain' }.", Color.GOOD if vault.full_encryption else Color.MEH)
+                print(f"Vault is { 'encrypted' if vault.full_encryption else 'plain or hybrid' }.", Color.GOOD if vault.full_encryption else Color.MEH)
     # String target
     else:
         is_encrypted: bool = VaultKey.is_encrypted(config.target)
@@ -866,11 +903,15 @@ if config.command in [ 'diff', 'changes' ]:
 
 if config.command == 'file-daemon':
     target_path: str = os.path.abspath(config.target_root)
-    if os.path.exists(target_path):
+    if os.path.isfile(target_path) or (os.path.isdir(target_path) and os.listdir(target_path)):
         if config.force:
-            rmtree(target_path, ignore_errors=True)
+            for child in map(lambda c: os.path.join(target_path, c), os.listdir(target_path)):
+                if os.path.isfile(child):
+                    os.unlink(child)
+                else:
+                    rmtree(child, ignore_errors=True)
         else:
-            raise FileExistsError(f"Cannot mount sync root to { target_path } as the path already exist")
+            raise FileExistsError(f"Cannot create sync root at { target_path } as the path already exist and is not empty")
     # Resolve sources
     if config.include_default_dirs:
         for dir_path in ( 'host_vars', 'group_vars', 'vars' ):
@@ -886,14 +927,22 @@ if config.command == 'file-daemon':
         for _path, _target in sources:
             if _target == subtarget and _path != path:
                 raise ValueError(f"Sources may not have the same target subpath, found identical target for { _path } and { path }")
-    # Create target dir
-    _target_tmp_path = mkdtemp()
-    os.rename(_target_tmp_path, target_path)
+    # Create target dir and record if we had to create it for later cleanup
+    already_existed: bool = os.path.isdir(target_path)
+    os.makedirs(target_path, mode=0o700, exist_ok=True)
     # Cleanup handler
-    def _cleanup_daemons(daemons) -> None:
+    def _cleanup_daemons(daemons, delete_root) -> None:
         print('\nStopping file daemons and cleaning up files...')
         [ daemon.stop(delete=False) for daemon in daemons ] # type: ignore
-        rmtree(target_path, ignore_errors=True)
+        # Only delete the root directory if we created it ourselves
+        if delete_root:
+            rmtree(target_path, ignore_errors=True)
+        else:
+            for child in map(lambda c: os.path.join(target_path, c), os.listdir(target_path)):
+                if os.path.isfile(child):
+                    os.unlink(child)
+                else:
+                    rmtree(child, ignore_errors=True)
         print('Goodbye.')
     # Create daemons
     def _error_callback(daemon: VaultDaemon, operation: str, err: Exception) -> None:
@@ -905,13 +954,13 @@ if config.command == 'file-daemon':
         VaultDaemon(path, target, keyring, recurse=config.recurse, error_callback=_error_callback, debug_out=_debug_out)
         for path, target in sources
     ]
-    atexit.register(_cleanup_daemons, daemons=daemons)
+    atexit.register(_cleanup_daemons, daemons=daemons, delete_root=(not already_existed))
     # Extra interrupt handler to silence error
     signal.signal(signal.SIGINT, lambda *_: exit(0))
     # Start file daemons
     [ daemon.start(stop_on_exit=False) for daemon in daemons ]
-    print(f"{ len(daemons) } file daemons are running.", Color.GOOD)
-    print('Interrupt the program to stop them and delete the target directory.')
+    print(f"{ len(daemons) } file daemon(s) running.", Color.GOOD)
+    print('Interrupt the program to stop and delete the target directory.')
     # Idle
     try:
         while True:
@@ -932,10 +981,11 @@ if config.command in [ 'get', 'set', 'del' ]:
             value = value.cipher
         if type(value) is ProtoEncryptedVar:
             value = value.plaintext
+        # Early abort
+        if (config.as_json or config.quiet) and value is Unset:
+            exit(100)
         # Output JSON
         if config.as_json:
-            if value is Unset:
-                exit(100)
             # Custom decoder for encrypted vars
             def _decode_vars(obj) -> Any:
                 if type(obj) is EncryptedVar:
@@ -945,7 +995,11 @@ if config.command in [ 'get', 'set', 'del' ]:
                 raise TypeError(f"{ type(obj) } cannot be serialized into JSON")
             json_code: str = json.dumps(value, default=_decode_vars, indent=2)
             print_json(json_code)
-        # Output text
+        # Output nothing but the raw YAML
+        elif config.quiet:
+            yaml_code: str = vault._dump_to_str(value).strip('\n') if isinstance(value, dict | list | tuple) else str(value)
+            print_yaml(yaml_code)
+        # Output text with extra messages
         else:
             print(f"Key: { format_key_path(key) }")
             if value is Unset:

{ansible_vars-1.0.1.dist-info → ansible_vars-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ansible-vars
-Version: 1.0.1
+Version: 1.0.3
 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
@@ -172,7 +172,7 @@ Shows the amounts of encrypted and decrypted variables in a vault file. Supports
 
 #### encrypt, decrypt, is-encrypted
 
-En-/Decrypts or checks the encryption status of a file or string value. No loaded secrets are required for `is-encrypted`.
+En-/Decrypts or checks the encryption status of a file or string value. Note that only full file encryption is considered in file mode, a hybrid vault with individually encrypted variables will be counted as plain.
 
 #### convert
 
@@ -192,7 +192,7 @@ Compares two vaults or variable files and prints a tree structure showing differ
 
 #### file-daemon
 
-Starts a daemon which mirrors the decrypted contents of one or multiple vault or variable file(s)/directories to a target directory. By default, this includes the directories `./host_vars`, `./group_vars`, and `./vars`. Changes to the source files are reflected in the decrypted targets. Changes to the target files are ignored.
+Starts a daemon which mirrors the decrypted contents of one or multiple vault or variable file(s)/directories to a target directory. By default, this includes the directories `./host_vars`, `./group_vars`, and `./vars`. Changes to the source files are reflected in the decrypted targets. Changes to the target files are ignored. For added security, consider syncing the files to a mounted ramdisk.
 
 #### get
 
@@ -202,6 +202,20 @@ Displays the (decrypted) value of a specified key in a vault or variable file. S
 
 Creates, updates, or deletes a key-value pair from a vault or variable file. When setting a value, you may provide a YAML string which will be parsed into the corresponding objects. Note that these are experimental features, as the current parser has difficulty preserving the metadata for programmatic variable changes. Comments and Jinja2 blocks between the affected key and the next key in the file may be lost.
 
+### Environment variables
+
+#### AV_COLOR_MODE
+
+Set the color mode as you would with `-C <mode>`.
+
+#### AV_TEMP_DIR
+
+Set the tempfile/staging root as you would with `-T <path>`.
+
+#### AV_CREATE_PLAIN
+
+Invert the default creation mode for files: If unset or `no`, files are created with full encryption unless specified otherwise via the `--plain|-p` flag. This behavior mirrors that of `ansible-vault`. When set to `yes`, the behavior and flag are inverted as files are created without encryption by default unless specified otherwise via the `--no-plain|-P` flag.
+
 ### Python library
 
 When using `ansible-vars` as a library, import any of these modules from the `ansible_vars` module.
@@ -230,6 +244,10 @@ The `VaultDaemon` syncs changes from a source file or directory to a target usin
 
 Custom types and exceptions, and static values. Mostly useful for type hints.
 
+## Security considerations
+
+When editing a file or creating a daemon, decrypted vaults are written to disk temporarily. The temporary files can only be accessed by the current user, but could potentially be restored through data recovery methods after deletion. To mitigate this issue, consider creating an in-RAM filesystem ("ramdisk") and using it as the staging directory (`--temp-dir <path>`) or the daemon target.
+
 ## Known issues and limitations
 
 - YAML round-trip parser

{ansible_vars-1.0.1.dist-info → ansible_vars-1.0.3.dist-info}/RECORD

@@ -1,12 +1,12 @@
 ansible_vars/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ansible_vars/cli.py,sha256=HZLvlwyTMQubwMubjT0eLgsZ1clXBKWS-YH5uCjPwSE,55401
+ansible_vars/cli.py,sha256=-DJ8aEV4Sr1XAelntQ-NHRCfr1rxd6o5hqG5VYFeHns,58744
 ansible_vars/constants.py,sha256=Nd3sIuSoOvyfUfHfnsnJBDGMW7eNzbMm1NAvEQio9hE,1624
 ansible_vars/errors.py,sha256=VnViEBMR3rIeioMj460DgdBA5S5FYiDObaDDhG2FMBs,857
 ansible_vars/util.py,sha256=BzS7n3UzaKqVZ3W78HVkJtdVCYofprqQDtU8wYH1d0Q,21325
 ansible_vars/vault.py,sha256=_dp1K5_UAFGgcg6iO4on4-L_BaJO2cHP6My3EU6enA4,45593
 ansible_vars/vault_crypt.py,sha256=JcFc6dTZ6EqhKXv_C5ofggTpBK8hWG3ZwrBrDNYcEIg,9501
-ansible_vars-1.0.1.dist-info/METADATA,sha256=DSTVVasM2MZB3uT7_tv40gbf85KVhqGCx3Uw6FDB9Vk,15717
-ansible_vars-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ansible_vars-1.0.1.dist-info/entry_points.txt,sha256=RrhkEH0MbfRzflguVrfYfthsFC5V2fkFnizUG3uHMtQ,55
-ansible_vars-1.0.1.dist-info/licenses/LICENSE,sha256=ocyJHLG5wD12qB4uam2pqWTHIJmzloiyNyTex6Q2DKo,1062
-ansible_vars-1.0.1.dist-info/RECORD,,
+ansible_vars-1.0.3.dist-info/METADATA,sha256=3vcaDPiNAm0JbRP7iWbXDaSERQQQ23KMMdZxVJJzmmU,16863
+ansible_vars-1.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ansible_vars-1.0.3.dist-info/entry_points.txt,sha256=RrhkEH0MbfRzflguVrfYfthsFC5V2fkFnizUG3uHMtQ,55
+ansible_vars-1.0.3.dist-info/licenses/LICENSE,sha256=ocyJHLG5wD12qB4uam2pqWTHIJmzloiyNyTex6Q2DKo,1062
+ansible_vars-1.0.3.dist-info/RECORD,,