[Owasp-leaders] Proposal for changing OWASP Documentation

Seba seba at owasp.org
Tue Feb 16 08:22:59 UTC 2016


hi,

I have added my name / the SAMM project.

We will discuss this during our SAMM project call tomorrow and see if/how
we can rework the current SAMM source XML / v1.1 documents to mark down
format.

As SAMM describes quite some assurance activities, there will be
overlap/links with other parts of the wiki/projects.

We should probably also think of a meta-layer of information blocks, with
pointers and authoritative sources. As there will never be ONE
authoritative source for everything. But if we have a mesh of meta-layer of
information, we can start adding attributes, such as popularity,
completeness, number of references ...

Kind regards

Seba

On Mon, Feb 15, 2016 at 11:52 PM johanna curiel curiel <
johanna.curiel at owasp.org> wrote:

> >>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/20160216/85159a7f/attachment-0001.html>


More information about the OWASP-Leaders mailing list