ZAP Praktische gids (how to en oplossingen)

Download en installatie

Een OS-specifieke variant van de ZAP Desktop Tool kan opgehaald worden van: https://www.zaproxy.org/download/

Voor het opstarten van de tool is een Java JRE nodig (en niet een JDK) vanaf versie 11 anders volgt de melding:

Bekende beperkingen

Naast HTTP GET, HTTP POST en HTTP PUT zijn er nog meer request methods zoals HTTP PATCH. ZAP ondersteunt dit (nog, 2025) niet.

Wanneer je PATCH in een sequence probeert te gebruiken, stopt de sequence bij de overview. Als je PATCH via een andere route probeert te implementeren, krijg je de volgende foutmelding:

java.lang.IllegalArgumentException: Method not supported: PATCH

Portabiliteit en omgevingsvariabelen

Bij het werken met ZAP Automation Plans is het belangrijk om rekening te houden met portabiliteit. Scripts die lokaal goed functioneren, kunnen in een CI/CD-omgeving onverwachte problemen opleveren. Dit komt voornamelijk doordat omgevingsvariabelen (environment variables) anders zijn ingericht op een ontwikkelmachine dan in een pipeline-omgeving.

Omgevingsvariabelen in YAML

Het ZAP Automation Framework interpreteert géén omgevingsvariabelen automatisch in YAML-velden zoals urls of includePaths. In tegenstelling tot bijvoorbeeld shellscripts of Docker Compose, wordt een waarde als ${RELEASE_NAME} door ZAP beschouwd als een letterlijke string, tenzij je deze gebruikt in:

• een Zest-script, of
• een expliciet ondersteund veld zoals env.parameters

Houd hier dus rekening mee bij het verplaatsen of hergebruiken van automation plans tussen verschillende omgevingen.

Variabelen in sequence worden niet overgenomen uit automation plan!

Dus je moet een shell script maken met envsubst

Logging in Zest-scripts

Zest-scripts bieden geen directe ondersteuning voor logging naar stdout, zeker niet in headless modus. Wil je toch logberichten gebruiken binnen een Zest-script, dan zijn er enkele alternatieve werkwijzen:

• Gebruik de ZestActionPrint om een waarde op te slaan in een variabele.
• Log deze variabele via een secundair mechanisme, zoals:
  • een custom scan rule
  • een apart script dat de uitvoer verwerkt

Let op: standaard logging vanuit Zest werkt niet zoals je wellicht gewend bent bij andere scriptingtalen. Test dit goed bij gebruik in een pipeline.

ZAP Scan in GitLab CI/CD

The ZAP scan is integrated into the GitLab CI/CD pipeline as a job in the .gitlab-ci.yml file. And does the following:

1. Runs in the "zap" stage of the pipeline.
2. Uses the zaproxy/zaproxy:stable Docker image.
3. Executes for both merge requests and the main branch.
4. Sets environment variables based on the context (merge request or main branch)
5. Performs variable replacements in the configuration files.
6. Runs the ZAP scan using the zap.sh command with the zap-scan.yaml automation plan.
7. Stores the reports as artifacts, which can be accessed from the GitLab UI.

Running the zap scan locally with the run-zap-scan.sh

The run-zap-scan.sh script is used to run ZAP scans locally.

  ./run-zap-scan.sh -r mr155

The following actions are executed

1. Creates a temporary directory structure for ZAP scan outputs
2. Sets environment variables (RELEASE_NAME, ZEST_SCRIPT, ENCODING_SCRIPT)
3. Substitutes environment variables in configuration files
4. Runs the ZAP scan using Docker with the zaproxy/zap-stable image
5. Outputs the scan results to the temporary directory

Usage

To run a ZAP scan locally:

  ./run-zap-scan.sh -r mr155

After running the script, the scan reports can be found in the ./zap-temp/reports directory.

Debugging

The script includes commented-out code for debugging purposes. To enter the ZAP container for debugging:

1. Uncomment the debugging section in the script
2. Run the script
3. You will be placed in a shell inside the ZAP container

ZAP in combinatie met Kibana

Wanneer je ZAP gebruikt voor het scannen van een applicatie in een testomgeving, is het vaak wenselijk om het ZAP-verkeer te onderscheiden van normaal verkeer. Door een specifieke User-Agent-header in te stellen in ZAP, kun je dit verkeer eenvoudig terugvinden en filteren in logsystemen zoals Kibana (op basis van bijvoorbeeld Elasticsearch-logs).

Waarom dit doen?

ZAP genereert veel verkeer en kan foutmeldingen of ongebruikelijke requests veroorzaken. Om analyses zuiver te houden en false positives in dashboards te vermijden, is het aan te raden ZAP-verkeer te taggen en uit te sluiten of juist te volgen in Kibana.

---

Stap 1 – Stel de User-Agent in binnen ZAP

De User-Agent kan op meerdere manieren worden ingesteld, afhankelijk van hoe je ZAP gebruikt.

Via de GUI

1. Open ZAP.
2. Ga naar Tools → Options.
3. Navigeer naar HTTP Sessions of Connection → User-Agent.
4. Voeg een custom User-Agent toe, bijvoorbeeld:

In een Automation Plan (YAML)

Je kunt ook een custom header instellen via een script of een request policy. Bijvoorbeeld via een script dat wordt opgenomen in je automation plan:

jobs:
- type: requestor
 parameters:
   requests:
     - url: "https://example.org"
       method: "GET"
       headers:
         User-Agent: "ZAP-Scanner/1.0"

Stap 2 – Filter ZAP-verkeer in Kibana

Zodra de requests zijn gelogd met deze specifieke User-Agent, kun je in Kibana eenvoudig filteren op dit verkeer om bijvoorbeeld foutanalyses of dashboards zuiver te houden.

Voorbeelden van Kibana-queries

Alle verkeer afkomstig van ZAP:

user_agent.keyword: "ZAP-Scanner/1.0"

Verkeer uitsluiten in visualisaties of zoekopdrachten:

NOT user_agent.keyword: "ZAP-Scanner/1.0"

Let op: de exacte veldnaam kan variëren, afhankelijk van de ingest pipeline of logstructuur in jouw Elasticsearch-configuratie. Veelvoorkomende velden zijn user_agent, http.user_agent of user_agent.keyword.

Best practices

• Gebruik een unieke en herkenbare User-Agent zoals ZAP-Scanner/1.0 zodat je deze eenvoudig kunt terugvinden in logs.

• Leg in je testdocumentatie of Automation Plan vast welke User-Agent wordt gebruikt.

• Filter ZAP-verkeer standaard uit in je productiedashboards om verwarring of onterechte alerts te voorkomen.

• Overweeg om aparte dashboards of waarschuwingen op te zetten voor ZAP-verkeer, zodat je gestructureerd inzicht hebt in bevindingen uit penetratietests.

• Combineer de User-Agent met andere metadata (zoals IP-adres van je CI-runner) om verkeer nog betrouwbaarder te onderscheiden.

Redirects (HTTP 303) handmatig afhandelen

In tegenstelling tot een normale webbrowser volgt ZAP een HTTP 303-redirect niet automatisch. Dit kan ertoe leiden dat een testscript stopt of faalt nadat een POST-verzoek een 303 See Other statuscode teruggeeft. Om dit gedrag te corrigeren, moet je de redirect handmatig afhandelen binnen je script of automation plan.

Oplossing: handmatig de Location-header verwerken

De HTTP 303-redirect bevat in de response-header een Location-veld met de URL waarheen het verzoek doorgestuurd moet worden. Om deze waarde te extraheren en te gebruiken in een volgend verzoek, volg je onderstaande stappen:

1. Maak een variabele aan via Edit Assignment
   Voeg in je script een Edit: Set Variable stap toe.

3. Lees de Location-header uit de response
   Gebruik de optie om een variabele te vullen met de waarde van een specifieke header.

4. Gebruik regex voor prefix en postfix
   Stel een prefix-regex in (bijvoorbeeld Location: ) en een postfix-regex (zoals een newline of einde van de regel) om alleen de URL uit de header te isoleren.

5. Gebruik de variabele in een volgend request
   Je kunt de nieuwe URL uit de Location-header vervolgens gebruiken in een opvolgend Request-object of stap binnen je Zest-script of automation plan.

Let op

• Deze aanpak vereist dat je werkt met Zest of met aangepaste scripting binnen je automation plan.

• Test dit goed, want een fout in je regex kan ertoe leiden dat je een onvolledige of ongeldige URL gebruikt.