[Owasp-leaders] Proposal for changing OWASP Documentation
Steven van der Baan
steven.van.der.baan at owasp.org
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.
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
> Thats all taken from WASC as I couldnt fine a good OWASP alternative:
> 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 :(
> 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
> 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
> 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.
> 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
> 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?
> OWASP-Leaders mailing list
> OWASP-Leaders at lists.owasp.org <mailto:OWASP-Leaders at lists.owasp.org>
> OWASP ZAP <https://www.owasp.org/index.php/ZAP> Project leader
> OWASP-Leaders mailing list
> OWASP-Leaders at lists.owasp.org
More information about the OWASP-Leaders