[Snort-devel] Issues with the Snort Manual (Patch)

Joel Esler jesler at ...402...
Wed Nov 24 08:06:56 EST 2010


Joshua,

This is great, thank you very much.  This is exactly the collaboration with the community that I love to see.  I'll get this filed into a bug report right away.

Joel

On Nov 23, 2010, at 11:03 PM, <Joshua.Kinard at ...3108...> wrote:

> 
> Hi snort-devel,
> 
> Reading through the Snort manual, I am bothered by the large number of
> inconsistencies, spelling errors, missing option parameters, etc found
> within the manual.  Snort is a complicated piece of software.  How are
> we supposed to properly learn it if the documentation doesn't fully
> explain things or even contradicts itself at times?
> 
> I've attached a patch to the LaTeX source file from the recent release
> of snort-2.9.0.1, found in the doc/ subdir.  The patch corrects a lot of
> problems I've identified in the manual pertaining to rule options.  I
> did not review or study the other areas of the manual, but I would not
> be surprised if a lot of the minor tweaks in the rule options section
> (mostly inconsistent use of white space) also exist elsewhere.  I am
> also not able to actually build TeX files into PDF, as I lack the
> appropriate tools at present.
> 
> 
> Here's a summary of what I changed:
> 
> - Removed extraneous spaces between a rule option name and its parameter
> list.  I.e., content: "ABC"; --> content:"ABC";.  I have noticed that
> the main SourceFire product will choke when importing text files with
> rules that contain a space after the colon.  There is no guidance in the
> manual on what it accepted practice.  So, looking over VRT and ET rule
> releases, I adopted the notation that there should be no space between a
> rule option's name and its parameter list.
> 
> - Removed extraneous spaces between rule option parameters.  I.e.,
> byte_test:1, !&, 128, 0; --> byte_test:1,!&,128,0;.  Similar to the
> above, this is mostly a style change.  The common notation is no
> whitespacing between parameter options.  I have probably missed a few of
> these in other parts of the manual.
> 
> - dce_iface/dce_opnum: Re-wrote the example syntax to line up with the
> rest of the manual.
> 
> - byte_test/byte_jump in DCERPC2: Ditto.
> 
> - sd_pattern: Added missing semi-colon to the end of the syntax.
> 
> - reference: Added missing "osvdb" system ID, and updated the "mcafee"
> HTTP URL from snort-2.9.0.1.
> 
> - content modifiers depth/offset/distance/within: Added notation that
> these four options can take either a number OR a string value
> representing a variable created by the "byte_extract" option.  The lack
> of this mention could lead to confusion and I am surprised that it was
> missed when byte_extract was added.  Also used the \texttt{} operator
> instead of single quotes in the description fields on a few items.
> 
> - depth: All four of the numeric content modifiers invoke a ParseInt()
> function to convert the string value into a number.  This ParseInt
> function accepts -65,535 to 65,535 as a valid range of values.  This
> does not align with the change in depth's documentation from snort-2.9.0
> to 2.9.0.1.  No change was made pursuant to this notation.  However, I
> changed the documentation to reflect the fact that depth:0; is invalid,
> because the source code in src/detection-plugins/sp_pattern_match.c,
> lines 518 to 523, do an explicit check for depth != 0 and that depth is
> greater-than-or-equal-to the length of the pattern specified in the
> matched content option.  Therefore, it is impossible to have a depth of
> 0 because you cannot have a content with no length.
> 
> - http_encode: Removed erroneous LaTeX \hline before the row for
> "ascii".
> 
> - byte_test: Removed the '!' operator from the table detailing the
> possible operators.  I reported this once, and found it sloppy that
> while one or two edits were made to address the original issue on the
> preceding page, that the table, nor the notation at the bottom, were not
> updated.
> 
> - byte_jump: Another case of sloppiness: The example block for byte_test
> was copied to byte_jump and not changed.  So, I am certain a few people
> might've scratched their heads at the mentioning of an <operator> or
> <offset> field, neither of which applies to byte_jump.
> 
> - byte_extract: The source code does not support the mention that
> byte_extract's "offset" parameter can also hold a value.
> src/detection-plugins/sp_byte_extract.c, line 244 to line 251 backs this
> up.  So I removed the table row stating that this was possible.  If this
> IS possible, then the source code needs to be changed.
> 
> - byte_test/byte_jump/byte_extract: Re-wrote the syntax line to match
> other elements in the manual.  For byte_jump and byte_extract
> specifically, they mimic the way byte_test mentions its "<endian>" and
> "string,<number_type>" parameter..
> 
> - asn1: Listed out the options in the syntax example.  I made the
> assumption that relative_offset and absolute_offset cannot be used
> together.  Clarification on this would be appreciated.  Also added the
> missing "print" option, although, I can find NO documentation explaining
> what it is for.
> 
> - ttl: Broke the syntax example up into two pieces, as it's complex and
> reads better with two syntax examples.  Also explicitly spelled out that
> <= and >= are valid operators.
> 
> - ipopts: Added missing "lsrre" option.  Referenced CVE-1999-0909, but
> that doesn't explain much.
> 
> - dsize, icode, itype: Copied the syntax example for urilen and used it
> with these three options, as that is a more clear example.
> 
> - flags: Reserved 1 is now CWR, Congestion Window Reduced, and Reserved
> 2 is ECE, ECN-Echo.  This is per the notes on the Wikipedia page for
> TCP.  Flag values still refer to these as "1, and "2".  Also removed "0"
> from the set of allowable values for the optional 'mask' field.
> 
> - flowbits: Added missing "isnotset" to the list of parameters in the
> syntax example.  Also added the explanation for "reset" to the flowbits
> table.
> 
> - icode: The usage example erroneously referred to it as "code".  Fixed.
> 
> - stream_size: Spelled out tht != means "not equal".  It previously said
> "not".
> 
> - session: Added the missing "binary" option after reviewing the source
> code.  NO explanation for this option exists, so I assumed that it
> writes out data in some unknown binary format.  Clarification on this
> would be appreciated.
> 
> - tag: Added optional "0,packets," parameter to the syntax example.
> Used to override tagged_packet_limit.
> 
> - replace: Double quotes around the string.
> 
> - detection_filter/threshold: Shortened the syntax example to one line.
> 
> 
> Please let me know if there are any issues with any elements of this
> patch.  Also, is there a QA team in place to validate changes to the
> manual in new releases?
> 
> Thanks!,
> 
> --J
> <snort-manual_2.9.0.1-fixes.patch>------------------------------------------------------------------------------
> Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
> Tap into the largest installed PC base & get more eyes on your game by
> optimizing for Intel(R) Graphics Technology. Get started today with the
> Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs.
> http://p.sf.net/sfu/intelisp-dev2dev_______________________________________________
> Snort-devel mailing list
> Snort-devel at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/snort-devel





More information about the Snort-devel mailing list