fixup! Document web application vulnerability scanning procedure (#7021)

Author: dsotirho-ucsc

OPERATOR.rst

@@ -668,8 +668,12 @@ the tarball from the most recent pipeline on that branch.
 Running a ZAP vulnerability scan
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-ZAP Setup
-"""""""""
+Setting up ZAP
+""""""""""""""
+
+Follow these steps to set up the ZAP application for scanning of the HCA and
+AnVIL systems. After completing this set up once, you can skip this step in the
+future, and instead jump down to `Launching ZAP`_.
 
 - Download ZAP from https://www.zaproxy.org/
 
@@ -698,14 +702,14 @@ ZAP Setup
 - You may now close the ZAP application. The next time you open the application,
   the settings you set above will be used.
 
-Running an authenticated scan
-"""""""""""""""""""""""""""""
+Launching ZAP
+"""""""""""""
 
-The scans you run need be run with authenticated requests. The process for
-running an authenticated scan is to first obtain an Azul authentication token,
-and then launch the ZAP application with the token set as an environment
-variable. The token will then automatically be added as a header to all requests
-made during the scan. See the `ZAP documentation`_ for more information.
+All scans need be run with authenticated requests. The process for running an
+authenticated scan is to first obtain an Azul authentication token, and then
+launch the ZAP application with the token set as an environment variable. The
+token will then automatically be added as a header to all requests made during
+the scan. See the `ZAP documentation`_ for more information.
 
 .. _`ZAP documentation`: https://www.zaproxy.org/docs/getting-further/authentication/handling-auth-yourself/
 
@@ -727,24 +731,33 @@ made during the scan. See the `ZAP documentation`_ for more information.
 
   - ``/Applications/ZAP.app/Contents/MacOS/ZAP.sh``
 
-- After the ZAP application has opened, follow the steps below to create a new
-  session and run a scan. After your scan has completed and you have generated
-  a report, close the ZAP application, and repeat the steps above with a new
-  authentication token for each additional scan you wish to run.
+- After the ZAP application has opened, follow the steps below to `create a new
+  session`_ and run a scan. After your scan has completed and you have
+  generated a report, close the ZAP application, and repeat the steps above with
+  a new authentication token for each additional scan you wish to run.
+
+.. _`create a new session`: #zap-sessions
 
 ZAP Sessions
 """"""""""""
 
 With the ZAP application open, you must start a new session prior to running a
 new scan. Failure to do so can pollute the scan results with the findings from
-the previous scan.
+the previous scan. A new session is created each time you launch ZAP, or to
+manually open a new session, from the menu, select *File* – *New Session*.
 
 If you are prompted with options to persist the ZAP session, select the *No, I
 do not want to persis this session at this moment in time* option and click
-*Start*. You may now continue with the scan of your choice.
+*Start*.
+
+You may now continue with either a `Data Portal / Browser scan`_ or `Indexer /
+Service API scan`_.
 
-Running a Portal / Browser scan
-"""""""""""""""""""""""""""""""
+.. _`Portal / Browser scan`: #running-a-portal-browser-scan
+.. _`Indexer / Service API scan`: #running-an-azul-indexer-service-api-scan
+
+Running a Data Portal / Browser scan
+""""""""""""""""""""""""""""""""""""
 
 - From the *Quick Start* tab, click *Automated Scan*
 
@@ -765,7 +778,9 @@ Running a Portal / Browser scan
   instead, take note of the *Current Status* values in the ZAP window footer.
   Proceed when all scan counts show ``0``.
 
-- Generate a report (see section below)
+- Continue with the steps below to `generate a report`_.
+
+.. _`generate a report`: #generating-a-zap-report
 
 Running an Azul Indexer / Service API scan
 """"""""""""""""""""""""""""""""""""""""""
@@ -780,10 +795,12 @@ In order to run an API scan you must first import the OpenAPI definition.
   - Click *Import*
 
 After importing the OpenAPI definition, you may now follow the instructions
-above for running an ``Automated Scan``. When entering the URL to attack, use
+above for running an `Automated Scan`_. When entering the URL to attack, use
 the base URL of the Azul indexer or service with no additional path components
 (e.g. https://service.explore.anvilproject.org/).
 
+.. _`Automated Scan`: #running-a-data-portal-browser-scan
+
 Generating a ZAP Report
 """""""""""""""""""""""