doc_DATA = \
snort_manual.text \
snort_manual.html \
-snort_manual.pdf
+snort_manual.pdf \
+snort_manual.chunked.tgz
dist_doc_DATA = \
$(all_sources)
-# can't put chunked in doc_DATA since the directory won't install correctly
-# so we disable auto install of chunked and do it with an install hook
-noinst_docdir = $(DESTDIR)
-noinst_doc_DATA = snort_manual.chunked
-
snort = $(top_builddir)/src/snort
snort2lua = $(top_builddir)/tools/snort2lua/snort2lua
plugin_path = $(if $(shell echo $$SNORT_PLUGIN_PATH), --plugin-path=$(SNORT_PLUGIN_PATH) )
# a2x generates an intermediate xml file unconditionally and always places
# it in this dir even if the output is put elsewhere, which breaks parallel
# builds. hence we just build all sequentially, which is why dependencies
-# are: chunked depends on text depends on pdf depends on html. chunked is
-# last since we can't depend on the directory. there is no default for
-# chunked.
-if MAKE_HTML_DOC
-snort_manual.chunked: $(all_sources) snort_manual.text
- a2x -f chunked $(html_args) $(snort_src)
-endif
-
+# are: chunked depends on text depends on pdf depends on html.
if MAKE_PDF_DOC
snort_manual.pdf: $(all_sources) snort_manual.html
a2x -f pdf $(pdf_args) $(snort_src)
cp $< $@
endif
+# autotools makes doesn't seem to like directory targets, especially ones
+# with an unspecified set of files. to avoid these issues, we generate
+# a tarball and then explode that upon install with a hook. note that
+# there is no default for chunked.
if MAKE_HTML_DOC
+snort_manual.chunked.tgz: $(all_sources) snort_manual.text
+ a2x -f chunked $(html_args) $(snort_src)
+ tar zcf $@ snort_manual.chunked
+
install-data-hook:
- [ -d $(builddir)/snort_manual.chunked ] && \
- cp -R $(builddir)/snort_manual.chunked $(DESTDIR)$(docdir)/
+ tar zxf $(DESTDIR)$(docdir)/snort_manual.chunked.tgz -C $(DESTDIR)$(docdir)/
uninstall-hook:
rm -rf $(DESTDIR)$(docdir)/snort_manual.chunked
<div class="literalblock">\r
<div class="content">\r
<pre><code> ,,_ -*> Snort++ <*-\r
-o" )~ Version 3.0.0-a1 (Build 160) from 2.9.7-177\r
+o" )~ Version 3.0.0-a2 (Build 163) from 2.9.7-177\r
'''' By Martin Roesch & The Snort Team\r
http://snort.org/contact#team\r
Copyright (C) 2014-2015 Cisco and/or its affiliates. All rights reserved.\r
manual\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+source-highlight from <a href="http://www.gnu.org/software/src-highlite/">http://www.gnu.org/software/src-highlite/</a> to\r
+ generate the dev guide.\r
+</p>\r
+</li>\r
</ul></div>\r
</div>\r
<div class="sect2">\r
</li>\r
<li>\r
<p>\r
-Cmake doc/ has a problem when SNORT_PLUGIN_PATH is set to get extras\r
-included in the manual.\r
+With cmake, make install will rebuild the docs even though when already\r
+ built.\r
</p>\r
</li>\r
<li>\r
<p>\r
-Making in doc/ may fail complaining something about xmllint. Just make\r
-again and it will succeed. Appears to be an unknown dependency but it\r
-works for me!\r
+IPS option hash and inspectors pop, imap, smtp, and ssl fail to build\r
+ dynamically due to missing symbols in hash/ and protocols/ despite them\r
+ being declared SO_PUBLIC.\r
</p>\r
</li>\r
</ul></div>\r
</li>\r
<li>\r
<p>\r
-string <strong>search_engine.search_method</strong> = ac_bnfa_q: set fast pattern algorithm - choose available search engine\r
+select <strong>search_engine.search_method</strong> = 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 }\r
</p>\r
</li>\r
<li>\r
</li>\r
<li>\r
<p>\r
+implied <strong>snort.--piglet</strong>: enable piglet test harness mode\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
implied <strong>snort.--show-plugins</strong>: list module and plugin versions\r
</p>\r
</li>\r
int <strong>snort.--x2c</strong>: output ASCII char for given hex (see also --c2x)\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+string <strong>snort.--x2s</strong>: output ASCII string for given byte code (see also --x2c)\r
+</p>\r
+</li>\r
</ul></div>\r
<div class="paragraph"><p>Commands:</p></div>\r
<div class="ulist"><ul>\r
determine verdict. (Conversely, builtin actions don’t have an associated\r
plugin function.)</p></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_piglet_test_harness">Piglet Test Harness</h3>\r
+<div class="paragraph"><p>In order to assist with plugin development, an experimental mode called "piglet" mode\r
+is provided. With piglet mode, you can call individual methods for a specific plugin.\r
+The piglet tests are specified as Lua scripts. Each piglet test script defines a test\r
+for a specific plugin.</p></div>\r
+<div class="paragraph"><p>Here is a minimal example of a piglet test script for the IPv4 Codec plugin:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>plugin =\r
+{\r
+ type = "piglet",\r
+ version = 1\r
+}</code></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>piglet =\r
+{\r
+ name = "my_test_for_ipv4_codec",\r
+ type = "codec",\r
+ target = "ipv4",\r
+ test = function()\r
+ local raw_data = RawData.new(1024)\r
+ local codec_data = CodecData.new()\r
+ local decode_data = DecodeData.new()</code></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code> codec("decode", raw_data, codec_data, decode_data)\r
+ return true\r
+ end\r
+}</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>More example tests can be found in the piglet_scripts directory. Refer to these\r
+examples for furthur usage of Lua wrappers to snort data structures (such as Packet).</p></div>\r
+<div class="paragraph"><p>To run snort in piglet mode, first build snort with the BUILD_PIGLET option turned on\r
+(pass the flag -DBUILD_PIGLET:BOOL=ON in cmake).</p></div>\r
+<div class="paragraph"><p>Then, run the following command:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>snort --script-path $test_scripts --piglet</code></pre>\r
+</div></div>\r
+<div class="paragraph"><p>(where $test_scripts is the directory containing your piglet tests).</p></div>\r
+<div class="paragraph"><p>The test runner will generate a check-like output, indicating the\r
+the results of each test script.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_developers_guide">Developers Guide</h3>\r
+<div class="paragraph"><p>Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated guide to\r
+the source tree.</p></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
but there are a few differences.\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+Each source directory should have a dev_notes.txt file summarizing the\r
+ key points for the code in that directory. These are built into the\r
+ developers guide.\r
+</p>\r
+</li>\r
</ul></div>\r
</div>\r
<div class="sect2">\r
<p>\r
Put author, description, etc. in separate comment(s) following the\r
license. Do not put such comments in the middle of the license foo.\r
+ Be sure to put the author line ahead of the header guard to exclude them\r
+ from the developers guide.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Each header should have a comment immediately after the header guard to\r
+ give an overview of the file so the user knows what’s going on.\r
</p>\r
</li>\r
</ul></div>\r
</li>\r
<li>\r
<p>\r
+Includes within installed headers should specify parent directory.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
Just because it is a #define doesn’t mean it goes in a header.\r
Everything should be scoped as tightly as possible. Shared\r
implementation declarations should go in a separate header from the\r
</li>\r
<li>\r
<p>\r
+With clang, use at least these compiler flags:\r
+</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><code>-Wall -Wextra -pedantic -Wformat -Wformat-security\r
+-Wno-deprecated-declarations</code></pre>\r
+</div></div>\r
+</li>\r
+<li>\r
+<p>\r
Then Fix All Warnings. None Allowed.\r
</p>\r
</li>\r
</li>\r
<li>\r
<p>\r
+<strong>--piglet</strong> enable piglet test harness mode\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
<strong>--plugin-path</strong> <path> where to find plugins\r
</p>\r
</li>\r
</li>\r
<li>\r
<p>\r
+<strong>--x2s</strong> output ASCII string for given byte code (see also --x2c)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
<strong>-?</strong> <option prefix> output matching command line option quick help (same as --help-options)\r
</p>\r
</li>\r
</li>\r
<li>\r
<p>\r
-string <strong>search_engine.search_method</strong> = ac_bnfa_q: set fast pattern algorithm - choose available search engine\r
+select <strong>search_engine.search_method</strong> = 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 }\r
</p>\r
</li>\r
<li>\r
</li>\r
<li>\r
<p>\r
+implied <strong>snort.--piglet</strong>: enable piglet test harness mode\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
string <strong>snort.--plugin-path</strong>: <path> where to find plugins\r
</p>\r
</li>\r
</li>\r
<li>\r
<p>\r
+string <strong>snort.--x2s</strong>: output ASCII string for given byte code (see also --x2c)\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
string <strong>snort.-?</strong>: <option prefix> output matching command line option quick help (same as --help-options) { (optional) }\r
</p>\r
</li>\r
</li>\r
<li>\r
<p>\r
+<strong>piglet::pp_codec</strong>: Codec piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_inspector</strong>: Inspector piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_ips_action</strong>: Ips action piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_ips_option</strong>: Ips option piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_logger</strong>: Logger piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_search_engine</strong>: Search engine piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_so_rule</strong>: SO rule piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<strong>piglet::pp_test</strong>: Test piglet\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
<strong>search_engine::ac_banded</strong>: Aho-Corasick Banded (high memory, moderate performance)\r
</p>\r
</li>\r
<div id="footnotes"><hr /></div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2015-07-06 07:36:48 EDT\r
+Last updated 2015-07-31 10:11:05 EDT\r
</div>\r
</div>\r
</body>\r
14.3. Inspectors
14.4. Codecs
14.5. IPS Actions
+ 14.6. Piglet Test Harness
+ 14.7. Developers Guide
15. Coding Style
Snorty
,,_ -*> Snort++ <*-
-o" )~ Version 3.0.0-a1 (Build 160) from 2.9.7-177
+o" )~ Version 3.0.0-a2 (Build 163) 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.
signatures and the protected_content rule option.
* w3m from http://sourceforge.net/projects/w3m/ to build the plain
text manual
+ * source-highlight from http://www.gnu.org/software/src-highlite/
+ to generate the dev guide.
2.2. Building
Wunused-but-set-variable is not understood by clang
clang: warning: argument unused during compilation: '-pthread'
- * Cmake doc/ has a problem when SNORT_PLUGIN_PATH is set to get
- extras included in the manual.
- * Making in doc/ may fail complaining something about xmllint. Just
- make again and it will succeed. Appears to be an unknown
- dependency but it works for me!
+ * With cmake, make install will rebuild the docs even though when
+ already built.
+ * IPS option hash and inspectors pop, imap, smtp, and ssl fail to
+ build dynamically due to missing symbols in hash/ and protocols/
+ despite them being declared SO_PUBLIC.
2.8.2. Config
* bool search_engine.inspect_stream_inserts = false: inspect
reassembled payload - disabling is good for performance, bad for
detection
- * string search_engine.search_method = ac_bnfa_q: set fast pattern
- algorithm - choose available search engine
+ * 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 }
* bool search_engine.split_any_any = false: evaluate any-any rules
separately to save memory
* bool search_engine.search_optimize = false: tweak state machine
* string snort.--run-prefix: <pfx> prepend this to each output file
* string snort.--script-path: <path> where to find 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
* int snort.--skip: <n> skip 1st n packets { 0: }
* int snort.--snaplen = 1514: <snap> set snaplen of packet (same as
* implied snort.--warn-vars: warn about variable definition and
usage issues
* int snort.--x2c: output ASCII char for given hex (see also --c2x)
+ * string snort.--x2s: output ASCII string for given byte code (see
+ also --x2c)
Commands:
associated plugin function.)
+14.6. 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. The piglet tests are
+specified as Lua scripts. Each piglet test script defines a test for
+a specific plugin.
+
+Here is a minimal example of a piglet test script for the IPv4 Codec
+plugin:
+
+plugin =
+{
+ type = "piglet",
+ version = 1
+}
+
+piglet =
+{
+ name = "my_test_for_ipv4_codec",
+ type = "codec",
+ target = "ipv4",
+ test = function()
+ local raw_data = RawData.new(1024)
+ local codec_data = CodecData.new()
+ local decode_data = DecodeData.new()
+
+ codec("decode", raw_data, codec_data, decode_data)
+ return true
+ 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:
+
+snort --script-path $test_scripts --piglet
+
+(where $test_scripts is the directory containing your piglet tests).
+
+The test runner will generate a check-like output, indicating the the
+results of each test script.
+
+
+14.7. Developers Guide
+
+------------
+
+Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated
+guide to the source tree.
+
+
---------------------------------------------------------------------
15. Coding Style
* Generally try to follow http://google-styleguide.googlecode.com/
svn/trunk/cppguide.xml, but there are a few differences.
+ * 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.
15.2. Naming
reformat).
* Put author, description, etc. in separate comment(s) following
the license. Do not put such comments in the middle of the
- license foo.
+ 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.
15.4. Logging
// 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
-Wall -Wextra -pedantic -Wformat -Wformat-security
-Wunused-but-set-variable -Wno-deprecated-declarations
+ * With clang, use at least these compiler flags:
+
+ -Wall -Wextra -pedantic -Wformat -Wformat-security
+ -Wno-deprecated-declarations
+
* Then Fix All Warnings. None Allowed.
between pcaps
* --pcap-show print a line saying what pcap is currently being read
* --pedantic warnings are fatal
+ * --piglet enable piglet test harness mode
* --plugin-path <path> where to find plugins
* --process-all-events process all action groups
* --rule <rules> to be added to configuration; may be repeated
* --warn-symbols warn about unknown symbols in your Lua config
* --warn-vars warn about variable definition and usage issues
* --x2c output ASCII char for given hex (see also --c2x)
+ * --x2s output ASCII string for given byte code (see also --x2c)
* -? <option prefix> output matching command line option quick help
(same as --help-options)
* -A <mode> set alert mode: none, cmg, or alert_*
compiling into state machine (0 means no maximum) { 0: }
* int search_engine.max_queue_events = 5: maximum number of
matching fast pattern states to queue per packet
- * string search_engine.search_method = ac_bnfa_q: set fast pattern
- algorithm - choose available search engine
+ * 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 }
* bool search_engine.search_optimize = false: tweak state machine
construction for better performance
* bool search_engine.split_any_any = false: evaluate any-any rules
* implied snort.--pcap-show: print a line saying what pcap is
currently being read
* implied snort.--pedantic: warnings are fatal
+ * implied snort.--piglet: enable piglet test harness mode
* string snort.--plugin-path: <path> where to find plugins
* implied snort.--process-all-events: process all action groups
* string snort.--rule: <rules> to be added to configuration; may be
* implied snort.--warn-vars: warn about variable definition and
usage issues
* int snort.--x2c: output ASCII char for given hex (see also --c2x)
+ * string snort.--x2s: output ASCII string for given byte code (see
+ also --x2c)
* string snort.-?: <option prefix> output matching command line
option quick help (same as --help-options) { (optional) }
* string snort.-A: <mode> set alert mode: none, cmg, or alert_*
* logger::log_null: support for null encapsulation
* logger::log_pcap: log packet in pcap format
* logger::unified2: output event and packet in unified2 format file
+ * piglet::pp_codec: Codec piglet
+ * piglet::pp_inspector: Inspector piglet
+ * piglet::pp_ips_action: Ips action piglet
+ * piglet::pp_ips_option: Ips option piglet
+ * piglet::pp_logger: Logger piglet
+ * piglet::pp_search_engine: Search engine piglet
+ * piglet::pp_so_rule: SO rule piglet
+ * piglet::pp_test: Test piglet
* search_engine::ac_banded: Aho-Corasick Banded (high memory,
moderate performance)
* search_engine::ac_bnfa: Aho-Corasick Binary NFA (low memory, high
set (EXTRA_VERSION_MAJOR 1)
set (EXTRA_VERSION_MINOR 0)
- set (EXTRA_VERSION_BUILD 0-a1)
+ set (EXTRA_VERSION_BUILD 0-a2)
set (VERSION "${EXTRA_VERSION_MAJOR}.${EXTRA_VERSION_MINOR}.${EXTRA_VERSION_BUILD}")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
# Process this file with autoconf to produce a configure script.
-AC_INIT([snort_extra], [1.0.0-a1], [snort-team@sourcefire.com])
+AC_INIT([snort_extra], [1.0.0-a2], [snort-team@sourcefire.com])
AC_PREREQ(2.69)
AC_CONFIG_SRCDIR([config.h.in])
cursor.h
data_bus.h
decode_data.h
- logger.h
inspector.h
ips_action.h
ips_option.h
+ logger.h
+ lua_api.h
module.h
mpse.h
parameter.h
cursor.h \
data_bus.h \
decode_data.h \
-logger.h \
inspector.h \
ips_action.h \
ips_option.h \
+logger.h \
+lua_api.h \
module.h \
mpse.h \
parameter.h \
hi_server.cc hi_server.h \
hi_server_norm.cc hi_server_norm.h \
hi_si.cc hi_si.h \
-hi_stateful_inspect.h \
hi_stream_splitter.cc hi_stream_splitter.h \
hi_ui_config.cc hi_ui_config.h \
hi_ui_iis_unicode_map.cc hi_ui_iis_unicode_map.h \
projects / thirdparty / snort3.git / commitdiff
