Document web application vulnerability scanning procedure (#7021)

Author: dsotirho-ucsc

OPERATOR.rst

@@ -665,6 +665,143 @@ 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 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 *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.
+
+  - *Check for Updates*:
+
+    - Check the *Check for updates on startup* option
+
+    - Check the *Check for updates to the add-ons you have installed* option
+
+- 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
+"""""""""""""""""""""""""""""
+
+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.
+
+.. _`ZAP documentation`: https://www.zaproxy.org/docs/getting-further/authentication/handling-auth-yourself/
+
+- 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, execute an endpoint such as ``/index/catalogs``
+
+  - Note the example ``curl`` command, and copy the token from the
+    ``Authorization`` header option (e.g. ``Bearer ya29.a0…``)
+
+- To set the environment 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``
+
+- 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.
+
+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.
+
+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.
+
+Running a Portal / Browser scan
+"""""""""""""""""""""""""""""""
+
+- From the *Quick Start* tab, click *Automated Scan*
+
+  - Enter the desired URL (e.g. https://anvilproject.org/) in the *URL to
+    attack* field
+
+  - Check the *Use traditional spider* option
+
+  - Select *If modern* from the *Use ajax spider* option
+
+  - Select *Firefox Headless* from the *With* option
+
+  - 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 receive a notification when the scans have completed,
+  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)
+
+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*
+
+  - Enter the URL of the OpenAPI definition (e.g.
+    https://service.explore.anvilproject.org/openapi.json) in the *URL* field
+
+  - 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
+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, use the following steps to save a PDF export of the
+scan results.
+
+- From the menu, select *Report* – *Generate Report*
+
+  - Select *Traditional PDF Report* from the *Template* option
+
+  - Enter a value such as "AnVIL Data Portal" in the *Report Title* field
+
+  - Enter a value such as "2025-01-01-anvil-data-portal.pdf" in the *Report
+    Name* field
+
+  - Click *Generate Report*
+
+
 Troubleshooting
 ---------------