Issues with the Snort Manual (Patch)

[<Joshua.Kinard () us-cert gov>]

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

Attachment: snort-manual_2.9.0.1-fixes.patch
Description: 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 () lists sourceforge net
https://lists.sourceforge.net/lists/listinfo/snort-devel