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

Joel Esler jesler at ...402...
Mon Nov 29 19:15:56 EST 2010

I know some of the answers to these questions, however, I am going to enter your comments into the existing bug for clarification in the manual so that all answers are in one place.  I think that makes the most sense.

Sent from my iPhone

On Nov 29, 2010, at 6:23 PM, <Joshua.Kinard at ...3108...> wrote:

>
> Thanks for this.  Will the developers be able to provide
> guidance/comments on the following items addressed in the documentation
> patch?:
>
> - asn1: Are absolute_offset and relative_offset mutually exclusive?
>
> - asn1: What is the purpose or function of the 'print' parameter?
>
> - byte_extract: Is 'offset' supposed to be able to hold a variable name
> extracted from a previous byte_extract keyword?
>
> - session: What is the purpose or function of the 'binary' parameter?
>
> - General: Is a space after a colon in a Snort rule option the preferred
> format, or is no space preferred?  Snort parses either-or, but as I
> mentioned, the main SourceFire product has choked on instances of these
> (specifically, importing a text file with a rule whose "sid" parameter
> contains such a space).
>
> - General: Are spaces between parameters in a rule option also the
> preferred format, or are no spaces preferred?  Similar to the last
> question.  I haven't noticed SourceFire mistreating options formatted as
> such, but the possibility probably exists.
>
>
>
> I had an additional thought over the weekend, that is not addressed in
> the manual nor reflected in my patch.  The manual states that HTTP
> content modifiers for pcre (U, I, P, H, D, M, C, K, S, & Y) cannot be
> used in combination with the 'R' relative modifier (or 'B' rawbytes).
> Content, however, disallows use of the 'rawbytes' option with the HTTP
> modifiers, but speaks nothing of the two relative modifiers, 'distance'
> or 'within'.
>
> Is a rule written as such valid?:
> alert tcp $HOME_NET 1024: ->$EXTERNAL_NET 80 (msg:"Bad HTTP URI
> /foobar"; flow:established,to_server; content:"GET"; http_method;
> content:"/foobar"; http_uri; distance:0; sid:42000001; rev:1; gid:1;
> priority:2;)
>
> Since the http_* modifiers affect where the two content matches look, is
> "distance:0;" applicable on the second content to force the match to
> continue directly after the end of the first?  This wouldn't be valid in
> a pcre option (i.e., content:"GET"; http_method; pcre:"/\/foobar/RU";).
> What about when using the http_raw_* modifiers with 'distance' and
> 'within'?
>
> Lastly, are 'distance' and 'within' valid on the 'uricontent' option?
> This has never been clearly addressed it seems and has a history of
> confusing people.  It also ties in with the previous question, since
> uricontent can be rendered as a content/http_uri pair.  Granted, both of
> these questions are more suitable for discussion on snort-users, but
> since I'm looking at further modifying the documentation if I can get
> some concrete explanation on them, I'm inquiring here instead.
>
>
> Thanks!,
>
> --J
>
>
> -----Original Message-----
> From: Joel Esler [mailto:jesler at ...402...]
> Sent: Wednesday, November 24, 2010 8:07 AM
> To: Kinard, Joshua A
> Cc: snort-devel at lists.sourceforge.net
> Subject: Re: [Snort-devel] Issues with the Snort Manual (Patch)
>
> 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
>