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

Christopher Todd chris at christophertodd.com
Thu Jan 16 20:57:29 EST 2003


I think Michael makes some good points, and I like the idea of the
glossary/appendix, but I would like to suggest an alternate possibility.

As Michael points out, the Guide and the ASAC/Encyclopedia present much the
same information, just in a different way.  There's nothing wrong with that.
The Guide is an educational tool; it's purpose is to teach web developers
how to write secure web apps.  It must hold the developer's hand and walk
them through concepts and ideas they may never have dealt with before.  It
must, therefore, be more verbose and explanatory and present information at
a relatively high level.

The ASAC/Encyclopedia is a reference work, to which you can refer when, for
example, you can't quite remember which characters are important to filter
to prevent SQL injection attacks.  Sometimes you need a quick reference for
a particular fact, and don't want to go wading through voluminous writing
whose purpose is to teach.

I think both books are very important, and I think it's perfectly OK, if not
necessary, for them to contain redundant information.  They will be two ways
of presenting the same information; one educational, and one as a reference
for more experienced and knowledgeable developers.  And I think keeping them
as separate books emphasizes that they are for different audiences and
situations.  Combining them into one work could confuse the reader, and
would be less useful than if they were separate.

Just my $0.02,
Chris

> -----Original Message-----
> From: owasp-guide-admin at lists.sourceforge.net
> [mailto:owasp-guide-admin at lists.sourceforge.net]On Behalf Of Jeremy
> Poteet
> Sent: Thursday, January 16, 2003 5:44 PM
> To: owasp-guide at lists.sourceforge.net
> Subject: Re: [OWASP-GUIDE] Fwd: Here I go questioning the
> Encyclopediaagain...
>
>
> 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.
>
> Jeremy
>
>
> 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
>
>
>
> -------------------------------------------------------
> 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