Skip to content

Commit 634e24a

Browse files
committed
Document web application vulnerability scanning procedure (#7021)
1 parent fcdeda5 commit 634e24a

File tree

1 file changed

+97
-0
lines changed

1 file changed

+97
-0
lines changed

OPERATOR.rst

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -665,6 +665,103 @@ one branch (see ``deployments/*.browser/environment.py``) and it will always use
665665
the tarball from the most recent pipeline on that branch.
666666

667667

668+
Running a ZAP vulnerability scan
669+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
670+
671+
ZAP Setup
672+
"""""""""
673+
674+
- Download ZAP from https://www.zaproxy.org/
675+
676+
- Install & open ZAP
677+
678+
- From the menu, select ``Tools`` -> ``Options``:
679+
680+
- -> ``Network`` -> ``Rate Limit``, add a 3 request per second rule for both
681+
``anvilprod.org`` and ``humancellatlas.org``.
682+
683+
- -> ``Check for Updates``:
684+
685+
- Check for updates on startup: Checked
686+
687+
- Check for updates to the add-ons you have installed: Checked
688+
689+
Running an authenticated scan
690+
"""""""""""""""""""""""""""""
691+
692+
The process for running an authenticated scan is to first obtain an Azul
693+
authentication token, and then pass this to ZAP via an environment variable. See
694+
https://www.zaproxy.org/docs/getting-further/authentication/handling-auth-yourself/
695+
for more information.
696+
697+
- To get an authorization token from Azul:
698+
699+
- Open the Swagger UI for the appropriate (HCA or AnVIL) Azul service
700+
701+
- Click ``Authorize`` and complete the authorization
702+
703+
- Using the Swagger UI, excecute an enpoint such as ``/index/catalogs``
704+
705+
- Note the example ``curl`` command, and copy the token from the
706+
``Authorization`` header (e.g. "Bearer ya29.a0…")
707+
708+
- To set the envinroment variable and launch ZAP from the command line, open a
709+
terminal and run:
710+
711+
- ``export ZAP_AUTH_HEADER_VALUE="<TOKEN-VALUE-HERE>"``
712+
713+
- ``/Applications/ZAP.app/Contents/MacOS/ZAP.sh``
714+
715+
- Continue with the desired scan
716+
717+
Running a Portal / Browser scan
718+
"""""""""""""""""""""""""""""""
719+
720+
- From the ``Quick Start`` tab, click ``Automated Scan``
721+
722+
- URL to attack: https://anvilproject.org/
723+
724+
- Use traditional spider: Checked
725+
726+
- Use ajax spider: If modern
727+
728+
- With: Firefox Headless
729+
730+
- Click ``Attack``
731+
732+
- Wait until all scans have completed, note ``Current Status`` in the ZAP footer
733+
734+
- Generate a report (see section below)
735+
736+
Running an Azul Indexer / Service API scan
737+
""""""""""""""""""""""""""""""""""""""""""
738+
739+
In order to run an API scan you must first import the OpenAPI definition.
740+
741+
- From the menu, select ``Import`` -> ``Import an OpenAPI Definition``
742+
743+
- URL: https://service.explore.anvilproject.org/openapi.json
744+
745+
- Click "Import"
746+
747+
You may now continue with an ``Automated Scan`` as detailed above. For the URL
748+
to attack, enter the base URL of the Azul indexer or service with no additional
749+
path (e.g. https://service.explore.anvilproject.org/).
750+
751+
Generating a ZAP Report
752+
"""""""""""""""""""""""
753+
754+
- From the menu, select ``Report`` -> ``Generate Report``
755+
756+
- Template: Traditional PDF Report
757+
758+
- Report Title: (Use a format such as "AnVIL Data Portal")
759+
760+
- Report Name: (Use a format such as "2025-01-01-anvil-data-portal.pdf")
761+
762+
- Click "Generate Report"
763+
764+
668765
Troubleshooting
669766
---------------
670767

0 commit comments

Comments
 (0)