[Owasp-leaders] Proposal for changing OWASP Documentation

johanna curiel curiel johanna.curiel at owasp.org
Mon Feb 15 22:52:14 UTC 2016


>>3) Agree how to get from 1) to 2) - maybe some small trails? Can our
community do it or do we need to wrap this into the RFP already under way?

Based on the ongoing RFP for assessments , formalising this information to
be discussed in a board meeting is the next step.
That's why I set that on the wiki page because in the next board meeting
you can add this document to the board's agenda for discussion and
participation.
This is the first step, however, I think you need to work out a more
detailed plan.

I like Glen's idea of his team proposing to manage. We need leaders to help
manage because we do not have such resources.Someone needs to be
accountable ;-)

Since the Security Framework is quite developed, I suggest to work out a
proposal with this in mind for feasibility and maintainability.

You can indeed start with a couple of projects. It will be a big rebuild of
the content, from wiki to Security Framework, divide and conquer.

   - What kind of resources will be necessary ? (Technical editors, Markup
   editor etc)
   - You can create a budget and then submit a phased plan with clear
   timelines and goals
   - Example: Pilot Project
   -

*OWASP Github project: centralise content from wiki to  Markdown format -*
*Pilot project:Transfer from Wiki to Github markdown :Code review &
Developer guidelines*


*Phases:*

   - Transfer Code Review_ raw content from wiki to mark down format  (x
      hours)
      - Transfer Developer Guide_raw content from wiki to mark down format
      (x hours)
      - Break down and verify redundant content (x hours /Who:?)
      - Technical review of content (x hours/price per hour resource)
      - Editorial review/Grammar (x hours/price per hour resource)
      - Setup Hosting Github (We have an OWASP github, check if that works
      out for this project)
         - Access/Content Managers: Glen Ten Cate + bro
         - Backup Managers: Gary Robinson( make sure you have time ;-))
      - My advice is  to set a plan where you work out project by project
   ( starting with Code review, OpenSamm, Developer Guide and work from there)
   starting with a small pilot project.

I can always help you work  out the plan, let me know if you need it.
These are just suggestions, but keeping in mind sustainability in such
initiative is important for long term success.

Cheers

Johanna




On Mon, Feb 15, 2016 at 5:36 PM, Gary Robinson <gary.robinson at owasp.org>
wrote:

> Hey All,
>
> Johanna thanks for putting the proposal wiki page together (
> https://www.owasp.org/index.php/Category:OWASP_Github_Documentation),
> I've added my name to the participant list and the Code Review Project to
> the project list.  I agree that since the responses so far are in favor of
> looking into this that we should make it into a more solid proposal.
>
> How do we make this real?  I believe we need to do three things:
> 1) Work out where were are - engage with projects who are already
> experimenting with this, see what works, and how it could encompass all
> OWASP info.
> 2) Work out where we want to be - gain a consensus of how this
> documentation framework would look like, how we bring together the various
> duplicate descriptions into one 'golden source', how projects would use it,
> etc.
> 3) Agree how to get from 1) to 2) - maybe some small trails? Can our
> community do it or do we need to wrap this into the RFP already under way?
>
> I agree with Johanna, if your interested in being part of this can you add
> your name/project to the wiki page and we can setup a mailing list, or plan
> a discussion at one of the summits.
>
> Gary
>
> On Mon, Feb 15, 2016 at 10:44 AM, Glenn Ten Cate <glenn.ten.cate at owasp.org
> > wrote:
>
>> Hi Gary,
>>
>> I really understand your pain in this topic and that's why we created the
>> SKF project. A Central place for security knowledge.
>>
>> >      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.
>>
>> This is the exact issue we tried to tackle, i'm not saying our markdown
>> files are perfect but at least we try to have it on 1 place and be the
>> authority of that information and keeping it up to date. We choose to take
>> this upon us and yes it's a lot of work but we want to offer correct
>> information.
>>
>> >      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)
>>
>> That is why we created a markdown format of all the knowledge base items
>> and the code examples so they are easily reusable for everybody. Also
>> because it's all in the Github everybody can create pull requests and they
>> will be reviewed by the SKF team.
>>
>> >      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.
>>
>> The problem with the current Wiki setup is that there is no real place of
>> authority where people can find this information. We need to have
>> one authoritative place where all the information / markdown files are
>> located and synced to the specific projects or pages in the Wiki to display
>> this information. The SKF could be this authoritative place IMHO.
>>
>> >      4. Content gets out-of-date.  The work to create a new version of a
>> >         doc project takes years.
>>
>> That's why we need 1 authoritative place where it's easy to reuse the
>> information for everybody, also when we have such a place the content will
>> be of higher quality and would evolve very fast because everybody is using
>> it and give feedback if it's not correct or can be better.
>>
>> Actionable items:
>> - We need to create an authoritative place where we will get all the
>> information from and get consensus from the OWASP community.
>> - We need to get consensus about the format being used for this central
>> place, i would say use markdown format because it's easy to integrate into
>> other projects or docs
>> - We need to create some examples scripts in a Github repository
>> how people can use the markdown files and sync or generate docs from the
>> Central place of authority
>>
>> Just my thoughts, hope it can help and improve the OWASP brand and
>> quality we want to achieve.
>>
>> Greetz,
>> Glenn
>>
>>
>>
>>
>> On Mon, Feb 15, 2016 at 11:09 AM, Steven van der Baan <
>> steven.van.der.baan at owasp.org> wrote:
>>
>>> 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
>>> >
>>> _______________________________________________
>>> OWASP-Leaders mailing list
>>> OWASP-Leaders at lists.owasp.org
>>> https://lists.owasp.org/mailman/listinfo/owasp-leaders
>>>
>>
>>
>
> _______________________________________________
> OWASP-Leaders mailing list
> OWASP-Leaders at lists.owasp.org
> https://lists.owasp.org/mailman/listinfo/owasp-leaders
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.owasp.org/pipermail/owasp-leaders/attachments/20160215/34f271a6/attachment-0001.html>


More information about the OWASP-Leaders mailing list