[OWASP-GUIDE] Fwd: Here I go questioning the Encyclopedia again...

Jeremy Poteet jpoteet at tech-partners.com
Thu Jan 16 17:44:11 EST 2003

I know that we often send our customers to OWASP for more information and
the ASAC section plays an important role.  I agree there is a great deal of
duplication between the two, but the Guide is intimidating as a first start.
Often we show a customer where they have a specific vulnerability and ASAC
gives them a quick, easy to read snippet of information to learn more.  When
they want to start to really learn about Application Security, the Guide is
a perfect choice.

The Encyclopedia/ASAC does allow a reader to learn a little on a specific
topic and as Michael says handles the simple question/answer.

With the current movement towards offering the Guide in other forms such as
a book, having the Guide depend on the Encyclopedia would only work if the
Encyclopedia was brought into the book as well, such as an Appendix or
Glossary.  That can be a disjointed way to read the material however, as
readers who are unfamiliar with terms may find themselves flipping back and
forth between sections of the book or between the PDF Guide and the HTML
version of the Encyclopedia.

My initial thought would be to keep both documents as they serve different
purposes.  Any research or perspectives would be good to keep in sync
between the two projects.  As far as specific wording and organization, I
feel it would be best to keep that separate.


On 1/16/03 3:34 PM, "Mark Curphey" <mark at curphey.com> wrote:

> As I mentioned in the last mail....
> Worth discussing?
> ----------
> From: Michael Schmuhl <michael at schmuhl.org>
> Date: Thu, 16 Jan 2003 12:25:54 -0700
> To: Mark Curphey <mark at curphey.com>,David Endler <dendler at owasp.org>
> Subject: Here I go questioning the Encyclopedia again...
> Ok -- I've lost track of the number of times that I've rethought this
> whole issue, and I have been pretty stoked to get a formal version of
> the Encyclopedia/ASAC out there.  Doing the work, though, I haven't been
> able to quell the gut feeling that something's still not right.
> The reason I hopped into this in the first place was because I saw the
> need for a somewhat comprehensive dictionary-type resource that someone
> could go to 1 - if they didn't understand a concept, and 2 - if they
> wanted to know what other issues/attack components there are.
> I am still convinced of this need.  The Guide is big enough that it is
> intimidating for someone who just wants a simple answer (everything2.com
> style)
> So what we've come up with is an encyclopedia whose stated purposes are:
>   1 - to create a common nomenclature
>   2 - to do _some_ teaching without being exhaustive (a la paragraph 2
>       above)
> --- break.  breathe. ---
> What's happened is that we've whittled down the entries to be presented
> to eighteen, which can hardly be considered large (read: comprehensive)
> enough to be authoritative in the web application space.  We've dropped
> entries on the premise that the subject matter wasn't particularly
> relevant for the average web app developer (even though many, like some
> cryptographic issues, file enumeration, and cookies, are covered in the
> Guide)
> While writing these entries, I've felt terribly redundant.  What good is
> an encyclopedia when there is better treatment of the subject matter
> in the Guide?
> Well, the idea was that the encyclopedia would be the definitive
> resource to (surprise!) define terms and the issues surrounding them.
> The Guide, VulnXML, and others would then use the common nomenclature
> established in the encyclopedia, and, presumably, - not - define,
> describe, etc., the issues inline, but rather refer to the encyclopedia.
> All well and good.  Thinking on the ramifications.  The above conceded,
> a great deal of content should be *removed* from the Guide and placed in
> the encyclopedia.  This lessens the value of the Guide as a standalone
> work.  In fact, it makes it impossible for it to be a standalone work,
> as it would always depend on the encyclopedia for explanations,
> definitions, and background of *every* term.  The Guide would presume an
> understanding of the encyclopedia up front.  Not being able to give
> context to any term (that's the job of the encyclopedia!), a reader of
> the Guide would be completely lost without the context given in a
> separate document (the encyclopedia).
> That's not right.  That's not how the Guide is supposed to work.  (the
> way I see things...)
> --- break.  breathe. ---
> Ok, let's be analytical about it:
> Information       Guide  Encyclopedia
> -----------       -----  ------------
> name                X         X
> other names         X         X
> definition          X         X
> exposition          X         X
> exploitations       X         X
> examples            X         X
> incidents                     X
> other discussions   X         X
> Ah.  _That's_ why I felt the encyclopedia was redundant.
> So, unless we remove a bunch from the Guide, the encyclopedia is
> redundant and unnecessary.  So why do it?
> Well, the initial need (see waaaay back to the top of this message)
> still exists.
> --- end background ---
> So what I'm thinking is merge the encyclopedia and the Guide.  perhaps
> add a glossary or an appendix - maybe just an index.
> Give the Guide all the information it needs to be the authoritative work
> it is and should be.  Visit all relevant webappsec terms and make sure
> they are represented in the Guide.  Make sure that, besides being
> represented, all are fully discussed (reference above table).
> ALSO, provide a mechanism within it for ready reference; a comprehensive
> list of issues, terms, attack components.
> So, here's a solicitation for thoughts.  Am I off base here?  Should I
> shut up and finish the last few encyclopedia entries so we can launch
> it?  Or should I (and this is what seems right about now) slap myself
> with a walleye until my exfoliated cheeks start to ooze?
> I just want this to be done right.  Being able to be a troublemaker at
> the same time is simply a bonus.
> -------------------------------------------------------
> This SF.NET email is sponsored by: Thawte.com
> Understand how to protect your customers personal information by implementing
> SSL on your Apache Web Server. Click here to get our FREE Thawte Apache
> Guide: http://ads.sourceforge.net/cgi-bin/redirect.pl?thaw0029en
> _______________________________________________
> Owasp-guide mailing list
> Owasp-guide at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/owasp-guide

More information about the Owasp-guide mailing list