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

Joel Esler jesler at ...402...
Mon Nov 29 20:22:45 EST 2010


I don't think it'll make it into 2.9.0.2, but look for it after that. 


Sent from my iPhone

On Nov 29, 2010, at 8:06 PM, <Joshua.Kinard at ...3108...> wrote:

> 
> 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,
> '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
>> 




More information about the Snort-devel mailing list