Note security concerns with grains for targeting

Given that Vault is used for managing secrets, it seems useful to remind
people that grains are generally minion-controlled when talking about
using them to assign policies (and consequently give access to secrets).
This is related to saltstack#43287, though only warns people of the issue, rather
than resolving it by adding (eg) Pillar-based targeting.

This change also cleans up some nearby style and formatting issues with
the docs.

Author: dehnert

salt/modules/vault.py

@@ -116,10 +116,16 @@
             .. versionchanged:: 3001
 
     policies
-        Policies that are assigned to minions when requesting a token. These can
-        either be static, eg saltstack/minions, or templated with grain values,
-        eg, ``my-policies/{grains[os]}``. ``{minion}`` is shorthand for grains[id],
-        ``saltstack/minion/{minion}``. .
+        Policies that are assigned to minions when requesting a token. These
+        can either be static, eg ``saltstack/minions``, or templated with grain
+        values, eg ``my-policies/{grains[os]}``. ``{minion}`` is shorthand for
+        ``grains[id]``, eg ``saltstack/minion/{minion}``.
+
+        .. important::
+
+            See :ref:`Is Targeting using Grain Data Secure?
+            <faq-grain-security>` for important security information. In short,
+            everything except ``grains[id]`` is minion-controlled.
 
         If a template contains a grain which evaluates to a list, it will be
         expanded into multiple policies. For example, given the template
@@ -135,16 +141,16 @@
         The minion will have the policies ``saltstack/by-role/web`` and
         ``saltstack/by-role/database``.
 
-        Optional. If policies is not configured, ``saltstack/minions`` and
-        ``saltstack/{minion}`` are used as defaults.
-
         .. note::
 
-            list members which do not have simple string representations,
+            List members which do not have simple string representations,
             such as dictionaries or objects, do not work and will
             throw an exception. Strings and numbers are examples of
             types which work well.
 
+        Optional. If policies is not configured, ``saltstack/minions`` and
+        ``saltstack/{minion}`` are used as defaults.
+
     keys
         List of keys to use to unseal vault server with the vault.unseal runner.