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

Author: dsotirho-ucsc

OPERATOR.rst

@@ -675,45 +675,45 @@ ZAP Setup
 
 - Install & open ZAP
 
-- From the popup, select ``No, I do not want to persis this session at this
-  moment in time`` and click ``Start``
+- From the popup, select the *No, I do not want to persis this session at this
+  moment in time* option and click *Start*
 
-- From the menu, select ``Edit`` -> ``ZAP Mode`` -> ``Standard Mode`` (This
-  should be the default option)
+- From the menu, select *Edit* -> *ZAP Mode* -> *Standard Mode* (This should be
+  the default option)
 
-- From the menu, select ``Tools`` -> ``Options``:
+- From the menu, select *Tools* -> *Options*:
 
-  - -> ``Network`` -> ``Rate Limit``, add and enable a 3 request per second rule
-    for the match string ``anvilprod.org``, and another rule for the match
-    string ``humancellatlas.org``. This is required to prevent the scans from
-    exceeding the WAF rate limits for the Azul APIs, and being temporarily
-    blocked by the wAF.
+  - *Network* -> *Rate Limit*, add and enable a 3 request per second rule for
+    the match string ``anvilprod.org``, and another rule for the match string
+    ``humancellatlas.org``. This is required to prevent the scans from exceeding
+    the WAF rate limits for the Azul APIs, and being temporarily blocked by the
+    WAF.
 
-  - -> ``Check for Updates``:
+  - *Check for Updates*:
 
-    - Check for updates on startup: Checked
+    - Check the *Check for updates on startup* option
 
-    - Check for updates to the add-ons you have installed: Checked
+    - Check the *Check for updates to the add-ons you have installed* option
 
 Running an authenticated scan
 """""""""""""""""""""""""""""
 
 The process for running an authenticated scan is to first obtain an Azul
-authentication token, and launch the ZAP application with the token set as
-an environment variable. See
-https://www.zaproxy.org/docs/getting-further/authentication/handling-auth-yourself/
+authentication token, and launch the ZAP application with the token set as an
+environment variable. See the `ZAP documentation
+<https://www.zaproxy.org/docs/getting-further/authentication/handling-auth-yourself/>`_
 for more information.
 
 - To get an authorization token from Azul:
 
   - Open the Swagger UI for the appropriate (HCA or AnVIL) Azul service
 
-  - Click ``Authorize`` and complete the authorization
+  - Click *Authorize* and complete the authorization
 
   - Using the Swagger UI, excecute an enpoint such as ``/index/catalogs``
 
   - Note the example ``curl`` command, and copy the token from the
-    ``Authorization`` header (e.g. "Bearer ya29.a0…")
+    ``Authorization`` header option (e.g. "Bearer ya29.a0…")
 
 - To set the envinroment variable and launch ZAP from the command line, open a
   terminal and run:
@@ -733,30 +733,31 @@ 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.
 
-If you are promopted to with options to persist the ZAP session, select ``No, I
-do not want to persist this session`` and click ``Start``. You may now continue
-with the scan of your choice.
+If you are promopted 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.
 
 Running a Portal / Browser scan
 """""""""""""""""""""""""""""""
 
-- From the ``Quick Start`` tab, click ``Automated Scan``
+- From the *Quick Start* tab, click *Automated Scan*
 
-  - URL to attack: https://anvilproject.org/
+  - Enter the desired URL (e.g. https://anvilproject.org/) in the *URL to
+    attack* field
 
-  - Use traditional spider: Checked
+  - Check the *Use traditional spider* option
 
-  - Use ajax spider: If modern
+  - Select *If modern* from the *Use ajax spider* option
 
-  - With: Firefox Headless
+  - Select *Firefox Headless* from the *With* option
 
-  - Click ``Attack``
+  - Click *Attack*
 
 - Wait until all the scans (Ajax spider, passive scans, etc.) have completed. In
   practice, this can take up to four hours depending on the target URL. Note
   that you will not recieve a notification when the scans have completed,
-  however you can see the ``Current Status`` in the ZAP window footer, and
-  proceed when all scan counts report ``0``.
+  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)
 
@@ -765,32 +766,34 @@ Running an Azul Indexer / Service API scan
 
 In order to run an API scan you must first import the OpenAPI definition.
 
-- From the menu, select ``Import`` -> ``Import an OpenAPI Definition``
+- From the menu, select *Import* -> *Import an OpenAPI Definition*
 
-  - URL: https://service.explore.anvilproject.org/openapi.json
+  - Enter the URL of the OpenAPI definition (e.g.
+    https://service.explore.anvilproject.org/openapi.json) in the *URL* field
 
-  - Click "Import"
+  - Click *Import*
 
-After importing the OpenAPI definitions, you may now follow the instructions
+After importing the OpenAPI definition, you may now follow the instructions
 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/).
 
 Generating a ZAP Report
 """""""""""""""""""""""
 
-After a scan has completed, you can save a PDF export of the scan results with
-the ``Generate Report`` action.
+After a scan has completed, use the following steps to save a PDF export of the
+scan results.
 
-- From the menu, select ``Report`` -> ``Generate Report``
+- From the menu, select *Report* -> *Generate Report*
 
-  - Template: Traditional PDF Report
+  - Select *Traditional PDF Report* from the *Template* option
 
-  - Report Title: (Use a format such as "AnVIL Data Portal")
+  - Enter a value such as "AnVIL Data Portal" in the *Report Title* field
 
-  - Report Name: (Use a format such as "2025-01-01-anvil-data-portal.pdf")
+  - Enter a value such as "2025-01-01-anvil-data-portal.pdf" in the *Report
+    Name* field
 
-  - Click "Generate Report"
+  - Click *Generate Report*
 
 
 Troubleshooting