Scan your journey with OWASP ZAP

In plain words

OWASP ZAP is a free security tool. This page shows how to let it watch a playback for a deeper security check. It is for people comfortable with a terminal, and you can skip it if you only need the basics.

OWASP ZAP is a free, open-source security tool. StepTrails can send a replay through ZAP, so ZAP watches the real pages and calls of your recorded, signed-in journey instead of guessing. Every finding is tied to the step that caused it, for example found on step 7: Click "Pay".

This is a passive scan: ZAP only observes what the replay already does. It sends nothing extra and StepTrails puts ZAP in safe mode, which refuses to attack anything.

1. Start ZAP

You run ZAP yourself. The easiest way is Docker (replace choose-a-key with a secret of your own):

docker run -u zap -p 127.0.0.1:8080:8080 -i ghcr.io/zaproxy/zaproxy:stable zap.sh -daemon -host 0.0.0.0 -port 8080 \
  -config api.addrs.addr.name=.* -config api.addrs.addr.regex=true -config api.key=choose-a-key

127.0.0.1: in front of the port keeps ZAP reachable from your computer only.

2. Replay through it

export STEPTRAILS_ZAP_API_KEY=choose-a-key
node bin/replay.js checkout.json --zap http://127.0.0.1:8080

ZAP's findings appear with the others in the terminal, the HTML report, the JSON, SARIF and Jira bugs, with the step that triggered each one. The policy file, baseline and --fail-on apply to them too.

Good to know

• The API key goes in the setting STEPTRAILS_ZAP_API_KEY, never on the command line, and is never printed or saved. See Settings.
• HTTPS: ZAP re-signs secure traffic with its own certificate, so StepTrails tells the browser to accept it for that run only.
• Local sites work too: the browser is told to send even localhost traffic through ZAP.
• Accepting one alert: in the policy file use { "check": "zap-alert", "alert": "10021", "reason": "...", "expires": "2027-01-31" } with the ZAP alert number. See Security checks.
• Alerts ZAP marks as false positives are left out, and evidence is shortened and masked so cookies and tokens are not copied into reports.
• Use --zap on its own: it does not combine with --repeat, --proxy or --no-security, and it needs a running ZAP.
• This is not a penetration test. Automated tools find a useful subset, and each finding should be checked before it is acted on.