Automation Framework from the command line interface (CLI) to scan a JWT-protected API

[Mohamed Amine Khoubach]

I’m using OWASP ZAP Automation Framework from the command line interface (CLI) to scan a JWT-protected API, and I’m encountering several difficulties. I would appreciate any advice or working examples.

My setup and goals:

• Running ZAP in Docker via CLI with a YAML automation plan (plan.yaml).

• Targeting an API that uses JWT tokens for authentication.

• Automating login via a POST request to retrieve a JWT token from a JSON response.

• Injecting the JWT token as an Authorization header in all subsequent requests (spider, active scan, etc.).

• Generating a modern report after the scan completes.

What I have done:

• Created an authentication script (JavaScript) to perform login and extract/store the JWT token in session attributes.

• Created an httpSender script to inject the Authorization header on all requests using the stored token.

• Exported a ZAP context file (Authentication.context) from the GUI including the target URLs and authentication setup.

• Written a plan.yaml that references the context and defines spider, activeScan, and report jobs.

• Running the scan via CLI with Docker using a command like:

bash

CopyEdit

sudo docker run --rm --network host -v /home/heelioos:/zap/wrk/:rw zaproxy/zap-stable:latest \ zap.sh -cmd -config log.level=DEBUG -autorun /zap/wrk/plan.yaml

The problems I’m facing:

• When I try to add headers: directly under spider or activeScan jobs in the YAML, ZAP returns errors about unrecognized parameters.

• Authentication script errors: it complains about “Script type: authentication cannot be used with action: run” when I specify certain actions in YAML.

• The httpSender script does not always inject the header correctly or the token is missing from the session.

• The .context file must be created in the GUI but I’m unsure if the authentication config there is fully compatible with automation.

• Documentation and examples for JWT authentication and header injection in the CLI automation framework are limited or outdated.

• Unclear how to link the authentication script and httpSender script properly in CLI automation YAML to flow the token through scans.

What help I need:

• Working examples of plan.yaml for JWT-authenticated APIs run from CLI, with authentication and header injection correctly set up.

• Clarification on correct script types and YAML syntax to avoid “cannot be used with action: run” errors.

• Best practices for exporting and using .context files with CLI automation.

• Tips for debugging authentication and header injection scripts in CLI mode.

• Any known gotchas or recommended workflows for JWT auth with CLI Automation Framework.

Thanks a lot in advance! I’m eager to get this working smoothly and share any useful knowledge back to the community.

Best regards,

[Simon Bennetts]

Hiya,

Always try to debug problems like this in the ZAP desktop if you possibly can.

It _is_ possible to debug them via the CLI but it will be _much_ harder.

Also, go through this authentication guide first, before you try to script anything yourself: https://www.zaproxy.org/docs/authentication/

Oh, and ZAP has not been an OWASP project for nearly 2 years now :)

Cheers,

Simon

[Mohamed Amine Khoubach]

Hi Simon,

Thanks for the clarification — I wasn’t aware ZAP is no longer an OWASP project.

I’ve followed the authentication guide and tested my plan in the desktop app, where it works fine. But when I export it as a YAML and run it from the CLI, it doesn’t behave the same. Any idea what might be causing that?

Thanks,

Mohamed amine

--
ZAP by Checkmarx: https://www.zaproxy.org/
---
You received this message because you are subscribed to the Google Groups "ZAP User Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to zaproxy-user...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/zaproxy-users/5e8cc6c3-59da-42e6-9d5e-28eddb2e4032n%40googlegroups.com.

[kingthorin+zap]

>  it doesn’t behave the same.

Is terribly vague.

So we'll provide a similarly precise answer 😉 "Because" 😉

[Mohamed Amine Khoubach]

Hi,

Just to clarify, I did provide specific details in my original message — including the fact that the JWT token is retrieved via a login script, but the Authorization header is missing when the same plan is executed via the CLI (even though it works as expected in the desktop). That’s a concrete behavior difference between the two modes, not a vague statement.

If further technical detail is needed, I’m happy to provide it. But I’d appreciate responses that engage with the question rather than dismiss it. I’m here to contribute and learn — not trade sarcasm.

Thanks

[Simon Bennetts]

I'm afraid you're probably going to have to debug this :/

We can provide advice and guidance .. but we dont have access to your app.

But lets make sure we have a good understanding of the current situation.

Are these statements correct?

• You used the Authentication Tester, and this reported everything worked
• You then created an AF plan using that context
• Running that plan in the desktop works
• When you run the same plan from the CLI on the same machine it fails to speicify the Authorization header

Cheers,

Simon

[Mohamed Amine Khoubach]

Exactly this is the main issue m facing

To view this discussion visit https://groups.google.com/d/msgid/zaproxy-users/84bc825f-e352-4d7e-bda2-56c885867854n%40googlegroups.com.

[Simon Bennetts]

OK. We have a new option which may well help in this case :D

Cut you AF plan down as much as possible, ie just define the env and a single authenticated request.

Enable the "diagnostics" https://www.zaproxy.org/docs/desktop/addons/authentication-helper/browser-auth/#automation-framework

Add a report job which uses this report https://www.zaproxy.org/docs/desktop/addons/authentication-helper/auth-report-json/

Run this both in the Desktop and from the command line.

You should get 2 reports (use different names or copy them so the first doesnt get overwritten.

You'll then need to look through them to see where they differ. And significant differences as opposed to timestamps etc.

I'd start with the screenshots, which you will need to convert them in order to view them (we do plan to provide tools to make viewing these reports much easier.

Also look at the statistics - I would expect these to differ in key areas (but no idea where yet).

We want to work out where the biggest diviation happens and then work back to the cause..

Cheers,

Simon

[Mohamed Amine Khoubach]

Thanks a lot, Simon! I really appreciate your help. I’ll try out your suggested approach and will follow up once I’ve had a chance to compare the reports. Catch up soon! 

To view this discussion visit https://groups.google.com/d/msgid/zaproxy-users/4d780d5c-7c1e-44c5-affd-6ffd74eb1a8bn%40googlegroups.com.