Getting started guide - some ideas for improvement

[Sandra Koetter]

Hi folks,

I had a look through the getting start guide and as a newbie to ZAP I had the following thoughts:

-  the system requirements (e.g. java 8+) are in a paragraph. it might be easier and better visually  to have them either as bullet points or a table

- would be good to have bit more info about vulnerability assessments as I was wondering if that isn't part of the pen-testing and could be done  using ZAP?

- I had issues setting up the proxy stuff when i was trying to first install it. not seen a help with proxy link in the pdf but might be worthwhile adding the link to the github site where you can find it? the configuring part of the doc doesn't really give  a lot of info (but maybe thats just me)

- separate guide for starting on how to interpret test results and identify false positives?

happy to do a PR with those first  changes unless someone else has already picked up on those? 

Do we have a place where we can list changes we want to make to a document

Many thanks,

Sandra

[Simon Bennetts]

Hi Sandra,

Thanks for your thoughts.

Replies inline

On Monday, 15 July 2019 21:11:10 UTC+2, Sandra Koetter wrote:

Hi folks,

I had a look through the getting start guide and as a newbie to ZAP I had the following thoughts:

-  the system requirements (e.g. java 8+) are in a paragraph. it might be easier and better visually  to have them either as bullet points or a table

The requirements are essentially just "Java 8+", but any formatting changes that make any of the guide easier to read would be good :)

 

- would be good to have bit more info about vulnerability assessments as I was wondering if that isn't part of the pen-testing and could be done  using ZAP?

Unfortunately I dont believe theres any industry standard definitions for these terms (anyone feel free to correct me!).

I think we should make it clear that ZAP is focussed on finding vulnerabilities in Web Apps. Whether thats part of vulnerability assessments, pentesting or anything else is for others to decide?

But if you can come up with some words that covers more industry terms in a reasonable way then great!

 

- I had issues setting up the proxy stuff when i was trying to first install it. not seen a help with proxy link in the pdf but might be worthwhile adding the link to the github site where you can find it? the configuring part of the doc doesn't really give  a lot of info (but maybe thats just me)

Out of interest why did you try to set up a proxy manually?

ZAP does this automatically when launching browsers and as this makes it much easier this is the direction we are trying to encourage people to go in.

We are in the process of reorganising where the key ZAP info is, and linking to the authoritative description is always useful.

 

- separate guide for starting on how to interpret test results and identify false positives?

Yes, we need this, but I agree its probably better in another guide.

 

happy to do a PR with those first  changes unless someone else has already picked up on those? 

Please go for it :)

 

Do we have a place where we can list changes we want to make to a document

You could raise an issue: https://github.com/zaproxy/zaproxy/issues

We often create issues with checklists in the first comment - these can be checked as items are completed.

Its then also a place other people can comment about the individual changes.

Many thanks,

Simon

 

Many thanks,

Sandra

[Sandra Koetter]

Hi Simon,

- formatting of requirements: it sounded like it was more than just java so I will have a look at changing that paragraph to make it clearer what people need and what is available

-  vulnerability assessments etc....: yeh its not clear and - at least for me- it reads its more used for pen testing as we go straight into pen testing methodology. I will try to have a look if I can find something but if anyone else has a better idea that would be grand

-  I cannot remember why I tried to set it up manually. might have been that the guide I used said you should???? 

- interpreting  test results etc: I can raise an issue for this if needed?

Many thanks,

sandra

[Simon Bennetts]

- formatting of requirements: it sounded like it was more than just java so I will have a look at changing that paragraph to make it clearer what people need and what is available

+1

 

-  vulnerability assessments etc....: yeh its not clear and - at least for me- it reads its more used for pen testing as we go straight into pen testing methodology. I will try to have a look if I can find something but if anyone else has a better idea that would be grand

+1

 

-  I cannot remember why I tried to set it up manually. might have been that the guide I used said you should???? 

Ha! Would definitely be good to understand this, I think the docs should encourage people to use browser launch first

 

- interpreting  test results etc: I can raise an issue for this if needed?

Definitely - we have a 'component-Docs' label that can be used for these sort of issues.

 

cheers,

Simon

[Sandra Koetter]

Hi Simon,

I have added https://github.com/zaproxy/zaproxy/issues/5481 to the issues for the extra guide. I don't seem to be able to add labels but someone did add the components label after i raised the issue.

Will be working on the other points later in the week - and also try to figure out where I got the manual setting up of the proxy got from :D .

Ta,

Sandra

[Simon Bennetts]

Many thanks!