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

Joshua.Kinard at ...3108... Joshua.Kinard at ...3108...
Mon Nov 29 20:06:07 EST 2010

Sounds good to me!  I'll look forward to the next documentation update.

-----Original Message-----
From: Joel Esler [mailto:jesler at ...402...] 
Sent: Monday, November 29, 2010 7:16 PM
To: Kinard, Joshua A
Cc: <snort-devel at lists.sourceforge.net>
Subject: Re: [Snort-devel] Issues with the Snort Manual (Patch)

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,
> 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;
> 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-, 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
>> 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
>> HTTP URL from snort-
>> - 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  No change was made pursuant to this
>> 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