[Owasp-leaders] Proposal for changing OWASP Documentation

Mon Feb 15 10:09:40 UTC 2016

I'm in favour of this as well. It would simplify to cross-reference
between the documents.
I would add projects like the Security Knowledge Framework into this as
it already contains a lot of coding examples.

Cheers,
Steven.

On 15/02/16 09:52, psiinon wrote:
> I'm all for this, but there again in most cases I'd probably be
> consuming this info rather than generating it ;)
> 
> We want to concentrate on making ZAP as good as we can, not
> copy-and-pasting docs from other OWASP projects.
> Theres loads of great content I'd like to include with ZAP if it was in
> the right format.
> 
> We can (and do) link to other projects, but there are many times when
> you want deeper integration.
> A couple of ZAP examples:
> 
> When you raise an alert manually ZAP gives you a pulldown of common
> vulns, and then fills out some boilerplate info if you select one of the
> options.
> Thats all taken from WASC as I couldnt fine a good OWASP alternative:
> https://github.com/zaproxy/zaproxy/blob/develop/src/lang/vulnerabilities.xml
> 
> I'd love to include a checklist in ZAP based on the testing guide - some
> of the checks could be automatically completed when you perform some ZAP
> actions, others would need to be manually completed by the tester, but
> all could include more info (still in ZAP) explaining what the tester
> needed to do.
> This was a student project but it didnt go anywhere :(
> 
> Cheers,
> 
> Simon
> 
> On Sun, Feb 14, 2016 at 8:30 PM, Gary Robinson <gary.robinson at owasp.org
> <mailto:gary.robinson at owasp.org>> wrote:
> 
>     Hi Folks,
> 
>      
> 
>     I want to reach out to the leaders and bring up the subject of OWASP
>     docs projects, in fact all OWASP documentation including wiki and
>     text available to our code projects as well.  I’ll try to keep this
>     e-mail brief so won’t get bogged in details, but generally I want to
>     know if the community experiences the same pains, see the same
>     opportunities, or has other suggestions for improvement.
> 
>      
> 
>     The issues that can arise from our current method of developing our
>     various docs include:
> 
> 
>      1. Draft content that exists in the wiki.  This may be in varying
>         states (correct, incorrect, lousy, confused, etc.) and is
>         visible to the internet and typically not clearly labelled as
>         draft.  Google ‘owasp purple monkey dishwasher’ for an example
>         of a draft wiki page visible to the internet.  This content also
>         needs to get cleaned up after a project release.
>      2. Substandard descriptions/content can get into our docs.  Getting
>         people to review every line/example/diagram/appendix is
>         difficult with a volunteer organization (as other threads have
>         discussed)
>      3. Duplications happen, as 10 different projects create/copy/paste
>         their definitions of topics such as XSS, SQLi, CSRF, etc.  This
>         wastes effort in an organization already constrained of active
>         volunteers.
>      4. Content gets out-of-date.  The work to create a new version of a
>         doc project takes years.
> 
>     I’m sure some readers will be mentally adding their own issues to
>     this list.
> 
>      
> 
>     Proposal:
> 
> 
>     Bringing together discussions with a few people over the last few
>     years (you know who you are), I’m proposing the following: we write
>     our docs with reusable resources.  What would this mean?  Something
>     similar to the following:
> 
> 
>      1. We dump all of the content from our wiki, current docs,
>         descriptions in code tools, etc.  We put it into markup (as some
>         projects are already doing) and add it to source code repositories.
>      2. We share doc markup files _across ALL docs and code projects_. 
>         For example, imagine we have a folder for SQLi.  This directory
>         contains the OWASP ‘golden source’ for SQLi definition,
>         examples, code, tests, etc.  Repeat for all other AppSec issues
>         (CSRF, cert pinning, etc.).  We use a mechanism to ‘compile’
>         these markdown files into PDFs and integrate into code project
>         HTML pages.
>      3. Similar to good coding projects, we control who can edit the
>         files under certain directories – people we know have expertise
>         in an area.  Edits get peer reviewed before submission.  Other
>         people can suggest edits and prove their experience to the
>         existing team to join it.
>      4. We allow anyone to ‘include’ this markup file into their
>         project.  So if the Code Review Guide wants to add a section on
>         SQLi, and needs a definition, I don’t write it (or copy from
>         wiki), I simply include the relevant markup file.  Same for
>         testing guide, dev guide, ZAP hints page, security shepherd info
>         page, cheetsheet, and on and on.
>      5. We allow all of our docs, plus the wiki, plus all code projects,
>         to dynamically use an markup file update.  We make this ‘real
>         time’.  This needs an example.  Say in March a massive change
>         occurs in the world of SQLi.  Right now any project that talks
>         about SQLi would need to manually go in and update, and those
>         updates will be of varying quality and content.  If, instead,
>         one (true) source file was update, all those other projects
>         could spot the change and automatically rebuild themselves,
>         meaning the next person to download a development guide PDF, or
>         view the wiki, would get the updated SQLi information.
>          1. This is a big change.  This may be a controversial
>             change.  _However it would greatly reduce our
>             workload_ (only one markup document needs to get updated). 
>             It will also _greatly reduce review tasks_, as everyone is
>             sharing core content which is reviewed once.  It also
>             improves our image to the world, as all projects have the
>             same great descriptions and content.
>          2.   This change also improves our responsiveness.  Imagine a
>             heartbleed type issue being reflected in all OWASP code and
>             documentation projects, as well as the wiki/cheetsheets,
>             within a few days?  (simply the time for the team to agree
>             updates to the text/examples/descriptions, review, and submit)
>      6.  We should also make these markup files available to anyone on
>         the internet (read only).  This way the source descriptions
>         become an OWASP resource it itself, and anyone out there needing
>         to spread the word on AppSec has easy access to rock solid,
>         up-to-date definitions.
> 
>     This changes the model, from people like myself who run ‘projects’,
>     to smaller expert teams who know ‘technologies’ (such as SQLi or IIS
>     secure configuration).  It focuses people where they want to be on
>     docs projects, but easily shares that knowledge across all OWASP
>     (and more) projects.  It also means there’d never be another need to
>     clean-up the wiki – it would always be based off the markup content.
> 
> 
>     *Big downside*: there’s a large piece of work to start it off.  All
>     content would need to get organized, put into sensible structure,
>     converted to markdown, argued over, ‘experts’ defined and assigned,
>     etc.  I doubt this would be a volunteer effort, and may need
>     contractor involvement.  Could this be combined with the OWASP wiki
>     redesign?
> 
> 
>     So… the ask from the community, what are your thoughts? Could this
>     be a viable option to save us time on docs/descriptions and increase
>     quality?  Would there be funds to perform the initial conversion of
>     everything into markup pages?  Would there be resistance to working
>     in this new model?
> 
> 
>     Gary
> 
> 
>     _______________________________________________
>     OWASP-Leaders mailing list
>     OWASP-Leaders at lists.owasp.org <mailto:OWASP-Leaders at lists.owasp.org>
>     https://lists.owasp.org/mailman/listinfo/owasp-leaders
> 
> 
> 
> 
> -- 
> OWASP ZAP <https://www.owasp.org/index.php/ZAP> Project leader
> 
> 
> _______________________________________________
> OWASP-Leaders mailing list
> OWASP-Leaders at lists.owasp.org
> https://lists.owasp.org/mailman/listinfo/owasp-leaders
> 