Secret (version) handling improvements

changelog/61.added.md

@@ -0,0 +1 @@
+Improved handling of KV v2 secret versions

changelog/62.added.md

@@ -0,0 +1 @@
+Added `vault_secret` state module for statefully managing secrets

docs/ref/states/index.rst

@@ -12,3 +12,4 @@ _____________
     vault
     vault_db
     vault_pki
+    vault_secret

docs/ref/states/saltext.vault.states.vault_secret.rst

@@ -0,0 +1,5 @@
+``vault_secret``
+================
+
+.. automodule:: saltext.vault.states.vault_secret
+    :members:

src/saltext/vault/modules/vault.py

@@ -18,7 +18,7 @@
 log = logging.getLogger(__name__)
 
 
-def read_secret(path, key=None, metadata=False, default=NOT_SET):
+def read_secret(path, key=None, metadata=False, default=NOT_SET, version=None):
     """
     Return the value of <key> at <path> in vault, or entire secret.
 
@@ -55,14 +55,21 @@ def read_secret(path, key=None, metadata=False, default=NOT_SET):
     default
         When the path or path/key combination is not found, an exception will
         be raised, unless a default is provided here.
+
+    version
+        The version to read. If unset, reads the latest one.
+
+        .. versionadded:: 1.2.0
     """
     if default == NOT_SET:
         default = CommandExecutionError
     if key is not None:
         metadata = False
     log.debug("Reading Vault secret for %s at %s", __grains__.get("id"), path)
     try:
-        data = vault.read_kv(path, __opts__, __context__, include_metadata=metadata)
+        data = vault.read_kv(
+            path, __opts__, __context__, include_metadata=metadata, version=version
+        )
         if key is not None:
             return data[key]
         return data
@@ -74,6 +81,38 @@ def read_secret(path, key=None, metadata=False, default=NOT_SET):
         return default
 
 
+def read_secret_meta(path):
+    """
+    .. versionadded:: 1.2.0
+
+    Return secret metadata and versions for <path>.
+    Requires KV v2.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt '*' vault.read_secret_meta salt/kv/secret
+
+    Required policy:
+
+    .. code-block:: vaultpolicy
+
+        path "<mount>/metadata/<secret>" {
+            capabilities = ["read"]
+        }
+
+    path
+        The path to the secret, including mount.
+    """
+    log.debug("Reading Vault secret metadata for %s at %s", __grains__.get("id"), path)
+    try:
+        return vault.read_kv_meta(path, __opts__, __context__)
+    except Exception as err:  # pylint: disable=broad-except
+        log.error("Failed to read secret metadata! %s: %s", type(err).__name__, err)
+        return False
+
+
 def write_secret(path, **kwargs):
     """
     Set secret dataset at <path>.
@@ -203,7 +242,7 @@ def patch_secret(path, **kwargs):
         return False
 
 
-def delete_secret(path, *args):
+def delete_secret(path, *args, **kwargs):
     """
     Delete secret at <path>. If <path> is on KV v2, the secret will be soft-deleted.
 
@@ -213,6 +252,7 @@ def delete_secret(path, *args):
 
         salt '*' vault.delete_secret "secret/my/secret"
         salt '*' vault.delete_secret "secret/my/secret" 1 2 3
+        salt '*' vault.delete_secret "secret/my/secret" all_versions=true
 
     Required policy:
 
@@ -228,64 +268,173 @@ def delete_secret(path, *args):
         }
 
         # KV v2 versions
+        # all_versions=True additionally requires the policy for vault.read_secret_meta
         path "<mount>/delete/<secret>" {
             capabilities = ["update"]
         }
 
     path
         The path to the secret, including mount.
 
