Clarify tag syntax, recommendations

docs/admin/install.rst

@@ -392,6 +392,12 @@ If you did set up a password manager in the previous step, you may want to enabl
 
   qvm-tags vault add sd-send-app-clipboard
 
+We recommend confirming that the tag was correctly applied using the ``ls`` subcommand:
+
+.. code-block:: sh
+
+  qvm-tags vault ls
+
 To remove the permission, use:
 
 .. code-block:: sh

docs/admin/managing_clipboard.rst

@@ -5,11 +5,13 @@ Managing Clipboard Access
 
 Every VM in Qubes has its own clipboard, similar to the clipboard of a Mac, Windows or Linux computer. For example, if you wanted to create a boilerplate "Thank you" message for replies to sources, you could create a textfile in the ``sd-app`` VM and copy its contents to the SecureDrop Client using ``Ctrl+C`` (copy) and ``Ctrl+V`` (paste) keyboard shortcuts.
 
-Qubes also supports copying information *between* VMs. This is done by using `special keyboard shortcuts <https://www.qubes-os.org/doc/copy-paste/>`_, ``Ctrl+Shift+C`` and ``Ctrl+Shift+V``, in a four-step process. By default, this is disabled for all VMs that are part of SecureDrop Workstation. There are three primary reasons for this:
+Qubes also supports copying information *between* VMs. This is done by using `special keyboard shortcuts <https://www.qubes-os.org/doc/copy-paste/>`_, ``Ctrl+Shift+C`` and ``Ctrl+Shift+V``, in a four-step process. By default, this is disabled for all VMs that are part of SecureDrop Workstation, consistent with the `principle of least privilege <https://en.wikipedia.org/wiki/Principle_of_least_privilege>`__.
 
-1. It is dangerous to copy untrusted content *into* a secure environment. What looks like plain text may contain character sequences that exploit security vulnerabilities in the target environment.
-2. The four-step process described above can be difficult to follow, and it is easy to make an operational mistake, such as pasting the wrong content into a message to a source.
-3. SecureDrop Workstation aims to minimize the `attack surface <https://en.wikipedia.org/wiki/Attack_surface>`__ adversaries can target to exfiltrate information. For example, if the clipboard implementation in Qubes OS itself contained a security vulnerability, an adversary could attempt to exploit that vulnerability to shuttle a message sent by a source from the networkless ``sd-app`` VM to a networked VM.
+As an administrator, you should be aware of the following risks related to clipboard access before changing the default configuration:
+
+1. It is dangerous to copy untrusted, unsanitized content *into* a secure environment. What looks like plain text may contain character sequences that exploit security vulnerabilities in the target environment.
+2. The four-step process described above can be difficult to follow, and it is easy to make an operational mistake, such as pasting a password into a message to a source, or into a window belonging to a VM with network access.
+3. Like any other part of the operating system, the implementation of Qubes clipboard itself may contain undiscovered security vulnerabilities that an adversary could exploit in an attempt to exfiltrate information.
 
 With these considerations in mind, there are use cases where clipboard access may be an important part of your regular use of SecureDrop Workstation. For example:
 
@@ -26,28 +28,37 @@ The process for setting up a password manager and permitting the one-directional
 - the tag ``sd-send-app-clipboard`` can be used to tag a VM that should be able to send its clipboard contents *to* ``sd-app`` via the cross-VM clipboard;
 - the tag  ``sd-receive-app-clipboard`` can be used to tag a VM that should be able to receive is clipboard contents *from* ``sd-app`` via the cross-VM clipboard.
 
-You can configure these tags for a given VM by opening a terminal in ``dom0`` and issuing a command like the following:
+You can configure these tags for a given VM from the ``dom0`` terminal. Changes to tags take effect immediately, and any VM can have multiple tags.
+
+.. important::
+
+   Make sure you fully understand technical and operational security risks before permitting clipboard access to any VM. The "send" and "receive" tags are separate so you can set up only the clipboard direction you need to support a given use case.
+
+   We recommend adding a note about any changes to the clipboard configuration to your internal documentation for SecureDrop. If you are unsure how to configure the clipboard to support a specific use case, please do not hesitate to contact us for assistance.
+
+The general syntax for adding a tag is as follows, substituting ``<VM name>`` with the name of an existing VM in the system you want to grant access to the clipboard:
 
 .. code-block:: sh
 
   qvm-tags <VM name> add <tag name>
 
-So, for example, if you had a VM for the Signal messenger called ``signal`` and you wanted to copy messages *from* the SecureDrop Client *to* Signal, you would issue the following command:
+We recommend confirming that the command was successfully applied using the ``ls`` subcommand:
 
 .. code-block:: sh
 
-  qvm-tags signal add sd-receive-app-clipboard
+  qvm-tags <VM name> ls
 
 The syntax for revoking a tag is as follows:
 
 .. code-block:: sh
 
   qvm-tags <VM name> del <tag name>
 
-Changes to tags take effect immediately, and any VM can have multiple tags.
+As before, we recommend confirming the operation via the ``ls`` subcommand.
 
-.. important::
+As an example, if you had a custom VM called ``work-signal`` that runs the Signal messenger, and you wanted to copy and paste messages from the SecureDrop Client *into* Signal (and potentially other applications in that VM) but not *out* of Signal into the SecureDrop Client, you would issue the following commands:
 
-   Make sure you fully understand technical and operational security risks before permitting clipboard access to any VM. The "send" and "receive" tags are separate so you can set up only the clipboard direction you need to support a given use case.
-
-   We recommend adding a note about any changes to the clipboard configuration to your internal documentation for SecureDrop. If you are unsure how to configure the clipboard to support a specific use case, please do not hesitate to contact us for assistance.
+.. code-block:: sh
+
+  qvm-tags work-signal add sd-receive-clipboard
+  qvm-tags work-signal ls

docs/admin/reviewing_logs.rst

@@ -9,7 +9,7 @@ SecureDrop Workstation aggregates system logs from all its VMs in the ``sd-log``
 
 For this reason, the ``sd-log`` VM is networkless, and you cannot copy files from ``sd-log`` to other VMs by default.
 
-If you want to selectively enable copying logs to a single VM, you can use tags, similar to the method used for :doc:`managing clipboard access <managing_clipboard>`. You can add and remove the permission just before each copying operation; the change will take effect immediately. 
+If you want to selectively enable copying logs to a single VM, you can use tags, similar to the method used for :doc:`managing clipboard access <managing_clipboard>`. You can add and remove the permission just before each copying operation; the change will take effect immediately.
 
 .. important::
 
@@ -21,11 +21,11 @@ To enable copying logs to a target VM, you can use a command like the following
 
   qvm-tags <VM name> add sd-receive-logs
 
-We recommend verifying that the tag was successfully applied:
+We recommend verifying that the tag was successfully applied using the ``ls`` subcommand:
 
 .. code-block:: sh
 
-  qvm-tags <VM name> ls sd-receive-logs
+  qvm-tags <VM name> ls
 
 To remove the permission, use this command in ``dom0``: