ZAP Stap voor stap handleidingen (tutorials)

Zoals de naam aangeeft is ZAP een proxy, om een applicatie te testen zal het web verkeer door deze proxy moeten lopen. De installatie van ZAP zorgt dat deze proxy op de geïnstalleerde machine draait, je kan vervolgens een browser door deze proxy laten lopen.

1. Tutorial — ZAP installatie

In dit hoofdstuk wordt uitgelegd hoe je de basis van ZAP installeert en de basis functies gaat gebruiken.

Stap 1 — Installatie

Desktop GUI

• Download ZAP en start de GUI.
• Handig voor exploratief testen en het opnemen van Sequences.

Docker

docker run --rm -it   -u zap   -p 8090:8090 -p 8091:8091   -v "$PWD":/zap/wd   ghcr.io/zaproxy/zap-stable:latest sh

• Poort 8090 = proxy
• Poort 8091 = API

Stap 2 — Proxy instellen

• Gebruik de geïntegreerde browser of;
• Zet je browser (Firefox/Chromium) op http://localhost:8090.
• Bezoek de applicatie → requests verschijnen in History.
• ZAP functioneert als MITM-proxy: alle verkeer wordt zichtbaar en kan later opnieuw worden afgespeeld.
  De browser die geïntegreerde is in ZAP en standaard via de proxy loopt.

Stap 3 — Context maken

• Rechtsklik op de site in Sites → Include in Context → New Context.
• Definieer:
  • IncludePaths / ExcludePaths (regex ondersteund)
  • (Optioneel) Authentication + Users + Session Management
• Test je instellingen met de Authentication Tester.
  Hier maak je de context aan, dit is de centrale configuratie die ZAP vertelt wat er bij een applicatie hoort en hoe deze werkt.

Stap 4 — Verkennen

• Spider: ontdekt links op basis van HTML-structuur.
• Ajax Spider: gebruikt een echte browser en is geschikt voor SPA’s (React/Angular/Vue).
• OpenAPI import: laad je API-spec om endpoints in scope te krijgen.

Stap 5 — Actieve scan

• Rechtsklik op een context of node → Attack → Active Scan.
• Kies scan-policy en stel limieten in:
  • maxScanDurationInMins
  • maxRuleDurationInMins
  • threadsPerHost

Stap 6 — Rapportage

• Report → Generate Report → kies traditional-html en/of traditional-xml.

Stap 7 — Automation Plan genereren

• Open het tabblad Automation → Generate Plan → exporteer als af-plan.yaml.
• Headless uitvoeren:

zap.sh -cmd -autorun /zap/wd/af-plan.yaml

Het Automation Panel waar je gemaakte automation plans kan inzien en exporteren.

⚠️ Belangrijk: stel exit-criteria in (via exitStatus job) om te voorkomen dat scans onbeperkt draaien of CI/CD altijd slaagt.

---

2. How-to guides

A. Automation Plan met quality gate

Een compleet plan dat verkenning, scanning, rapportage en quality gates combineert:

env:
  parameters:
    base_url: "https://test.example.org"
contexts:
  - name: app
    urls: ["${base_url}"]
    includePaths: ["${base_url}.*"]

jobs:
  - type: passiveScan-config
    parameters:
      maxAlertsPerRule: 1000

  - type: activeScan-config
    parameters:
      maxScanDurationInMins: 30
      maxRuleDurationInMins: 5
      threadPerHost: 2

  - type: openapi
    parameters:
      context: app
      targetUrl: "${base_url}"
      apiUrl: "${base_url}/v3/api-docs"

  - type: spider
    parameters:
      context: app
      url: "${base_url}"
      maxDuration: 5

  - type: ajaxSpider
    parameters:
      context: app
      url: "${base_url}"
      maxDuration: 5

  - type: activeScan
    parameters:
      context: app

  - type: report
    name: html
    parameters:
      template: traditional-html
      reportDir: /zap/wd/reports
      reportTitle: "ZAP Scan"

  - type: report
    name: xml
    parameters:
      template: traditional-xml
      reportDir: /zap/wd/reports

  - type: exitStatus
    parameters:
      warnLevel: Low
      errorLevel: Medium

Runnen in Docker:

docker run --rm -t -u zap   -v "$PWD":/zap/wd   ghcr.io/zaproxy/zap-stable:latest   zap.sh -cmd -autorun /zap/wd/af-plan.yaml

---

B. Sequences opnemen (Zest)

Voor stateful flows (login, checkout, transacties) die spiders vaak missen.

1. Opnemen: Scripts → Sequences → Record Sequence. Doorloop scenario → stop → sla .zst.
2. Requests toevoegen: via Add to Script from History.
3. Variabiliseren: vervang vaste URL’s door ${base_url}.
4. Debug: voeg Action → Print toe; output zichtbaar in GUI.
5. Integreren in plan:

- type: script
  parameters:
    engine: Zest
    name: login-flow
    type: sequence
    file: "/zap/wd/sequences/login-flow.zst"

---

C. Authenticatie

• Form-based: configureer context (login URL, users, logged-in regex).
• Tokens (header/bearer): gebruik Replacer of HTTP Sender script.
• OIDC/JWT: vaak herbruikbaar, maar hou rekening met expiratie en refresh.
• SAML: tokens zijn niet herbruikbaar → elke run opnieuw ophalen (via sequence of regex Moet nog uitgewerkt worden in tutorial).

---

D. Referentie YAML-bestand

env:
  contexts:
    - name: "ICTU-Test"
      urls:
        - "http://testphp.vulnweb.com"
      includePaths:
        - "http://testphp.vulnweb.com.*"
      authentication:
        method: "form"
        parameters:
          loginUrl: "http://testphp.vulnweb.com/login.php"
          loginRequestBody: "uname={%username%}&pass={%password%}&login=login"
        verification:
          loggedInRegex: "Logout"
          loggedOutRegex: "Login"
      sessionManagement:
        method: "cookie"
      users:
        - name: "demo-user"
          credentials:
            username: "test"
            password: "test"

jobs:
  - type: passiveScan-config
    parameters:
      maxAlertsPerRule: 0

  - type: spider
    parameters:
      context: "ICTU-Test"
      user: "demo-user"
      maxDuration: 2

  - type: ajaxSpider
    parameters:
      context: "ICTU-Test"
      user: "demo-user"
      maxDuration: 2

  - type: activeScan
    parameters:
      context: "ICTU-Test"
      user: "demo-user"
      policy: "Default Policy"
      maxRuleDurationInMins: 2

  - type: report
    parameters:
      template: "traditional-html"
      reportDir: "./zap-reports"
      reportFile: "ictu-zap-report.html"

   - type: exitStatus
    parameters:
      warnLevel: Low
      errorLevel: Medium

---

3. Reference — Syntax, jobs en begrippen

Belangrijke jobs

• openapi: laadt de API-specificatie
• spider / ajaxSpider: verken endpoints
• activeScan / activeScan-config: actieve aanvalsscan
• script (Zest): sequences of custom logic
• report: output in html/xml/sarif
• exitStatus: quality gate

Variabelen

env:
  parameters:
    base_url: "https://test.example.org"
    release_name: "v1.2.3"

Gebruik als ${variabelenaam} in jobs.

Context-management

• Context in GUI ≠ Context in Automation Plan (kopie!).
• Synchroniseer handmatig of genereer plan opnieuw na wijzigingen.

---

4. Explanation — Concepten & best practices

• ZAP is geen vervanging van een pentest (penetratietest), maar biedt een shift-left security check op een draaiende (runtime) applicatie..
• Proxy-model: inzicht in al het verkeer; History is fantastisch voor het bouwen van flows.
• Passive vs Active scan: passief = observeren, actief = muteren en aanvallen.
• Sequences: onmisbaar voor flows met login of state.
• Authenticatie: integreer altijd in context; voorkom false negatives.
• Exit-criteria: altijd tijds- en regellimieten instellen; zo blijft CI voorspelbaar.
• Rapportage: HTML voor menselijk lezen, XML/SARIF voor dashboards en quality tooling.

---

5. Troubleshooting

• Browser start niet bij opname: start Firefox handmatig; ZAP snuffelt via proxy.
• Geen output bij sequence headless: gebruik GUI Output-tab.
• Context mismatch: Automation-context ≠ GUI-context → plan opnieuw genereren.
• SAML-token faalt in CI: token elke run vernieuwen via sequence of regex.
• Regex lastig: gebruik add-on Regular Expression Tester.
• Scans lopen eindeloos: altijd maxScanDurationInMins instellen + exitStatus.

---

6. Checklist — Klaar voor CI/CD

• Context juist ingericht (auth, include/exclude)
• Variabelen consistent gebruikt (${base_url} etc.)
• Sequence (.zst) opgenomen en getest
• Scanlimieten ingesteld
• Rapporten schrijven naar reports/
• exitStatus ingesteld (fail op Medium, of anders waar nodig.)
• Rapporten geüpload als artefact