From: Russ Combs Date: Mon, 31 Aug 2015 17:10:39 +0000 (-0400) Subject: fix distcheck issues X-Git-Tag: 3.0.0-233~862 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0f87d7461d6e29c8ebaafb88aca41789eda58747;p=thirdparty%2Fsnort3.git fix distcheck issues --- diff --git a/doc/default_snort_manual.html b/doc/default_snort_manual.html index a0fc7ec3a..836d5075f 100644 --- a/doc/default_snort_manual.html +++ b/doc/default_snort_manual.html @@ -781,7 +781,7 @@ asciidoc.install(2); 
 ,,_     -*> Snort++ <*-
-o"  )~   Version 3.0.0-a2 (Build 163) from 2.9.7-177
+o"  )~   Version 3.0.0-a2 (Build 167) from 2.9.7-177
  ''''    By Martin Roesch & The Snort Team
          http://snort.org/contact#team
          Copyright (C) 2014-2015 Cisco and/or its affiliates. All rights reserved.
@@ -1464,7 +1464,7 @@ To build with clang++ on OS X with gcc installed, do this first:
 

 

 
export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
-export SNORT_LUA_PATH=$my_path/etc

+export SNORT_LUA_PATH=$my_path/etc/snort

Then give it a go:

+

For more examples, see the usage section.

Tips

@@ -3177,7 +3178,7 @@ bool search_engine.inspect_stream_inserts = false: inspect reas

  • -select search_engine.search_method = ac_bnfa_q: set fast pattern algorithm - choose available search engine { ac_banded | ac_bnfa | ac_bnfa_q | ac_full | ac_full_q | ac_sparse | ac_sparse_bands | ac_std } +dynamic search_engine.search_method = ac_bnfa_q: set fast pattern algorithm - choose available search engine { ac_banded | ac_bnfa | ac_bnfa_q | ac_full | ac_full_q | ac_sparse | ac_sparse_bands | ac_std }

  • @@ -3275,7 +3276,7 @@ port snort.-j: <port> to listen for telnet connections

  • -enum snort.-k = all: <mode> checksum mode (all,noip,notcp,noudp,noicmp,none) { all|noip|notcp|noudp|noicmp|none } +enum snort.-k = all: <mode> checksum mode; default is all { all|noip|notcp|noudp|noicmp|none }

  • @@ -3335,7 +3336,7 @@ string snort.-S: <x=v> set config variable x equal to val

  • -int snort.-s = 1514: <snap> (same as --snaplen) { 68:65535 } +int snort.-s = 1514: <snap> (same as --snaplen); default is 1514 { 68:65535 }

  • @@ -3395,7 +3396,7 @@ implied snort.-y: include year in timestamp in the alert and lo

  • -int snort.-z = 1: <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system { 0: } +int snort.-z = 1: <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system; default is 1 { 0: }

  • @@ -3665,7 +3666,7 @@ string snort.--run-prefix: <pfx> prepend this to each out

  • -string snort.--script-path: <path> where to find luajit scripts +string snort.--script-path: <path> to a luajit script or directory containing luajit scripts

  • @@ -3710,6 +3711,11 @@ implied snort.--treat-drop-as-ignore: use drop, sdrop, and reje

  • +select snort.--unit-test: <verbosity> run unit tests with given libcheck output mode { silent | minimal | normal | verbose | env (export CK_VERBOSITY) } +

    +
    • +
  • +

    implied snort.--version: show version number (same as -V)

    • @@ -6163,6 +6169,16 @@ bool new_http_inspect.test_input = false: read HTTP messages fr bool new_http_inspect.test_output = false: print out HTTP section data

    +
  • +

    +int new_http_inspect.request_depth = -1: maximum request message body bytes to examine (-1 no limit) { -1: } +

    +
    • +
  • +

    +int new_http_inspect.response_depth = -1: maximum response message body bytes to examine (-1 no limit) { -1: } +

    +

    • Rules:

      @@ -6947,7 +6963,7 @@ int perf_monitor.flow_ip_memcap = 52428800: maximum memory for

    • -int perf_monitor.max_file_size = 4096: files will be rolled over if they exceed this size { 4096: } +int perf_monitor.max_file_size = 4294967295: files will be rolled over if they exceed this size { 4096: }

    • @@ -12503,6 +12519,11 @@ determine verdict. (Conversely, builtin actions don’t have an associated plugin function.)

    +

    Developers Guide

    +

    Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated guide to +the source tree.

    +
    +

    Piglet Test Harness

    In order to assist with plugin development, an experimental mode called "piglet" mode is provided. With piglet mode, you can call individual methods for a specific plugin. @@ -12514,30 +12535,25 @@ for a specific plugin.

    plugin =
 {
     type = "piglet",
-    version = 1
-}
    -
    -
    -
    -
    piglet =
-{
-    name = "my_test_for_ipv4_codec",
-    type = "codec",
-    target = "ipv4",
+    name = "codec::ipv4",
+    use_defaults = true,
     test = function()
-        local raw_data = RawData.new(1024)
+        local daq_header = DAQHeader.new()
+        local raw_buffer = RawBuffer.new("some data")
         local codec_data = CodecData.new()
         local decode_data = DecodeData.new()
    -
            codec("decode", raw_data, codec_data, decode_data)
-        return true
+
            return Codec.decode(
+            daq_header,
+            raw_buffer,
+            codec_data,
+            decode_data
+        )
     end
 }
    -

    More example tests can be found in the piglet_scripts directory. Refer to these -examples for furthur usage of Lua wrappers to snort data structures (such as Packet).

    To run snort in piglet mode, first build snort with the BUILD_PIGLET option turned on (pass the flag -DBUILD_PIGLET:BOOL=ON in cmake).

    Then, run the following command:

    @@ -12550,387 +12566,1230 @@ examples for furthur usage of Lua wrappers to snort data structures (such as Pac the results of each test script.

    -

    Developers Guide

    -

    Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated guide to -the source tree.

    -
    - - -
    -

    Coding Style

    -
    -

    All new code should try to follow these style guidelines. These are not -yet firm so feedback is welcome to get something we can live with.

    -
    -

    General

    +

    Piglet Lua API

    +

    This section documents the API that piglet exposes to Lua. +Refer to the piglet directory in the source tree for examples of usage.

    +

    Note: Because of the differences between the Lua and C++ data model and type +system, not all parameters map directly to the parameters of the underlying +C\++ member functions. Every effort has been made to keep the mappings consist, +but there are still some differences. They are documented below.

    +
    +

    Plugin Instances

    +

    For each test, piglet instantiates plugin specified in the name field of the +plugin table. The virtual methods of the instance are exposed in a table +unique to each plugin type. The name of the table is the CamelCase name of the +plugin type.

    +

    For example, codec plugins have a virtual method called decode. This method +is called like this:

    +
    +
    +
    Codec.decode(...)
    +
    +

    Codec

    • -Generally try to follow - http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml, - but there are a few differences. +Codec.get_data_link_type() → { int, int, … }

    • -Each source directory should have a dev_notes.txt file summarizing the - key points for the code in that directory. These are built into the - developers guide. +Codec.get_protocol_ids() → { int, int, … }

      • -
    -
    -
    -

    Naming

    -

    • -Use camel case for namespaces, classes, and types like WhizBangPdfChecker. +Codec.decode(DAQHeader, RawBuffer, CodecData, DecodeData) → bool

    • -Use lower case identifiers with underscore separators, e.g. some_function() - and my_var. +Codec.log(RawBuffer, uint[lyr_len])

    • -Use lower case filenames with underscores. +Codec.encode(RawBuffer, EncState, Buffer) → bool

      • -
    -
    -
    -

    Comments

    -

    • -Write comments sparingly with a mind towards future proofing. Often the - comments can be obviated with better code. Clear code is better than a - comment. +Codec.update(uint[flags_hi], uint[flags_lo], RawBuffer, uint[lyr_len] → int

    • -Function comment blocks are generally just noise that quickly becomes - obsolete. If you absolutely must comment on parameters, put each on a - separate line along with the comment. That way changing the signature - may prompt a change to the comments too. +Codec.format(bool[reverse], RawBuffer, DecodeData)

      • +
    +

    Differences:

    +

    • -Use FIXIT (not FIXTHIS or TODO or whatever) to mark things left for a - day or even just a minute. That way we can find them easily and won’t - lose track of them. +In Codec.update(), the (uint64_t) flags parameter has been split into +flags_hi and flags_lo

      • +
    +

    Inspector

    +

    • -Presently using FIXIT-X where X = P | H | M | L, indicating perf, high, - med, or low priority. For now, H, M, or L can indicate alpha 1, 2, or 3. - Perf changes fall between alpha 1 and 2. +Inspector.configure()

    • -Put the copyright(s) and license in a comment block at the top of each - source file (.h and .cc). Don’t bother with trivial scripts and make - foo. Some interesting Lua code should get a comment block too. Copy and - paste exactly from src/main.h (don’t reformat). +Inspector.tinit()

    • -Put author, description, etc. in separate comment(s) following the - license. Do not put such comments in the middle of the license foo. - Be sure to put the author line ahead of the header guard to exclude them - from the developers guide. +Inspector.tterm()

    • -Each header should have a comment immediately after the header guard to - give an overview of the file so the user knows what’s going on. +Inspector.likes(Packet)

      • -
    -
    -
    -

    Logging

    -

    • -Messages intended for the user should not look like debug messages. Eg, - the function name should not be included. +Inspector.eval(Packet)

    • -Most debug messages should just be deleted. +Inspector.clear(Packet)

    • -Don’t bang your error messages (no !). The user feels bad enough about the - problem already w/o you shouting at him. +Inspector.get_buf_from_key(string[key], Packet, RawBuffer) → bool

      • -
    -
    -
    -

    Types

    -

    • -Use logical types to make the code clearer and to help the compiler catch - problems. typedef uint16_t Port; bool foo(Port) is way better than - int foo(int port). +Inspector.get_buf_from_id(uint[id], Packet, RawBuffer) → bool

    • -Use forward declarations (e.g. struct SnortConfig;) instead of void*. +Inspector.get_buf_from_type(uint[type], Packet, RawBuffer) → bool

    • -Try not to use extern data unless absolutely necessary and then put the - extern in an appropriate header. +Inspector.get_splitter(bool[to_server]) → StreamSplitter

      • +
    +

    Differences: +* In Inspector.configure(), the SnortConfig* parameter is passed implicitly. +* the overloaded get_buf() member function has been split into three separate methods.

    +

    IpsOption

    +

    • -Use const liberally. In most cases, const char* s = "foo" should be - const char* const s = "foo". The former goes in the initialized data - section and the latter in read only data section. +IpsOption.hash() → int

    • -But use const char s[] = "foo" instead of const char* s = "foo" when - possible. The latter form allocates a pointer variable and the data - while the former allocates only the data. +IpsOption.is_relative() → bool

    • -Use static wherever possible to minimize public symbols and eliminate - unneeded relocations. +IpsOption.fp_research() → bool

    • -Declare functions virtual only in the parent class introducing the - function (not in a derived class that is overriding the function). - This makes it clear which class introduces the function. +IpsOption.get_cursor_type() → int

    • -Declare functions as override if they are intended to override a - function. This makes it possible to find derived implementations that - didn’t get updated and therefore won’t get called due a change in the - parent signature. +IpsOption.eval(Cursor, Packet) → int

    • -Use bool functions instead of int unless there is truly a need for - multiple error returns. The C-style use of zero for success and -1 for - error is less readable and often leads to messy code that either ignores - the various errors anyway or needlessly and ineffectively tries to do - something aobut them. +IpsOption.action(Packet)

    -
    -
    -

    Macros (aka defines)

    +

    IpsAction

    • -In many cases, even in C++, use #define name "value" instead of a - const char* const name = "value" because it will eliminate a symbol from - the binary. -

      -
      • -
    • -

      -Use inline functions instead of macros where possible (pretty much all - cases except where stringification is necessary). Functions offer better - typing, avoid re-expansions, and a debugger can break there. +IpsAction.exec(Packet)

      • +
    +

    Logger

    +

    • -All macros except simple const values should be wrapped in () and all - args should be wrapped in () too to avoid surprises upon expansion. - Example: +Logger.open()

      -
      -
      -
      #define SEQ_LT(a,b)  ((int)((a) - (b)) <  0)
      -

    • -Multiline macros should be blocked (i.e. inside { }) to avoid if-else type - surprises. +Logger.close()

      • -
    -
    -
    -

    Formatting

    -

    • -Indent 4 space chars … no tabs! +Logger.reset()

    • -If you need to indent many times, something could be rewritten or - restructured to make it clearer. Fewer indents is generally easier to - write, easier to read, and overall better code. +Logger.alert(Packet, string[message], Event)

    • -Braces go on the line immediately following a new scope (function - signature, if, else, loop, switch, etc. +Logger.log(Packet, string[message], Event)

      • -
    • -

      -Use consistent spacing and line breaks. Always indent 4 spaces from the - breaking line. Keep lines less than 100 chars; it greatly helps - readability. -

      +
    +

    SearchEngine

    +

    Currently, SearchEngine does not expose any methods.

    +

    SoRule

    +

    Currently, SoRule does not expose any methods.

    +
    +
    Interface Objects
    +

    Many of the plugins take C++ classes and structs as arguments. These objects +are exposed to the Lua API as Lua userdata. Exposed objects are instantiated +by calling the new method from each object’s method table.

    +

    For example, the DecodeData object can be instantiated and exposed to Lua +like this:

    -
    No:
-    calling_a_func_with_a_long_name(arg1,
-                                    arg2,
-                                    arg3);
    +
    local decode_data = DecodeData.new(...)
    +

    Each object also exposes useful methods for getting and setting member variables, +and calling the C++ methods contained in the the object. These methods can +be accessed using the : accessor syntax:

    -
    Yes:
-    calling_a_func_with_a_long_name(
-        arg1, arg2, arg3);
    +
    decode_data:set({ sp = 80, dp = 3500 })
    - -
  • -

    -Put function signature on one line, except when breaking for the arg - list: -

    +

    Since this is just syntactic sugar for passing the object as the first parameter +of the function DecodeData.set, an equivalent form is:

    -
    No:
-    inline
-    bool foo()
-    { // ...
    +
    decode_data.set(decode_data, { sp = 80, dp = 3500 })
    +

    or even:

    -
    Yes:
-    inline bool foo()
-    { // ...
    +
    DecodeData.set(decode_data, { sp = 80, dp = 3500 })
    -
    • +

    Buffer

    +

    • -Put conditional code on the line following the if so it is easy to break - on the conditional block: +Buffer.new(string[data]) → Buffer

      -
      -
      -
      No:
-    if ( test ) foo();
      -
      -
      -
      -
      Yes:
-    if ( test )
-        foo();
      -
      • -
    -
    -
    -

    Headers

    -

    • -Don’t hesitate to create a new header if it is needed. Don’t lump - unrelated stuff into an header because it is convenient. +Buffer.new(uint[length]) → Buffer

    • -Write header guards like this (leading underscores are reserved for - system stuff). In my_header.h: +Buffer.new(RawBuffer) → Buffer

      -
      -
      -
      #ifndef MY_HEADER_H
-#define MY_HEADER_H
-// ...
-#endif
      -

    • -Includes from a different directory should specify parent directory. - This makes it clear exactly what is included and avoids the primordial - soup that results from using -I this -I that -I the_other_thing … . +Buffer:allocate(uint[length]) → bool

      -
      -
      -
      // given:
-src/foo/foo.cc
-src/bar/bar.cc
-src/bar/baz.cc
      -
      -
      -
      -
      // in baz.cc
-#include "bar.h"
      -
      -
      -
      -
      // in foo.cc
-#include "bar/bar.h"
      -

    • -Includes within installed headers should specify parent directory. +Buffer:clear()

      • +
    +

    CodecData

    +

    • -Just because it is a #define doesn’t mean it goes in a header. - Everything should be scoped as tightly as possible. Shared - implementation declarations should go in a separate header from the - interface. And so on. +CodecData.new() → CodecData

    • -A .cc should include its own .h before any others (including - system headers). This ensures that the header stands on its own and can - be used by clients without include prerequisites. +CodecData.new(uint[next_prot_id]) → CodecData

    • -Include required headers, all required headers, and nothing but required - headers. Don’t just clone a bunch of headers because it is convenient. +CodecData.new(fields) → CodecData +

      +
      • +
    • +

      +CodecData:get() → fields +

      +
      • +
    • +

      +CodecData:set(fields) +

      +
      • +
    +

    fields is a table with the following contents:

    +
      +
    • +

      +next_prot_id +

      +
      • +
    • +

      +lyr_len +

      +
      • +
    • +

      +invalid_bytes +

      +
      • +
    • +

      +proto_bits +

      +
      • +
    • +

      +codec_flags +

      +
      • +
    • +

      +ip_layer_cnt +

      +
      • +
    • +

      +ip6_extension_count +

      +
      • +
    • +

      +curr_ip6_extension +

      +
      • +
    • +

      +ip6_csum_proto +

      +
      • +
    +

    Cursor

    +
      +
    • +

      +Cursor.new() → Cursor +

      +
      • +
    • +

      +Cursor.new(Packet) → Cursor +

      +
      • +
    • +

      +Cursor.new(string[data]) → Cursor +

      +
      • +
    • +

      +Cursor.new(RawBuffer) → Cursor +

      +
      • +
    • +

      +Cursor:reset() +

      +
      • +
    • +

      +Cursor:reset(Packet) +

      +
      • +
    • +

      +Cursor:reset(string[data]) +

      +
      • +
    • +

      +Cursor:reset(RawBuffer) +

      +
      • +
    +

    DAQHeader

    +
      +
    • +

      +DAQHeader.new() → DAQHeader +

      +
      • +
    • +

      +DAQHeader.new(fields) → DAQHeader +

      +
      • +
    • +

      +DAQHeader:get() → fields +

      +
      • +
    • +

      +DAQHeader:set(fields) +

      +
      • +
    +

    fields is a table with the following contents:

    +
      +
    • +

      +caplen +

      +
      • +
    • +

      +pktlen +

      +
      • +
    • +

      +ingress_index +

      +
      • +
    • +

      +egress_index +

      +
      • +
    • +

      +ingress_group +

      +
      • +
    • +

      +egress_group +

      +
      • +
    • +

      +flags +

      +
      • +
    • +

      +opaque +

      +
      • +
    +

    DecodeData

    +
      +
    • +

      +DecodeData.new() → DecodeData +

      +
      • +
    • +

      +DecodeData.new(fields) → DecodeData +

      +
      • +
    • +

      +DecodeData:reset() +

      +
      • +
    • +

      +DecodeData:get() → fields +

      +
      • +
    • +

      +DecodeData:set(fields) +

      +
      • +
    • +

      +DecodeData:set_ipv4_hdr(RawBuffer, uint[offset]) +

      +
      • +
    +

    fields is a table with the following contents:

    +
      +
    • +

      +sp +

      +
      • +
    • +

      +dp +

      +
      • +
    • +

      +decode_flags +

      +
      • +
    • +

      +type +

      +
      • +
    +

    EncState

    +
      +
    • +

      +EncState.new() → EncState +

      +
      • +
    • +

      +EncState.new(uint[flags_lo]) → EncState +

      +
      • +
    • +

      +EncState.new(uint[flags_lo], uint[flags_hi]) → EncState +

      +
      • +
    • +

      +EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto]) → EncState +

      +
      • +
    • +

      +EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto], uint[ttl]) → EncState +

      +
      • +
    • +

      +EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto], uint[ttl], uint[dsize]) → EncState +

      +
      • +
    +

    Event

    +
      +
    • +

      +Event.new() → Event +

      +
      • +
    • +

      +Event.new(fields) → Event +

      +
      • +
    • +

      +Event:get() → fields +

      +
      • +
    • +

      +Event:set(fields) +

      +
      • +
    +

    fields is a table with the following contents:

    +
      +
    • +

      +event_id +

      +
      • +
    • +

      +event_reference +

      +
      • +
    • +

      +sig_info +

      +
        +
      • +

        +generator +

        +
        • +
      • +

        +id +

        +
        • +
      • +

        +rev +

        +
        • +
      • +

        +class_id +

        +
        • +
      • +

        +priority +

        +
        • +
      • +

        +text_rule +

        +
        • +
      • +

        +num_services +

        +
        • +
      +
      • +
    +

    Flow

    +
      +
    • +

      +Flow.new() → Flow +

      +
      • +
    • +

      +Flow:reset() +

      +
      • +
    +

    Packet

    +
      +
    • +

      +Packet.new() → Packet +

      +
      • +
    • +

      +Packet.new(string[data]) → Packet +

      +
      • +
    • +

      +Packet.new(uint[size]) → Packet +

      +
      • +
    • +

      +Packet.new(fields) → Packet +

      +
      • +
    • +

      +Packet.new(RawBuffer) → Packet +

      +
      • +
    • +

      +Packet.new(DAQHeader) → Packet +

      +
      • +
    • +

      +Packet:set_decode_data(DecodeData) +

      +
      • +
    • +

      +Packet:set_data(uint[offset], uint[length]) +

      +
      • +
    • +

      +Packet:set_flow(Flow) +

      +
      • +
    • +

      +Packet:get() → fields +

      +
      • +
    • +

      +Packet:set() +

      +
      • +
    • +

      +Packet:set(string[data]) +

      +
      • +
    • +

      +Packet:set(uint[size]) +

      +
      • +
    • +

      +Packet:set(fields) +

      +
      • +
    • +

      +Packet:set(RawBuffer) +

      +
      • +
    • +

      +Packet:set(DAQHeader) +

      +
      • +
    +

    fields is a table with the following contents:

    +
      +
    • +

      +packet_flags +

      +
      • +
    • +

      +xtradata_mask +

      +
      • +
    • +

      +proto_bits +

      +
      • +
    • +

      +application_protocol_ordinal +

      +
      • +
    • +

      +alt_dsize +

      +
      • +
    • +

      +num_layers +

      +
      • +
    • +

      +iplist_id +

      +
      • +
    • +

      +user_policy_id +

      +
      • +
    • +

      +ps_proto +

      +
      • +
    +

    Note: Packet.new() and Packet:set() accept multiple arguments of the +types described above in any order

    +

    RawBuffer

    +
      +
    • +

      +RawBuffer.new() → RawBuffer +

      +
      • +
    • +

      +RawBuffer.new(uint[size]) → RawBuffer +

      +
      • +
    • +

      +RawBuffer.new(string[data]) → RawBuffer +

      +
      • +
    • +

      +RawBuffer:size() → int +

      +
      • +
    • +

      +RawBuffer:resize(uint[size]) +

      +
      • +
    • +

      +RawBuffer:write(string[data]) +

      +
      • +
    • +

      +RawBuffer:write(string[data], uint[size]) +

      +
      • +
    • +

      +RawBuffer:read() → string +

      +
      • +
    • +

      +RawBuffer:read(uint[end]) → string +

      +
      • +
    • +

      +RawBuffer:read(uint[start], uint[end]) → string +

      +
      • +
    +

    Note: calling RawBuffer.new() with no arguments returns a RawBuffer of size 0

    +

    StreamSplitter

    +
      +
    • +

      +StreamSplitter:scan(Flow, RawBuffer) → int, int +

      +
      • +
    • +

      +StreamSplitter:scan(Flow, RawBuffer, uint[len]) → int, int +

      +
      • +
    • +

      +StreamSplitter:scan(Flow, RawBuffer, uint[len], uint[flags]) → int, int +

      +
      • +
    • +

      +StreamSplitter:reassemble(Flow, uint[total], uint[offset], RawBuffer) → int, RawBuffer +

      +
      • +
    • +

      +StreamSplitter:reassemble(Flow, uint[total], uint[offset], RawBuffer, uint[len]) → int, RawBuffer +

      +
      • +
    • +

      +StreamSplitter:reassemble(Flow, uint[total], uint[offset], RawBuffer, uint[len], uint[flags]) → int, RawBuffer +

      +
      • +
    • +

      +StreamSplitter:finish(Flow) → bool +

      +
      • +
    +

    Note: StreamSplitter does not have a new() method, it must be created by an inspector via +Inspector.get_splitter()

    +
    +
    +
    +
    +
    +
    +

    Coding Style

    +
    +

    All new code should try to follow these style guidelines. These are not +yet firm so feedback is welcome to get something we can live with.

    +
    +

    General

    +
    +
    +
    +

    Naming

    +
      +
    • +

      +Use camel case for namespaces, classes, and types like WhizBangPdfChecker. +

      +
      • +
    • +

      +Use lower case identifiers with underscore separators, e.g. some_function() + and my_var. +

      +
      • +
    • +

      +Use lower case filenames with underscores. +

      +
      • +
    +
    +
    +

    Comments

    +
      +
    • +

      +Write comments sparingly with a mind towards future proofing. Often the + comments can be obviated with better code. Clear code is better than a + comment. +

      +
      • +
    • +

      +Function comment blocks are generally just noise that quickly becomes + obsolete. If you absolutely must comment on parameters, put each on a + separate line along with the comment. That way changing the signature + may prompt a change to the comments too. +

      +
      • +
    • +

      +Use FIXIT (not FIXTHIS or TODO or whatever) to mark things left for a + day or even just a minute. That way we can find them easily and won’t + lose track of them. +

      +
      • +
    • +

      +Presently using FIXIT-X where X = P | H | M | L, indicating perf, high, + med, or low priority. For now, H, M, or L can indicate alpha 1, 2, or 3. + Perf changes fall between alpha 1 and 2. +

      +
      • +
    • +

      +Put the copyright(s) and license in a comment block at the top of each + source file (.h and .cc). Don’t bother with trivial scripts and make + foo. Some interesting Lua code should get a comment block too. Copy and + paste exactly from src/main.h (don’t reformat). +

      +
      • +
    • +

      +Put author, description, etc. in separate comment(s) following the + license. Do not put such comments in the middle of the license foo. + Be sure to put the author line ahead of the header guard to exclude them + from the developers guide. +

      +
      • +
    • +

      +Each header should have a comment immediately after the header guard to + give an overview of the file so the user knows what’s going on. +

      +
      • +
    +
    +
    +

    Logging

    +
      +
    • +

      +Messages intended for the user should not look like debug messages. Eg, + the function name should not be included. +

      +
      • +
    • +

      +Most debug messages should just be deleted. +

      +
      • +
    • +

      +Don’t bang your error messages (no !). The user feels bad enough about the + problem already w/o you shouting at him. +

      +
      • +
    +
    +
    +

    Types

    +
      +
    • +

      +Use logical types to make the code clearer and to help the compiler catch + problems. typedef uint16_t Port; bool foo(Port) is way better than + int foo(int port). +

      +
      • +
    • +

      +Use forward declarations (e.g. struct SnortConfig;) instead of void*. +

      +
      • +
    • +

      +Try not to use extern data unless absolutely necessary and then put the + extern in an appropriate header. +

      +
      • +
    • +

      +Use const liberally. In most cases, const char* s = "foo" should be + const char* const s = "foo". The former goes in the initialized data + section and the latter in read only data section. +

      +
      • +
    • +

      +But use const char s[] = "foo" instead of const char* s = "foo" when + possible. The latter form allocates a pointer variable and the data + while the former allocates only the data. +

      +
      • +
    • +

      +Use static wherever possible to minimize public symbols and eliminate + unneeded relocations. +

      +
      • +
    • +

      +Declare functions virtual only in the parent class introducing the + function (not in a derived class that is overriding the function). + This makes it clear which class introduces the function. +

      +
      • +
    • +

      +Declare functions as override if they are intended to override a + function. This makes it possible to find derived implementations that + didn’t get updated and therefore won’t get called due a change in the + parent signature. +

      +
      • +
    • +

      +Use bool functions instead of int unless there is truly a need for + multiple error returns. The C-style use of zero for success and -1 for + error is less readable and often leads to messy code that either ignores + the various errors anyway or needlessly and ineffectively tries to do + something aobut them. +

      +
      • +
    +
    +
    +

    Macros (aka defines)

    +
      +
    • +

      +In many cases, even in C++, use #define name "value" instead of a + const char* const name = "value" because it will eliminate a symbol from + the binary. +

      +
      • +
    • +

      +Use inline functions instead of macros where possible (pretty much all + cases except where stringification is necessary). Functions offer better + typing, avoid re-expansions, and a debugger can break there. +

      +
      • +
    • +

      +All macros except simple const values should be wrapped in () and all + args should be wrapped in () too to avoid surprises upon expansion. + Example: +

      +
      +
      +
      #define SEQ_LT(a,b)  ((int)((a) - (b)) <  0)
      +
      +
      • +
    • +

      +Multiline macros should be blocked (i.e. inside { }) to avoid if-else type + surprises. +

      +
      • +
    +
    +
    +

    Formatting

    +
      +
    • +

      +Indent 4 space chars … no tabs! +

      +
      • +
    • +

      +If you need to indent many times, something could be rewritten or + restructured to make it clearer. Fewer indents is generally easier to + write, easier to read, and overall better code. +

      +
      • +
    • +

      +Braces go on the line immediately following a new scope (function + signature, if, else, loop, switch, etc. +

      +
      • +
    • +

      +Use consistent spacing and line breaks. Always indent 4 spaces from the + breaking line. Keep lines less than 100 chars; it greatly helps + readability. +

      +
      +
      +
      No:
+    calling_a_func_with_a_long_name(arg1,
+                                    arg2,
+                                    arg3);
      +
      +
      +
      +
      Yes:
+    calling_a_func_with_a_long_name(
+        arg1, arg2, arg3);
      +
      +
      • +
    • +

      +Put function signature on one line, except when breaking for the arg + list: +

      +
      +
      +
      No:
+    inline
+    bool foo()
+    { // ...
      +
      +
      +
      +
      Yes:
+    inline bool foo()
+    { // ...
      +
      +
      • +
    • +

      +Put conditional code on the line following the if so it is easy to break + on the conditional block: +

      +
      +
      +
      No:
+    if ( test ) foo();
      +
      +
      +
      +
      Yes:
+    if ( test )
+        foo();
      +
      +
      • +
    +
    +
    +

    Headers

    +
      +
    • +

      +Don’t hesitate to create a new header if it is needed. Don’t lump + unrelated stuff into an header because it is convenient. +

      +
      • +
    • +

      +Write header guards like this (leading underscores are reserved for + system stuff). In my_header.h: +

      +
      +
      +
      #ifndef MY_HEADER_H
+#define MY_HEADER_H
+// ...
+#endif
      +
      +
      • +
    • +

      +Includes from a different directory should specify parent directory. + This makes it clear exactly what is included and avoids the primordial + soup that results from using -I this -I that -I the_other_thing … . +

      +
      +
      +
      // given:
+src/foo/foo.cc
+src/bar/bar.cc
+src/bar/baz.cc
      +
      +
      +
      +
      // in baz.cc
+#include "bar.h"
      +
      +
      +
      +
      // in foo.cc
+#include "bar/bar.h"
      +
      +
      • +
    • +

      +Includes within installed headers should specify parent directory. +

      +
      • +
    • +

      +Just because it is a #define doesn’t mean it goes in a header. + Everything should be scoped as tightly as possible. Shared + implementation declarations should go in a separate header from the + interface. And so on. +

      +
      • +
    • +

      +A .cc should include its own .h before any others (including + system headers). This ensures that the header stands on its own and can + be used by clients without include prerequisites. +

      +
      • +
    • +

      +Include required headers, all required headers, and nothing but required + headers. Don’t just clone a bunch of headers because it is convenient.

    • @@ -13301,6 +14160,17 @@ input source on a separate thread:

    snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
     --pcap-filter '*.pcap' --max-packet-threads 8
    +

    Run Snort++ on 2 interfaces, eth0 and eth1:

    +
    +
    +
    snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg
    +
    +

    Run Snort++ inline with the afpacket DAQ:

    +
    +
    +
    snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \
+    -A cmg
    +
    @@ -13639,7 +14509,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---dump-defaults [<module prefix>] output module defaults in Lua format +--dump-defaults [<module prefix>] output module defaults in Lua format (optional)

  • @@ -13649,7 +14519,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---dump-version output the version, the whole version, and only the version +--dump-version output the version, the whole version, and only the version (optional)

  • @@ -13664,17 +14534,17 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---help-commands [<module prefix>] output matching commands +--help-commands [<module prefix>] output matching commands (optional)

  • ---help-config [<module prefix>] output matching config options +--help-config [<module prefix>] output matching config options (optional)

  • ---help-counts [<module prefix>] output matching peg counts +--help-counts [<module prefix>] output matching peg counts (optional)

  • @@ -13689,7 +14559,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---help-options <option prefix> output matching command line option quick help (same as -?) +--help-options <option prefix> output matching command line option quick help (same as -?) (optional)

  • @@ -13719,17 +14589,17 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---list-builtin <module prefix> output matching builtin rules +--list-builtin <module prefix> output matching builtin rules (optional)

  • ---list-gids [<module prefix>] output matching generators +--list-gids [<module prefix>] output matching generators (optional)

  • ---list-modules [<module type>] list all known modules of given type +--list-modules [<module type>] list all known modules of given type (optional)

  • @@ -13739,7 +14609,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---logid <0xid> log Identifier to uniquely id events for multiple snorts (same as -G) +--logid <0xid> log Identifier to uniquely id events for multiple snorts (same as -G) (0:65535)

  • @@ -13754,7 +14624,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---max-packet-threads <count> configure maximum number of packet threads (same as -z) +--max-packet-threads <count> configure maximum number of packet threads (same as -z) (0:)

  • @@ -13794,7 +14664,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---pcap-loop <count> read all pcaps <count> times; 0 will read until Snort is terminated +--pcap-loop <count> read all pcaps <count> times; 0 will read until Snort is terminated (-1:)

  • @@ -13854,7 +14724,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---script-path <path> where to find luajit scripts +--script-path <path> to a luajit script or directory containing luajit scripts

  • @@ -13869,12 +14739,12 @@ into the Snort binary. For a full list of build features, run ./configure

  • ---skip <n> skip 1st n packets +--skip <n> skip 1st n packets (0:)

  • ---snaplen <snap> set snaplen of packet (same as -s) +--snaplen <snap> set snaplen of packet (same as -s) (68:65535)

  • @@ -13894,6 +14764,11 @@ into the Snort binary. For a full list of build features, run ./configure

  • +--unit-test <verbosity> run unit tests with given libcheck output mode (silent | minimal | normal | verbose | env (export CK_VERBOSITY)) +

    +
    • +
  • +

    --version show version number (same as -V)

    • @@ -13959,7 +14834,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • --? <option prefix> output matching command line option quick help (same as --help-options) +-? <option prefix> output matching command line option quick help (same as --help-options) (optional)

  • @@ -13989,7 +14864,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • --G <0xid> (same as --logid) +-G <0xid> (same as --logid) (0:65535)

  • @@ -14089,7 +14964,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • --k <mode> checksum mode (all,noip,notcp,noudp,noicmp,none) +-k <mode> checksum mode; default is all (all|noip|notcp|noudp|noicmp|none)

  • @@ -14099,12 +14974,12 @@ into the Snort binary. For a full list of build features, run ./configure

  • --m <umask> set umask = <umask> +-m <umask> set umask = <umask> (0:)

  • --n <count> stop after count packets +-n <count> stop after count packets (0:)

  • @@ -14119,7 +14994,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • --s <snap> (same as --snaplen) +-s <snap> (same as --snaplen); default is 1514 (68:65535)

  • @@ -14154,7 +15029,7 @@ into the Snort binary. For a full list of build features, run ./configure

  • --z <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system +-z <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system; default is 1 (0:)

    • @@ -14191,6 +15066,11 @@ into the Snort binary. For a full list of build features, run ./configure

  • +dynamic: a select type determined by loaded plugins +

    +
    • +
  • +

    enum: a string selected from the given range

    • @@ -15925,6 +16805,16 @@ int network.new_ttl = 1: use this value for responses and when

  • +int new_http_inspect.request_depth = -1: maximum request message body bytes to examine (-1 no limit) { -1: } +

    +
    • +
  • +

    +int new_http_inspect.response_depth = -1: maximum response message body bytes to examine (-1 no limit) { -1: } +

    +
    • +
  • +

    bool new_http_inspect.test_input = false: read HTTP messages from text file

    • @@ -16205,7 +17095,7 @@ bool perf_monitor.max = false: calculate theoretical maximum pe

  • -int perf_monitor.max_file_size = 4096: files will be rolled over if they exceed this size { 4096: } +int perf_monitor.max_file_size = 4294967295: files will be rolled over if they exceed this size { 4096: }

  • @@ -16590,7 +17480,7 @@ int search_engine.max_queue_events = 5: maximum number of match

  • -select search_engine.search_method = ac_bnfa_q: set fast pattern algorithm - choose available search engine { ac_banded | ac_bnfa | ac_bnfa_q | ac_full | ac_full_q | ac_sparse | ac_sparse_bands | ac_std } +dynamic search_engine.search_method = ac_bnfa_q: set fast pattern algorithm - choose available search engine { ac_banded | ac_bnfa | ac_bnfa_q | ac_full | ac_full_q | ac_sparse | ac_sparse_bands | ac_std | lowmem | lowmem_q }

  • @@ -17120,7 +18010,7 @@ string snort.--run-prefix: <pfx> prepend this to each out

  • -string snort.--script-path: <path> where to find luajit scripts +string snort.--script-path: <path> to a luajit script or directory containing luajit scripts

  • @@ -17160,6 +18050,11 @@ implied snort.--treat-drop-as-ignore: use drop, sdrop, and reje

  • +select snort.--unit-test: <verbosity> run unit tests with given libcheck output mode { silent | minimal | normal | verbose | env (export CK_VERBOSITY) } +

    +
    • +
  • +

    implied snort.--version: show version number (same as -V)

    • @@ -17355,7 +18250,7 @@ port snort.-j: <port> to listen for telnet connections

  • -enum snort.-k = all: <mode> checksum mode (all,noip,notcp,noudp,noicmp,none) { all|noip|notcp|noudp|noicmp|none } +enum snort.-k = all: <mode> checksum mode; default is all { all|noip|notcp|noudp|noicmp|none }

  • @@ -17385,7 +18280,7 @@ string snort.-r: <pcap>… (same as --pcap-list)

  • -int snort.-s = 1514: <snap> (same as --snaplen) { 68:65535 } +int snort.-s = 1514: <snap> (same as --snaplen); default is 1514 { 68:65535 }

  • @@ -17420,7 +18315,7 @@ implied snort.-y: include year in timestamp in the alert and lo

  • -int snort.-z = 1: <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system { 0: } +int snort.-z = 1: <count> maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported by the system; default is 1 { 0: }

  • @@ -23563,7 +24458,7 @@ deleted -> unified2: 'filename'
    diff --git a/doc/default_snort_manual.pdf b/doc/default_snort_manual.pdf index 34858e4aa..b7806f465 100644 Binary files a/doc/default_snort_manual.pdf and b/doc/default_snort_manual.pdf differ diff --git a/doc/default_snort_manual.text b/doc/default_snort_manual.text index 7a527af56..1fd431efb 100644 --- a/doc/default_snort_manual.text +++ b/doc/default_snort_manual.text @@ -251,8 +251,9 @@ Table of Contents 14.3. Inspectors 14.4. Codecs 14.5. IPS Actions - 14.6. Piglet Test Harness - 14.7. Developers Guide + 14.6. Developers Guide + 14.7. Piglet Test Harness + 14.8. Piglet Lua API 15. Coding Style @@ -290,7 +291,7 @@ Table of Contents Snorty ,,_ -*> Snort++ <*- -o" )~ Version 3.0.0-a2 (Build 163) from 2.9.7-177 +o" )~ Version 3.0.0-a2 (Build 167) from 2.9.7-177 '''' By Martin Roesch & The Snort Team http://snort.org/contact#team Copyright (C) 2014-2015 Cisco and/or its affiliates. All rights reserved. @@ -764,7 +765,7 @@ Optional: First set up the environment: export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\; -export SNORT_LUA_PATH=$my_path/etc +export SNORT_LUA_PATH=$my_path/etc/snort Then give it a go: @@ -781,25 +782,27 @@ Then give it a go: * Verify config, with or w/o rules: - $my_path/bin/snort -c $my_path/etc/snort.lua - $my_path/bin/snort -c $my_path/etc/snort.lua -R $my_path/etc/sample.rules + $my_path/bin/snort -c $my_path/etc/snort/snort.lua + $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules * Run IDS mode. To keep it brief, look at the first n packets in each file: - $my_path/bin/snort -c $my_path/etc/snort.lua -R $my_path/etc/sample.rules \ + $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \ -r -A alert_test -n 100000 * Let’s suppress 1:2123. We could edit the conf or just do this: - $my_path/bin/snort -c $my_path/etc/snort.lua -R $my_path/etc/sample.rules \ + $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \ -r -A alert_test -n 100000 --lua "suppress = { { gid = 1, sid = 2123 } }" * Go whole hog on a directory with multiple packet threads: - $my_path/bin/snort -c $my_path/etc/snort.lua -R $my_path/etc/sample.rules \ + $my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \ --pcap-filter \*.pcap --pcap-dir -A alert_fast -n 1000 --max-packet-threads 8 +For more examples, see the usage section. + 2.4. Tips @@ -1663,7 +1666,7 @@ Configuration: * bool search_engine.inspect_stream_inserts = false: inspect reassembled payload - disabling is good for performance, bad for detection - * select search_engine.search_method = ac_bnfa_q: set fast pattern + * dynamic search_engine.search_method = ac_bnfa_q: set fast pattern algorithm - choose available search engine { ac_banded | ac_bnfa | ac_bnfa_q | ac_full | ac_full_q | ac_sparse | ac_sparse_bands | ac_std } @@ -1702,9 +1705,8 @@ Configuration: * implied snort.-H: make hash tables deterministic * string snort.-i: … list of interfaces * port snort.-j: to listen for telnet connections - * enum snort.-k = all: checksum mode - (all,noip,notcp,noudp,noicmp,none) { all|noip|notcp|noudp|noicmp| - none } + * enum snort.-k = all: checksum mode; default is all { all| + noip|notcp|noudp|noicmp|none } * string snort.-L: logging mode (none, dump, pcap, or log_*) * string snort.-l: log to this directory instead of current directory @@ -1719,7 +1721,8 @@ Configuration: policy * string snort.-r: … (same as --pcap-list) * string snort.-S: set config variable x equal to value v - * int snort.-s = 1514: (same as --snaplen) { 68:65535 } + * int snort.-s = 1514: (same as --snaplen); default is 1514 + { 68:65535 } * implied snort.-T: test and report on the current Snort configuration * string snort.-t: chroots process to after @@ -1738,7 +1741,7 @@ Configuration: files * int snort.-z = 1: maximum number of packet threads (same as --max-packet-threads); 0 gets the number of CPU cores reported - by the system { 0: } + by the system; default is 1 { 0: } * implied snort.--alert-before-pass: process alert, drop, sdrop, or reject before pass; default is pass before alert, drop,… * string snort.--bpf: are standard BPF options, as @@ -1832,7 +1835,8 @@ Configuration: * implied snort.--rule-to-text: output plain so rule header to stdout for text rule on stdin * string snort.--run-prefix: prepend this to each output file - * string snort.--script-path: where to find luajit scripts + * string snort.--script-path: to a luajit script or + directory containing luajit scripts * implied snort.--shell: enable the interactive command line * implied snort.--piglet: enable piglet test harness mode * implied snort.--show-plugins: list module and plugin versions @@ -1845,6 +1849,9 @@ Configuration: reject rules into alert rules during startup * implied snort.--treat-drop-as-ignore: use drop, sdrop, and reject rules to ignore session traffic when not inline + * select snort.--unit-test: run unit tests with given + libcheck output mode { silent | minimal | normal | verbose | env + (export CK_VERBOSITY) } * implied snort.--version: show version number (same as -V) * implied snort.--warn-all: enable all warnings * implied snort.--warn-conf: warn about configuration issues @@ -2951,6 +2958,10 @@ Configuration: text file * bool new_http_inspect.test_output = false: print out HTTP section data + * int new_http_inspect.request_depth = -1: maximum request message + body bytes to examine (-1 no limit) { -1: } + * int new_http_inspect.response_depth = -1: maximum response + message body bytes to examine (-1 no limit) { -1: } Rules: @@ -3191,8 +3202,8 @@ Configuration: exit only { 0: } * int perf_monitor.flow_ip_memcap = 52428800: maximum memory for flow tracking { 8200: } - * int perf_monitor.max_file_size = 4096: files will be rolled over - if they exceed this size { 4096: } + * int perf_monitor.max_file_size = 4294967295: files will be rolled + over if they exceed this size { 4096: } * int perf_monitor.flow_ports = 1023: maximum ports to track { 0: } * bool perf_monitor.reset = true: reset (clear) statistics after each reporting interval @@ -6673,7 +6684,15 @@ determine verdict. (Conversely, builtin actions don’t have an associated plugin function.) -14.6. Piglet Test Harness +14.6. Developers Guide + +------------ + +Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated +guide to the source tree. + + +14.7. Piglet Test Harness ------------ @@ -6689,28 +6708,23 @@ plugin: plugin = { type = "piglet", - version = 1 -} - -piglet = -{ - name = "my_test_for_ipv4_codec", - type = "codec", - target = "ipv4", + name = "codec::ipv4", + use_defaults = true, test = function() - local raw_data = RawData.new(1024) + local daq_header = DAQHeader.new() + local raw_buffer = RawBuffer.new("some data") local codec_data = CodecData.new() local decode_data = DecodeData.new() - codec("decode", raw_data, codec_data, decode_data) - return true + return Codec.decode( + daq_header, + raw_buffer, + codec_data, + decode_data + ) end } -More example tests can be found in the piglet_scripts directory. -Refer to these examples for furthur usage of Lua wrappers to snort -data structures (such as Packet). - To run snort in piglet mode, first build snort with the BUILD_PIGLET option turned on (pass the flag -DBUILD_PIGLET:BOOL=ON in cmake). @@ -6724,12 +6738,298 @@ The test runner will generate a check-like output, indicating the the results of each test script. -14.7. Developers Guide +14.8. Piglet Lua API ------------ -Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated -guide to the source tree. +This section documents the API that piglet exposes to Lua. Refer to +the piglet directory in the source tree for examples of usage. + +Note: Because of the differences between the Lua and C++ data model +and type system, not all parameters map directly to the parameters of +the underlying C\++ member functions. Every effort has been made to +keep the mappings consist, but there are still some differences. They +are documented below. + +14.8.1. Plugin Instances + +For each test, piglet instantiates plugin specified in the name field +of the plugin table. The virtual methods of the instance are exposed +in a table unique to each plugin type. The name of the table is the +CamelCase name of the plugin type. + +For example, codec plugins have a virtual method called decode. This +method is called like this: + +Codec.decode(...) + +Codec + + * Codec.get_data_link_type() → { int, int, … } + * Codec.get_protocol_ids() → { int, int, … } + * Codec.decode(DAQHeader, RawBuffer, CodecData, DecodeData) → bool + * Codec.log(RawBuffer, uint[lyr_len]) + * Codec.encode(RawBuffer, EncState, Buffer) → bool + * Codec.update(uint[flags_hi], uint[flags_lo], RawBuffer, uint + [lyr_len] → int + * Codec.format(bool[reverse], RawBuffer, DecodeData) + +Differences: + + * In Codec.update(), the (uint64_t) flags parameter has been split + into flags_hi and flags_lo + +Inspector + + * Inspector.configure() + * Inspector.tinit() + * Inspector.tterm() + * Inspector.likes(Packet) + * Inspector.eval(Packet) + * Inspector.clear(Packet) + * Inspector.get_buf_from_key(string[key], Packet, RawBuffer) → bool + * Inspector.get_buf_from_id(uint[id], Packet, RawBuffer) → bool + * Inspector.get_buf_from_type(uint[type], Packet, RawBuffer) → bool + * Inspector.get_splitter(bool[to_server]) → StreamSplitter + +Differences: * In Inspector.configure(), the SnortConfig* parameter +is passed implicitly. * the overloaded get_buf() member function has +been split into three separate methods. + +IpsOption + + * IpsOption.hash() → int + * IpsOption.is_relative() → bool + * IpsOption.fp_research() → bool + * IpsOption.get_cursor_type() → int + * IpsOption.eval(Cursor, Packet) → int + * IpsOption.action(Packet) + +IpsAction + + * IpsAction.exec(Packet) + +Logger + + * Logger.open() + * Logger.close() + * Logger.reset() + * Logger.alert(Packet, string[message], Event) + * Logger.log(Packet, string[message], Event) + +SearchEngine + +Currently, SearchEngine does not expose any methods. + +SoRule + +Currently, SoRule does not expose any methods. + +14.8.1.1. Interface Objects + +Many of the plugins take C++ classes and structs as arguments. These +objects are exposed to the Lua API as Lua userdata. Exposed objects +are instantiated by calling the new method from each object’s method +table. + +For example, the DecodeData object can be instantiated and exposed to +Lua like this: + +local decode_data = DecodeData.new(...) + +Each object also exposes useful methods for getting and setting +member variables, and calling the C++ methods contained in the the +object. These methods can be accessed using the : accessor syntax: + +decode_data:set({ sp = 80, dp = 3500 }) + +Since this is just syntactic sugar for passing the object as the +first parameter of the function DecodeData.set, an equivalent form +is: + +decode_data.set(decode_data, { sp = 80, dp = 3500 }) + +or even: + +DecodeData.set(decode_data, { sp = 80, dp = 3500 }) + +Buffer + + * Buffer.new(string[data]) → Buffer + * Buffer.new(uint[length]) → Buffer + * Buffer.new(RawBuffer) → Buffer + * Buffer:allocate(uint[length]) → bool + * Buffer:clear() + +CodecData + + * CodecData.new() → CodecData + * CodecData.new(uint[next_prot_id]) → CodecData + * CodecData.new(fields) → CodecData + * CodecData:get() → fields + * CodecData:set(fields) + +fields is a table with the following contents: + + * next_prot_id + * lyr_len + * invalid_bytes + * proto_bits + * codec_flags + * ip_layer_cnt + * ip6_extension_count + * curr_ip6_extension + * ip6_csum_proto + +Cursor + + * Cursor.new() → Cursor + * Cursor.new(Packet) → Cursor + * Cursor.new(string[data]) → Cursor + * Cursor.new(RawBuffer) → Cursor + * Cursor:reset() + * Cursor:reset(Packet) + * Cursor:reset(string[data]) + * Cursor:reset(RawBuffer) + +DAQHeader + + * DAQHeader.new() → DAQHeader + * DAQHeader.new(fields) → DAQHeader + * DAQHeader:get() → fields + * DAQHeader:set(fields) + +fields is a table with the following contents: + + * caplen + * pktlen + * ingress_index + * egress_index + * ingress_group + * egress_group + * flags + * opaque + +DecodeData + + * DecodeData.new() → DecodeData + * DecodeData.new(fields) → DecodeData + * DecodeData:reset() + * DecodeData:get() → fields + * DecodeData:set(fields) + * DecodeData:set_ipv4_hdr(RawBuffer, uint[offset]) + +fields is a table with the following contents: + + * sp + * dp + * decode_flags + * type + +EncState + + * EncState.new() → EncState + * EncState.new(uint[flags_lo]) → EncState + * EncState.new(uint[flags_lo], uint[flags_hi]) → EncState + * EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto]) → + EncState + * EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto], + uint[ttl]) → EncState + * EncState.new(uint[flags_lo], uint[flags_hi], uint[next_proto], + uint[ttl], uint[dsize]) → EncState + +Event + + * Event.new() → Event + * Event.new(fields) → Event + * Event:get() → fields + * Event:set(fields) + +fields is a table with the following contents: + + * event_id + * event_reference + * sig_info + + + generator + + id + + rev + + class_id + + priority + + text_rule + + num_services + +Flow + + * Flow.new() → Flow + * Flow:reset() + +Packet + + * Packet.new() → Packet + * Packet.new(string[data]) → Packet + * Packet.new(uint[size]) → Packet + * Packet.new(fields) → Packet + * Packet.new(RawBuffer) → Packet + * Packet.new(DAQHeader) → Packet + * Packet:set_decode_data(DecodeData) + * Packet:set_data(uint[offset], uint[length]) + * Packet:set_flow(Flow) + * Packet:get() → fields + * Packet:set() + * Packet:set(string[data]) + * Packet:set(uint[size]) + * Packet:set(fields) + * Packet:set(RawBuffer) + * Packet:set(DAQHeader) + +fields is a table with the following contents: + + * packet_flags + * xtradata_mask + * proto_bits + * application_protocol_ordinal + * alt_dsize + * num_layers + * iplist_id + * user_policy_id + * ps_proto + +Note: Packet.new() and Packet:set() accept multiple arguments of the +types described above in any order + +RawBuffer + + * RawBuffer.new() → RawBuffer + * RawBuffer.new(uint[size]) → RawBuffer + * RawBuffer.new(string[data]) → RawBuffer + * RawBuffer:size() → int + * RawBuffer:resize(uint[size]) + * RawBuffer:write(string[data]) + * RawBuffer:write(string[data], uint[size]) + * RawBuffer:read() → string + * RawBuffer:read(uint[end]) → string + * RawBuffer:read(uint[start], uint[end]) → string + +Note: calling RawBuffer.new() with no arguments returns a RawBuffer +of size 0 + +StreamSplitter + + * StreamSplitter:scan(Flow, RawBuffer) → int, int + * StreamSplitter:scan(Flow, RawBuffer, uint[len]) → int, int + * StreamSplitter:scan(Flow, RawBuffer, uint[len], uint[flags]) → + int, int + * StreamSplitter:reassemble(Flow, uint[total], uint[offset], + RawBuffer) → int, RawBuffer + * StreamSplitter:reassemble(Flow, uint[total], uint[offset], + RawBuffer, uint[len]) → int, RawBuffer + * StreamSplitter:reassemble(Flow, uint[total], uint[offset], + RawBuffer, uint[len], uint[flags]) → int, RawBuffer + * StreamSplitter:finish(Flow) → bool + +Note: StreamSplitter does not have a new() method, it must be created +by an inspector via Inspector.get_splitter() --------------------------------------------------------------------- @@ -7187,6 +7487,15 @@ each input source on a separate thread: snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \ --pcap-filter '*.pcap' --max-packet-threads 8 +Run Snort++ on 2 interfaces, eth0 and eth1: + +snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg + +Run Snort++ inline with the afpacket DAQ: + +snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \ + -A cmg + 16.3. Plugins @@ -7424,20 +7733,23 @@ run ./configure --help. * --dump-builtin-rules [] output stub rules for selected modules * --dump-defaults [] output module defaults in Lua - format + format (optional) * --dump-dynamic-rules output stub rules for all loaded rules libraries * --dump-version output the version, the whole version, and only - the version + the version (optional) * --enable-inline-test enable Inline-Test Mode Operation * --help list command line options * --help-commands [] output matching commands + (optional) * --help-config [] output matching config options + (optional) * --help-counts [] output matching peg counts + (optional) * --help-module output description of given module * --help-modules list all available modules with brief help * --help-options