Document web application vulnerability scanning procedure (#7021)

Author: dsotirho-ucsc

OPERATOR.rst

@@ -665,6 +665,103 @@ one branch (see ``deployments/*.browser/environment.py``) and it will always use
 the tarball from the most recent pipeline on that branch.
 
 
+Running a ZAP vulnerability scan
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ZAP Setup
+"""""""""
+
+- Download ZAP from https://www.zaproxy.org/
+
+- Install & open ZAP
+
+- From the menu, select ``Tools`` -> ``Options``:
+
+  - -> ``Network`` -> ``Rate Limit``, add a 3 request per second rule for both
+    ``anvilprod.org`` and ``humancellatlas.org``.
+
+  - -> ``Check for Updates``:
+
+    - Check for updates on startup: Checked
+
+    - Check for updates to the add-ons you have installed: Checked
+
+Running an authenticated scan
+"""""""""""""""""""""""""""""
+
+The process for running an authenticated scan is to first obtain an Azul
+authentication token, and then pass this to ZAP via an environment variable. See
+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
+
+  - 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…")
+
+- To set the envinroment variable and launch ZAP from the command line, open a
+  terminal and run:
+
+  - ``export ZAP_AUTH_HEADER_VALUE="<TOKEN-VALUE-HERE>"``
+
+  - ``/Applications/ZAP.app/Contents/MacOS/ZAP.sh``
+
+- Continue with the desired scan
+
+Running a Portal / Browser scan
+"""""""""""""""""""""""""""""""
+
+- From the ``Quick Start`` tab, click ``Automated Scan``
+
+  - URL to attack: https://anvilproject.org/
+
+  - Use traditional spider: Checked
+
+  - Use ajax spider: If modern
+
+  - With: Firefox Headless
+
+  - Click ``Attack``
+
+- Wait until all scans have completed, note ``Current Status`` in the ZAP footer
+
+- Generate a report (see section below)
+
+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``
+
+  - URL: https://service.explore.anvilproject.org/openapi.json
+
+  - Click "Import"
+
+You may now continue with an ``Automated Scan`` as detailed above. For the URL
+to attack, enter the base URL of the Azul indexer or service with no additional
+path (e.g. https://service.explore.anvilproject.org/).
+
+Generating a ZAP Report
+"""""""""""""""""""""""
+
+- From the menu, select ``Report`` -> ``Generate Report``
+
+  - Template: Traditional PDF Report
+
+  - Report Title: (Use a format such as "AnVIL Data Portal")
+
+  - Report Name: (Use a format such as "2025-01-01-anvil-data-portal.pdf")
+
+  - Click "Generate Report"
+
+
 Troubleshooting
 ---------------