+    all_versions
+        .. versionadded:: 1.2.0
+
+        Delete all versions of the secret for KV v2.
+        Can only be passed as a keyword argument.
+        Defaults to false.
+
     .. versionadded:: 1.0.0
 
         For KV v2, you can specify versions to soft-delete as supplemental
         positional arguments.
     """
+    all_versions = kwargs.pop("all_versions", False)
+    unknown_kwargs = tuple(x for x in kwargs if not x.startswith("_"))
+    if unknown_kwargs:
+        raise SaltInvocationError(f"Passed unknown keyword arguments: {' '.join(unknown_kwargs)}")
     log.debug("Deleting vault secrets for %s in %s", __grains__.get("id"), path)
     if args:
         log.debug(f"Affected versions: {' '.join(str(x) for x in args)}")
     try:
-        return vault.delete_kv(path, __opts__, __context__, versions=list(args) or None)
+        return vault.delete_kv(
+            path, __opts__, __context__, versions=list(args) or None, all_versions=all_versions
+        )
     except Exception as err:  # pylint: disable=broad-except
         log.error("Failed to delete secret! %s: %s", type(err).__name__, err)
         return False
 
 
-def destroy_secret(path, *args):
+def restore_secret(path, *versions, **kwargs):
+    """
+    .. versionadded:: 1.2.0
+
+    Restore specific versions of a secret path. Only supported on Vault KV v2.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt '*' vault.restore_secret secret/my/secret 1 2
+
+    Required policy:
+
+    .. code-block:: vaultpolicy
+
+        # all_versions=True or defaulting to the most recent version additionally
+        # requires the policy for vault.read_secret_meta
+        path "<mount>/undelete/<secret>" {
+            capabilities = ["update"]
+        }
+
+    path
+        The path to the secret, including mount.
+
+    all_versions
+        Restore all versions of the secret for KV v2.
+        Can only be passed as a keyword argument.
+        Defaults to false.
+
+    You can specify versions to restore as supplemental positional arguments.
+    If no version is specified, tries to restore the latest version, and if
+    the latest version has not been deleted, fails.
+    """
+    all_versions = kwargs.pop("all_versions", False)
+    unknown_kwargs = tuple(x for x in kwargs if not x.startswith("_"))
+    if unknown_kwargs:
+        raise SaltInvocationError(f"Passed unknown keyword arguments: {' '.join(unknown_kwargs)}")
+    log.debug("Restoring vault secrets for %s in %s", __grains__.get("id"), path)
+
+    try:
+        return vault.restore_kv(
+            path, __opts__, __context__, list(versions) or None, all_versions=all_versions
+        )
+    except vault.VaultException as err:
+        raise CommandExecutionError(f"{err.__class__.__name__}: {err}") from err
+
+
+def destroy_secret(path, *args, **kwargs):
     """
     Destroy specified secret versions at <path>. Only supported on Vault KV v2.
 
     CLI Example:
 
     .. code-block:: bash
 
+        salt '*' vault.destroy_secret "secret/my/secret"
         salt '*' vault.destroy_secret "secret/my/secret" 1 2
+        salt '*' vault.destroy_secret "secret/my/secret" all_versions=true
 
     Required policy:
 
     .. code-block:: vaultpolicy
 
+        # all_versions=True or defaulting to the most recent version additionally
+        # requires the policy for vault.read_secret_meta
         path "<mount>/destroy/<secret>" {
             capabilities = ["update"]
         }
 
     path
         The path to the secret, including mount.
 
+    all_versions
+        .. versionadded:: 1.2.0
+
+        Delete all versions of the secret for KV v2.
+        Can only be passed as a keyword argument.
+        Defaults to false.
+
     You can specify versions to destroy as supplemental positional arguments.
-    At least one is required.
+
+    .. versionchanged:: 1.2.0
+
+        If no version was specified, defaults to the most recent one.
     """
-    if not args:
-        raise SaltInvocationError("Need at least one version to destroy.")
+    all_versions = kwargs.pop("all_versions", False)
+    unknown_kwargs = tuple(x for x in kwargs if not x.startswith("_"))
+    if unknown_kwargs:
+        raise SaltInvocationError(f"Passed unknown keyword arguments: {' '.join(unknown_kwargs)}")
     log.debug("Destroying vault secrets for %s in %s", __grains__.get("id"), path)
     if args:
         log.debug(f"Affected versions: {' '.join(str(x) for x in args)}")
     try:
-        return vault.destroy_kv(path, list(args), __opts__, __context__)
+        return vault.destroy_kv(
+            path, list(args) or None, __opts__, __context__, all_versions=all_versions
+        )
     except Exception as err:  # pylint: disable=broad-except
         log.error("Failed to destroy secret! %s: %s", type(err).__name__, err)
         return False
 
 
+def wipe_secret(path):
+    """
+    .. versionadded:: 1.2.0
+
+    Remove all version history and data for the secret at <path>.
+    Requires KV v2.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt '*' vault.wipe_secret "secret/my/secret"
+
+    Required policy:
+
+    .. code-block:: vaultpolicy
+
+        path "<mount>/metadata/<secret>" {
+            capabilities = ["delete"]
+        }
+    """
+    log.debug("Wiping vault secrets for %s in %s", __grains__.get("id"), path)
+    try:
+        return vault.wipe_kv(path, __opts__, __context__)
+    except Exception as err:  # pylint: disable=broad-except
+        log.error("Failed to wipe secret! %s: %s", type(err).__name__, err)
+        return False
+
+
 def list_secrets(path, default=NOT_SET, keys_only=None):
     """
     List secret keys at <path>. The path should end with a trailing slash.

src/saltext/vault/states/vault_db.py

@@ -587,7 +587,7 @@ def creds_cached(
 
     .. note::
 
-        This function is mosly intended to associate a specific credential with
+        This function is mostly intended to associate a specific credential with
         a beacon that warns about expiry and allows to run an associated state to
         reconfigure an application with new credentials.
         See the :py:mod:`vault_lease beacon module <saltext.vault.beacons.vault_lease>`
@@ -725,7 +725,7 @@ def creds_uncached(
 
     .. note::
 
-        This function is mosly intended to remove a cached lease and its
+        This function is mostly intended to remove a cached lease and its
         beacon. See :py:func:`creds_cached` for a more detailed description.
         To remove the associated beacon together with the lease, just pass
         ``beacon: true`` as a parameter to this state.