Create ESAPI user guide for ESAPI Encoder

[kwwall]

We either need a separate ESAPI Encoder User Guide or a suitable wiki page (either on the GitHub repo or the OWASP wiki) or a GitHub 'Gist' to document how to use the ESAPI Encoder in various scenarios. The documentation should be aimed at beginners and should start with an introduction to XSS rather than assuming that developers understand it. While it can refer to other OWASP documentation (such as the Cheat Sheet series) for detailed references, we should try to avoid a lot of "link hoping".

If should focus on encoders used for XSS defense, but at the end, touch on the other encoders and when they are appropriate to use as well.

Since the Java Encoder project shares similar interfaces with ESAPI for output encoding, we should explore a collaborative effort together with that project and maybe the Cheat Sheet series projects as well.

NOTE: The motivation for this comes from Chamila Wijayarathna and Nalin A. G. Arachchilage for their authorship and subsequent extensive discussion of their paper "Fighting Against XSS Attacks: A Usability Evaluation of OWASP ESAPI Output Encoding". One thing noted in that paper his how participants in that study struggled to understand the big picture and how to apply the appropriate encoder and they thought a user guide for the ESAPI Encoder would be useful.

[noloader]

@kwwall,

I can help with this task if you like. We are in the process of the "developer training" thing.

Currently I'm taking my knowledge, combining it with Manico's slides and producing documents for $dayjob.

I'm happy to provide something that is world consumable.

I can also show you how to build books using DocBook, if you are interested. I've found DocBooks are much better than Word docs or OpenOffice docs because DocBooks source is XML. It is all text based, and you only need Notepad to write the material.

One of the benefits of DocBooks is, you can easily change output devices. So instead of building a PDF, you can export to a web page or mediawiki article.

---

Here's an example of a DocBook manual from one of my projects: POWER8-crypto. The make-book.sh does the heavy lifting. The steps to setup DocBook are located in the same repo: docbook.pdf.

[xeno6696]

This is a wonderful idea.

I would like to help, but I don't want to slow anybody down either. I need materials like this to bring in house at my new $job

[kwwall]

I'm in. That's been on my TODO list for a while, but I never can seem to find the time because of other more pressing ESAPI issues, like people not reading release notes and then complaining about ESAPI logging not working, etc.

Heck, I'd even relearn LaTeX to get someone to help on this. (But I draw the line at troff. :)

-kevin

On Thu, Jul 21, 2022, 2:50 PM Matt Seil @.***> wrote:

This is a wonderful idea.

I would like to help, but I don't want to slow anybody down either. I need materials like this to bring in house at my new $job

— Reply to this email directly, view it on GitHub https://github.com/ESAPI/esapi-java-legacy/issues/563#issuecomment-1191823191, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAO6PG3HDNAIEWYSO3IF4PTVVGLXHANCNFSM4PIB5COQ . You are receiving this because you were mentioned.Message ID: @.***>

[planetlevel]

Not sure if this has anything that might help. But it was a first attempt at a user guide from many years ago. https://owasp.org/www-pdf-archive/ESAPI_Book.pdf

—Jeff

---

From: Matt Seil @.> Sent: Thursday, July 21, 2022 2:50 PM To: ESAPI/esapi-java-legacy @.> Cc: Subscribed @.***> Subject: Re: [ESAPI/esapi-java-legacy] Create ESAPI user guide for ESAPI Encoder (#563)

This is a wonderful idea.

I would like to help, but I don't want to slow anybody down either. I need materials like this to bring in house at my new $job

— Reply to this email directly, view it on GitHubhttps://github.com/ESAPI/esapi-java-legacy/issues/563#issuecomment-1191823191, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAUUFTF7RYKO7X5HTGE2KFTVVGLXJANCNFSM4PIB5COQ. You are receiving this because you are subscribed to this thread.Message ID: @.***>

[kwwall]

Thanks. I don't suppose you have any editable version of this or know who has one.

-kevin

On Thu, Jul 21, 2022, 5:43 PM Jeff Williams @.***> wrote:

Not sure if this has anything that might help. But it was a first attempt at a user guide from many years ago. https://owasp.org/www-pdf-archive/ESAPI_Book.pdf

—Jeff

---

From: Matt Seil @.> Sent: Thursday, July 21, 2022 2:50 PM To: ESAPI/esapi-java-legacy @.> Cc: Subscribed @.***> Subject: Re: [ESAPI/esapi-java-legacy] Create ESAPI user guide for ESAPI Encoder (#563)

This is a wonderful idea.

I would like to help, but I don't want to slow anybody down either. I need materials like this to bring in house at my new $job

— Reply to this email directly, view it on GitHub< https://github.com/ESAPI/esapi-java-legacy/issues/563#issuecomment-1191823191>, or unsubscribe< https://github.com/notifications/unsubscribe-auth/AAUUFTF7RYKO7X5HTGE2KFTVVGLXJANCNFSM4PIB5COQ

. You are receiving this because you are subscribed to this thread.Message ID: @.***>

— Reply to this email directly, view it on GitHub https://github.com/ESAPI/esapi-java-legacy/issues/563#issuecomment-1191963665, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAO6PGY2OTAGDJOIFHEBWNDVVG773ANCNFSM4PIB5COQ . You are receiving this because you were mentioned.Message ID: @.***>