Merge pull request #39 from lkubb/pillar-workings-security

docs/topics/basic_configuration.md

@@ -30,13 +30,20 @@ It is highly recommended that you have a general understanding of the Vault
 authentication and authorization mechanisms that you intend to use with this
 extension and how this usage fits into your security model.
 
-The following are some things to consider. Using [templating](#vault-templating) with
-grains might allow minions to access Vault policies they are not supposed to.
-Consider using pillars or hard coding policies instead.
-Using approle authentication will allow the Salt Master to create roles with
-arbitrary policies. This means that the Salt Master can in the event of a compromise
-escalate it's privileges within the Vault namespace.
-This may not be a problem if the Salt Master manages the Vault server already.
+The following is a non-exhaustive list of points to consider:
+
+* Using [templating](#vault-templating) with grains might allow minions to access Vault policies
+  they are not supposed to since they control the content themselves. Consider using
+  pillars or hard coding policies instead.
+* In general, minions should never be allowed to mutate their own pillar, otherwise
+  the pillar's trustworthiness degrades to the level of grains. Specifically, if you
+  employ the Vault pillar module, a minion must not have write access to its pillar's
+  source path.
+* Using AppRole authentication allows the Salt Master to create roles with arbitrary
+  policies. A compromised Salt Master can thus escalate its privileges within the
+  Vault namespace. In the present, this [cannot be worked around with parameter constraints](https://github.com/hashicorp/vault/issues/8789#issuecomment-1321983227)
+  in a sensible way. This may not be a problem if the Salt Master manages the Vault
+  server already or if it is dedicated to Salt.
 
 ## Prerequisites
 

docs/topics/templating.md

@@ -22,18 +22,26 @@ Generally available template variables are:
     : The minion's pillar value with the key `<var>`.
 
       :::{important}
-      Make sure to only reference pillars that are not sourced from Vault since
-      the latter ones might be unavailable during rendering. If you use
-      the Vault integration in one of your pillar `sls` files, all values from
-      that file will be absent during rendering, even the ones that do not
-      depend on Vault.
+      Pillar values sourced from Vault should never be referenced here:
+
+      * In the general case, they will be undefined to prevent circular references.
+        If you use the Vault integration during rendering of some your regular pillar
+        `sls` files, all values from these will be undefined, even the ones that do not
+        depend on Vault. It is thus highly encouraged to avoid calling the Vault modules
+        during pillar rendering if you rely on pillar templating in this extension.
+        You can use the dedicated Vault pillar module or reference secrets during
+        **state** rendering instead, possibly in conjunction with map files
+        to avoid hardcoding Vault sources in the states themselves.
+      * In some cases, a cached pillar will be used for performance
+        reasons, which can contain Vault-sourced values. This only happens during
+        **token** (not AppRole) policy rendering and can be disabled by setting
+        {vconf}`policies:refresh_pillar <policies:refresh_pillar>` to `true`.
 
       Pillar values from previously rendered pillars can be used to template
-      [Vault Pillar](saltext.vault.pillar.vault) paths.
-
-      Using pillar values to template Vault pillar paths requires them to be defined
-      before the Vault ext_pillar is called. Especially consider the significancy
-      of the {conf_master}`ext_pillar_first <ext_pillar_first>` master config setting.
+      [Vault Pillar](saltext.vault.pillar.vault) paths. Using pillar values to template
+      Vault pillar paths requires them to be defined before the Vault ext_pillar is called.
+      Especially consider the significancy of the
+      {conf_master}`ext_pillar_first <ext_pillar_first>` master config setting.
       :::
 
 `{grains[<var>]}`
@@ -42,7 +50,7 @@ Generally available template variables are:
       :::{important}
       See {external+salt:ref}`Is Targeting using Grain Data Secure?
       <faq-grain-security>` for important security information. In short,
-      everything except `grains[id]` is minion-controlled.
+      everything except `grains[id]` is minion-controlled and should thus be avoided.
       :::
 
 ### Metadata

src/saltext/vault/pillar/vault.py

@@ -4,6 +4,10 @@
 .. important::
     This module requires the general :ref:`Vault setup <vault-setup>`.
 
+.. warning::
+    A minion must not be able to write to its own pillar source path,
+    otherwise a core security assumption in Salt is violated.
+
 .. versionchanged:: 1.0.0
     Previous versions of this pillar module found in Salt core were configured
     with a parameter named ``conf``, expecting a single value representing