From: Russ Combs (rucombs) Date: Fri, 24 Jul 2020 14:04:57 +0000 (+0000) Subject: Merge pull request #2338 in SNORT/snort3 from ~RUCOMBS/snort3:doc_ock to master X-Git-Tag: 3.0.2-3~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=51dbcd8bb3ab0163e2ddc7749a82cd6b961e4dcb;p=thirdparty%2Fsnort3.git Merge pull request #2338 in SNORT/snort3 from ~RUCOMBS/snort3:doc_ock to master Squashed commit of the following: commit 69605eb5c65c077d388eb23ed7367e7fc0932b32 Author: russ Date: Thu Jul 23 11:29:16 2020 -0400 doc: update default text manuals commit e557a646ff67c6622ffe5bd92ba125eaeb3eb898 Author: russ Date: Tue Jul 14 11:53:58 2020 -0400 doc: split Snort manual into separate user, reference, and upgrade docs. commit 061e8c053cf9bb9a7255a0b6fe826bfe986b93eb Author: russ Date: Tue Jul 14 09:45:41 2020 -0400 style: fix cmake indentation --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 8ba3c5342..87812e17b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -57,9 +57,12 @@ endif (ENABLE_UNIT_TESTS) add_subdirectory (src) add_subdirectory (tools) add_subdirectory (lua) -add_subdirectory (doc) add_subdirectory (daqs) +if ( MAKE_DOC ) + add_subdirectory (doc) +endif ( MAKE_DOC ) + # Miscellaneous stuff. Does NOT directly affect Snort's build environment. include (${CMAKE_MODULE_PATH}/packaging_data.cmake) include (${CMAKE_MODULE_PATH}/create_pkg_config.cmake) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 3a12e36a5..c4e443d85 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,343 +1,77 @@ -if ( MAKE_DOC ) - add_custom_target ( snort_manuals ALL ) - set ( - HELP_SOURCES - commands.txt - config.txt - counts.txt - modules.txt - plugins.txt - options.txt - signals.txt - help.txt - ) +add_subdirectory (user) +add_subdirectory (reference) +add_subdirectory (upgrade) +add_subdirectory (devel) + +add_custom_target ( + docs-html + DEPENDS + docs-user-html + docs-reference-html + docs-upgrade-html +) + +add_custom_target ( + docs-pdf + DEPENDS + docs-user-pdf + docs-reference-pdf + docs-upgrade-pdf +) + +add_custom_target ( + docs-text + DEPENDS + docs-user-text + docs-reference-text + docs-upgrade-text +) + +add_custom_target ( + docs-user + DEPENDS + docs-user-html + docs-user-pdf + docs-user-text +) + +add_custom_target ( + docs-reference + DEPENDS + docs-reference-html + docs-reference-pdf + docs-reference-text +) + +add_custom_target ( + docs-upgrade + DEPENDS + docs-upgrade-html + docs-upgrade-pdf + docs-upgrade-text +) + +add_custom_target ( + docs-devel + DEPENDS + docs-devel-html +) + +add_custom_target ( + docs + DEPENDS + docs-user + docs-reference + docs-upgrade +) + +add_custom_target ( + docs-all + DEPENDS + docs-user + docs-reference + docs-upgrade + docs-devel +) - set ( - LIST_SOURCES - builtin.txt - gids.txt - ) - - set ( - MODULE_SOURCES - basic.txt - codec.txt - connector.txt - data.txt - inspector.txt - ips_action.txt - ips_option.txt - logger.txt - ) - - set ( - UNBUILT_SOURCES - active.txt - appid.txt - binder.txt - building.txt - byte_extract.txt - byte_jump.txt - byte_math.txt - byte_test.txt - concepts.txt - connectors.txt - daq.txt - dcerpc.txt - differences.txt - enviro.txt - errors.txt - extending.txt - features.txt - file_processing.txt - ftp.txt - high_availability.txt - http_inspect.txt - http2_inspect.txt - overview.txt - params.txt - perf_monitor.txt - pop_imap.txt - port_scan.txt - reference.txt - reload_limitations.txt - sensitive_data.txt - side_channel.txt - smtp.txt - snort2lua.txt - snort2x.png - snort3x.png - snort_manual.html - snort_manual.pdf - snort_manual.text - snort_manual.txt - snorty.png - style.txt - telnet.txt - terms.txt - testing_numerical_values.txt - trace.txt - tutorial.txt - usage.txt - wizard.txt - ) - - function ( add_help_command generator_script output_file ) - add_custom_command ( - OUTPUT ${output_file} - COMMAND ${generator_script} $ ${output_file} $ENV{SNORT_PLUGIN_PATH} - DEPENDS snort - COMMENT "Documents: building ${output_file} with $ENV{SNORT_PLUGIN_PATH}" - ) - endfunction ( add_help_command ) - - foreach ( output_file ${HELP_SOURCES} ) - add_help_command ( - "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_help.sh" - "${output_file}" - ) - list ( APPEND BUILT_SOURCES "${output_file}" ) - endforeach () - - foreach ( output_file ${LIST_SOURCES} ) - add_help_command ( - "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_list.sh" - "${output_file}" - ) - list ( APPEND BUILT_SOURCES "${output_file}" ) - endforeach () - - foreach ( output_file ${MODULE_SOURCES} ) - add_help_command ( - "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_module.sh" - "${output_file}" - ) - list ( APPEND BUILT_SOURCES "${output_file}" ) - endforeach () - - add_custom_command ( - OUTPUT version.txt - COMMAND $ -V 2>&1 | grep -v Using > version.txt - DEPENDS snort - COMMENT "Documents: building version.txt" - ) - list ( APPEND BUILT_SOURCES version.txt ) - - add_custom_command ( - OUTPUT snort2lua_cmds.txt - COMMAND $ --markup --help > snort2lua_cmds.txt - DEPENDS snort2lua - COMMENT "Documents: building snort2lua_cmds.txt" - ) - list ( APPEND BUILT_SOURCES snort2lua_cmds.txt ) - - if ( RUBY_EXECUTABLE ) - add_custom_command ( - OUTPUT config_changes.txt - COMMAND ${RUBY_EXECUTABLE} - "${CMAKE_CURRENT_LIST_DIR}/get_differences.rb" - "${CMAKE_SOURCE_DIR}/tools/snort2lua" - > "${CMAKE_CURRENT_BINARY_DIR}/config_changes.txt" - DEPENDS snort2lua get_differences.rb - COMMENT "Documents: building config_changes.txt" - ) - list ( APPEND BUILT_SOURCES config_changes.txt ) - - else ( RUBY_EXECUTABLE ) - list ( APPEND UNBUILT_SOURCES config_changes.txt ) - - endif ( RUBY_EXECUTABLE ) - - foreach ( file_name ${BUILT_SOURCES} ) - list ( - APPEND - BINARY_DIR_BUILT_SOURCES - "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" - ) - endforeach ( file_name ) - - foreach ( file_name ${UNBUILT_SOURCES} ) - list ( - APPEND - LIST_DIR_SOURCES - "${CMAKE_CURRENT_LIST_DIR}/${file_name}" - ) - endforeach ( file_name ) - - set ( BUILT_DIST ${BINARY_DIR_BUILT_SOURCES} ${BINARY_DIR_UNBUILT_SOURCES} ) - - add_custom_target ( - all_built_sources - DEPENDS ${BUILT_SOURCES} - ) - - add_dependencies ( snort_manuals all_built_sources ) - - if ( MAKE_HTML_DOC ) - set ( - HTML_ASCIIDOC_ARGS - -b xhtml11 -a toc2 -a icons -a imagesdir=. - ) - - set ( - HTML_A2X_ARGS - --format=chunked - --attribute=linkcss --attribute=stylesdir --attribute=disable-javascript - --xsltproc-opts=\"--stringparam chunk.tocs.and.lots 1\" - --attribute=quirks! --attribute=imagesdir=. - --resource=. - ) - - add_custom_command ( - OUTPUT snort_manual.html - COMMAND cp ${LIST_DIR_SOURCES} . - COMMAND ${ASCIIDOC_EXE} ${HTML_ASCIIDOC_ARGS} snort_manual.txt - DEPENDS all_built_sources - COMMENT "Documents: building snort_manual.html" - ) - - set ( HTML_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/html/" ) - - add_custom_command ( - OUTPUT "${HTML_DOC_TMP}/" - COMMAND mkdir -p ${HTML_DOC_TMP} - ) - - add_custom_command ( - OUTPUT snort_manual.tgz - COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . - COMMAND ${ASCIIDOC_A2X_EXE} ${HTML_A2X_ARGS} snort_manual.txt - COMMAND cp -r snort_manual.chunked .. - COMMAND tar zcf ../snort_manual.tgz -C ../ snort_manual.chunked - DEPENDS all_built_sources "${HTML_DOC_TMP}/" - WORKING_DIRECTORY ${HTML_DOC_TMP} - COMMENT "Documents: building snort_manual.tgz" - ) - - add_custom_target ( - html - COMMAND rm -rf ${HTML_DOC_TMP} - DEPENDS snort_manual.html snort_manual.tgz - ) - - foreach ( file_name ${UNBUILT_SOURCES} ) - list ( - APPEND - BINARY_DIR_UNBUILT_SOURCES - "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" - ) - endforeach ( file_name ) - - list ( - APPEND - EXTRA_CLEAN - "${CMAKE_CURRENT_BINARY_DIR}/snort_manual.chunked" - "${CMAKE_CURRENT_BINARY_DIR}/snort_manual.tgz" - ) - - add_custom_target ( - snort_online.html - COMMAND ${CMAKE_SOURCE_DIR}/doc/online_manual.sh - DEPENDS all_built_sources - ) - - add_custom_target ( - dev_guide.html - COMMAND ${CMAKE_SOURCE_DIR}/doc/dev_guide.sh ${CMAKE_SOURCE_DIR} - DEPENDS all_built_sources - ) - endif ( MAKE_HTML_DOC ) - - if ( MAKE_TEXT_DOC ) - set ( - TEXT_A2X_ARGS - --format=text - ) - - set ( TEXT_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/text" ) - - add_custom_command ( - OUTPUT "${TEXT_DOC_TMP}/" - COMMAND mkdir -p ${TEXT_DOC_TMP} - ) - - add_custom_command ( - OUTPUT snort_manual.text - COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . - COMMAND ${ASCIIDOC_A2X_EXE} ${TEXT_A2X_ARGS} snort_manual.txt - COMMAND cp snort_manual.text .. - DEPENDS all_built_sources "${TEXT_DOC_TMP}/" - WORKING_DIRECTORY ${TEXT_DOC_TMP} - COMMENT "Documents: building snort_manual.text" - ) - - add_custom_target ( - text - COMMAND rm -rf ${TEXT_DOC_TMP} - DEPENDS snort_manual.text - ) - endif ( MAKE_TEXT_DOC ) - - if ( MAKE_PDF_DOC ) - set ( - PDF_A2X_ARGS - --format=pdf - --attribute=imagesdir=. - ) - - set ( PDF_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/pdf" ) - - add_custom_command ( - OUTPUT "${PDF_DOC_TMP}/" - COMMAND mkdir -p ${PDF_DOC_TMP} - ) - - add_custom_command ( - OUTPUT snort_manual.pdf - COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . - COMMAND ${ASCIIDOC_A2X_EXE} ${PDF_A2X_ARGS} snort_manual.txt - COMMAND cp snort_manual.pdf .. - DEPENDS all_built_sources "${PDF_DOC_TMP}/" - WORKING_DIRECTORY ${PDF_DOC_TMP} - COMMENT "Documents: building snort_manual.pdf" - ) - - add_custom_target ( - pdf - COMMAND rm -rf ${PDF_DOC_TMP} - DEPENDS snort_manual.pdf - ) - endif ( MAKE_PDF_DOC ) - - install ( - FILES - ${BUILT_DIST} - ${UNBUILT_SOURCES} - DESTINATION - ${CMAKE_INSTALL_DOCDIR} - ) - - set ( - EXTRA_CLEAN - ${EXTRA_CLEAN} - ${BINARY_DIR_BUILT_SOURCES} - ) - - if ( NOT CMAKE_CURRENT_LIST_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR ) - list ( - APPEND - EXTRA_CLEAN - ${BINARY_DIR_UNBUILT_SOURCES} - ) - endif () - - if ( EXTRA_CLEAN ) - set_property ( - DIRECTORY - PROPERTY - ADDITIONAL_MAKE_CLEAN_FILES ${EXTRA_CLEAN} - ) - endif ( EXTRA_CLEAN ) - -endif ( MAKE_DOC ) diff --git a/doc/devel/CMakeLists.txt b/doc/devel/CMakeLists.txt new file mode 100644 index 000000000..a00ba6e59 --- /dev/null +++ b/doc/devel/CMakeLists.txt @@ -0,0 +1,91 @@ + +set ( + UNBUILT_SOURCES + snort_devel.txt + extending.txt + style.txt +) + +foreach ( file_name ${UNBUILT_SOURCES} ) + list ( + APPEND + LIST_DIR_SOURCES + "${CMAKE_CURRENT_LIST_DIR}/${file_name}" + ) +endforeach ( file_name ) + +set ( BUILT_DIST ${BINARY_DIR_BUILT_SOURCES} ${BINARY_DIR_UNBUILT_SOURCES} ) + +add_custom_command ( + OUTPUT version.txt + COMMAND $ -V 2>&1 | grep -o "Version.*$" > version.txt + COMMAND sed -i -e "s/Version/:revnumber:/" version.txt + COMMAND echo ":revdate: {localdate} {localtime}" >> version.txt + DEPENDS snort + COMMENT "Documents: building version.txt" +) + +list ( APPEND BUILT_SOURCES version.txt ) + +add_custom_target ( + dev_built_sources + DEPENDS ${BUILT_SOURCES} +) + +if ( MAKE_HTML_DOC ) + + set ( HTML_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/html/" ) + + add_custom_command ( + OUTPUT "${HTML_DOC_TMP}/" + COMMAND mkdir -p ${HTML_DOC_TMP} + ) + + add_custom_command ( + OUTPUT snort_devel.html + COMMAND mv ../${BUILT_SOURCES} ./ + COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} ./ + COMMAND ${CMAKE_CURRENT_LIST_DIR}/snort_devel.sh ${CMAKE_SOURCE_DIR} + COMMAND mv snort_devel.html ../ + DEPENDS dev_built_sources "${HTML_DOC_TMP}/" + WORKING_DIRECTORY ${HTML_DOC_TMP} + COMMENT "Documents: building dev guide" + ) + + add_custom_target ( + docs-devel-html + DEPENDS snort_devel.html + ) + +endif ( MAKE_HTML_DOC ) + +install ( + FILES + ${BUILT_DIST} + ${UNBUILT_SOURCES} + DESTINATION + ${CMAKE_INSTALL_DOCDIR} +) + +set ( + EXTRA_CLEAN + ${EXTRA_CLEAN} + ${BINARY_DIR_BUILT_SOURCES} +) + +if ( NOT CMAKE_CURRENT_LIST_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR ) + list ( + APPEND + EXTRA_CLEAN + ${BINARY_DIR_UNBUILT_SOURCES} + ) +endif () + +if ( EXTRA_CLEAN ) + set_property ( + DIRECTORY + PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES ${EXTRA_CLEAN} + ) +endif ( EXTRA_CLEAN ) + diff --git a/doc/extending.txt b/doc/devel/extending.txt similarity index 99% rename from doc/extending.txt rename to doc/devel/extending.txt index dde8f14c5..5861d1f75 100644 --- a/doc/extending.txt +++ b/doc/devel/extending.txt @@ -611,11 +611,6 @@ Note: calling ++RawBuffer.new()++ with no arguments returns a RawBuffer of size Note: StreamSplitter does not have a ++new()++ method, it must be created by an inspector via ++Inspector.get_splitter()++ -=== Developers Guide - -Run doc/dev_guide.sh to generate /tmp/dev_guide.html, an annotated guide to -the source tree. - === Performance Considerations for Developers * Since C compilers evaluate compound conditional expression from left to diff --git a/doc/devel/snort_devel.sh b/doc/devel/snort_devel.sh new file mode 100755 index 000000000..7334c0e08 --- /dev/null +++ b/doc/devel/snort_devel.sh @@ -0,0 +1,138 @@ +#!/usr/bin/env bash +# run from top of source tree (where configure.ac lives) +# or supply top_srcdir as argument +# use ./snort_devel.html to browse the source notes and headers +# +# FIXIT: +# -- make sidebar width draggable +# -- remove header guards? (outermost #ifndef, #define, #endif) +# -- use css source instead of the sed fixups? + +usage() +{ + echo "usage: $0 []" + exit -1 +} + +pushd . +work=`pwd` + +if [ "$1" ] ; then + cd $1 || usage + echo "cd $1" +fi + +[ -d src ] || usage + +out=snort_devel.txt +data=dev_data.txt +html=snort_devel.html +notes=dev_notes.txt + +src_dirs=`find src -type d -name "[^.]?*" | sort` + +# copy headers to temp working dir using same tree structure +# but strip out repetitive copyright blocks + +for d in $src_dirs ; do + mkdir -p $work/$d + + ls $d/*.h &> /dev/null || + continue + + for f in $d/*.h ; do + n=`grep -m 1 -n -o "#ifndef" $f` + n=${n/:*} + [ "$n" ] || continue + n=$((n-1)) + sed -e "1,${n}d" $f > $work/$f + done +done + +echo "generating doc source from headers and dev notes" + +for d in $src_dirs ; do + + # section heading + if [ ${#d} -eq 3 ] ; then + echo -e "=== $d/\n" + else + echo -e "=== ${d:4}/\n" + fi + + # section notes + if [ -e "$d/$notes" ] ; then + cp $d/$notes $work/$d/ + echo -e "include::$d/$notes[]\n" + fi + + ls $d/*.h &> /dev/null || + continue + + # now emit subsection for all headers + for h in $d/*.h ; do + [ -e "$work/$h" ] || continue + cat <> $work/$data + +echo "generating the dev guide" +popd +asc_args="-b xhtml11 -a toc2" +asciidoc $asc_args $out + +# fix up some stuff +# this is quick and dirty and but not future proof +echo "fixing up the html" + +sed -i.sed \ + -e "s/color: fuchsia/color: green/" \ + -e "s/margin-left: 16em/margin-left: 20em/" \ + -e "s/width: 13em/width: 18em/" \ + $html + +# now convert snort includes into links using the existing anchor points +# we can't derive the href ids because the toc generator only uses the +# file w/o path (eg _rules_h instead of _detection_rules_h) and will add +# numeric suffixes if non-unique (foo/rules.h and bar/rules.h would become +# _rules_h and _rules_h_2). + +# this function generates sed commands like this +# s|"detection/rules.h"|"detection/rules.h"| +# for each Path added above + +gen_cmds() +{ + while true ; do + read id + id=${id/*=\"/} + id=${id/\"*/} + + read path + path=${path/*Path = /} + path=${path/\<*/} + path=\"${path:4}\" + + echo "s|$path|$path|" + + if ! read sep ; then + break + fi + done +} + +echo "generating link commands" +grep -B 1 "Path = " $html | gen_cmds > sed_cmds.txt + +echo "translating snort includes into links" +sed -i.sed -f sed_cmds.txt $html + diff --git a/doc/devel/snort_devel.txt b/doc/devel/snort_devel.txt new file mode 100644 index 000000000..b6d39e802 --- /dev/null +++ b/doc/devel/snort_devel.txt @@ -0,0 +1,24 @@ + += Snort++ Developers Guide +The Snort Team +include::version.txt[] +:revdate: {localdate} {localtime} +:toc: +:toc-placement: manual +:toc-title: Contents +:toclevels: 4 + +toc::[] + +== Extending Snort + +include::extending.txt[] + +== Coding Style + +include::style.txt[] + +== Source Code + +include::dev_data.txt[] + diff --git a/doc/style.txt b/doc/devel/style.txt similarity index 100% rename from doc/style.txt rename to doc/devel/style.txt diff --git a/doc/reference/CMakeLists.txt b/doc/reference/CMakeLists.txt new file mode 100644 index 000000000..6150f26d3 --- /dev/null +++ b/doc/reference/CMakeLists.txt @@ -0,0 +1,245 @@ + +set ( + HELP_SOURCES + commands.txt + config.txt + counts.txt + modules.txt + plugins.txt + options.txt + signals.txt + help.txt +) + +set ( + LIST_SOURCES + builtin.txt + gids.txt +) + +set ( + MODULE_SOURCES + basic.txt + codec.txt + connector.txt + data.txt + inspector.txt + ips_action.txt + ips_option.txt + logger.txt +) + +set ( + UNBUILT_SOURCES + appendix.txt + building.txt + enviro.txt + snort_reference.txt +) + +set ( + DEFAULT_MANUALS + snort_reference.text +) + +function ( add_help_command generator_script output_file ) + add_custom_command ( + OUTPUT ${output_file} + COMMAND ${generator_script} $ ${output_file} $ENV{SNORT_PLUGIN_PATH} + DEPENDS snort + COMMENT "Documents: building ${output_file}" + ) +endfunction ( add_help_command ) + +foreach ( output_file ${HELP_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_help.sh" + "${output_file}" + ) + list ( APPEND BUILT_SOURCES "${output_file}" ) +endforeach () + +foreach ( output_file ${LIST_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_list.sh" + "${output_file}" + ) + list ( APPEND BUILT_SOURCES "${output_file}" ) +endforeach () + +foreach ( output_file ${MODULE_SOURCES} ) + add_help_command ( + "${CMAKE_CURRENT_LIST_DIR}/scripts/generate_module.sh" + "${output_file}" + ) + list ( APPEND BUILT_SOURCES "${output_file}" ) +endforeach () + +add_custom_command ( + OUTPUT version.txt + COMMAND $ -V 2>&1 | grep -o "Version.*$" > version.txt + COMMAND sed -i -e "s/Version/:revnumber:/" version.txt + DEPENDS snort + COMMENT "Documents: building version.txt" +) +list ( APPEND BUILT_SOURCES version.txt ) + +foreach ( file_name ${BUILT_SOURCES} ) + list ( + APPEND + BINARY_DIR_BUILT_SOURCES + "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" + ) +endforeach ( file_name ) + +foreach ( file_name ${UNBUILT_SOURCES} ) + list ( + APPEND + LIST_DIR_SOURCES + "${CMAKE_CURRENT_LIST_DIR}/${file_name}" + ) +endforeach ( file_name ) + +add_custom_target ( + ref_built_sources + DEPENDS ${BUILT_SOURCES} +) + +if ( MAKE_HTML_DOC ) + set ( + HTML_ASCIIDOC_ARGS + -b xhtml11 -a toc2 -a icons -a imagesdir=. + ) + + set ( + HTML_A2X_ARGS + --format=chunked + --attribute=linkcss --attribute=stylesdir --attribute=disable-javascript + --xsltproc-opts=\"--stringparam chunk.tocs.and.lots 1\" + --attribute=quirks! --attribute=imagesdir=. + --resource=. + ) + + set ( HTML_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/html/" ) + + add_custom_command ( + OUTPUT "${HTML_DOC_TMP}/" + COMMAND mkdir -p ${HTML_DOC_TMP} + ) + + add_custom_command ( + OUTPUT snort_reference.html + COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . + COMMAND ${ASCIIDOC_EXE} ${HTML_ASCIIDOC_ARGS} snort_reference.txt + COMMAND mv snort_reference.html ../ + DEPENDS ref_built_sources "${HTML_DOC_TMP}/" + WORKING_DIRECTORY ${HTML_DOC_TMP} + COMMENT "Documents: building snort_reference.html" + ) + + add_custom_target ( + docs-reference-html + DEPENDS snort_reference.html + ) + + foreach ( file_name ${UNBUILT_SOURCES} ) + list ( + APPEND + BINARY_DIR_UNBUILT_SOURCES + "${CMAKE_CURRENT_BINARY_DIR}/${file_name}" + ) + endforeach ( file_name ) + +endif ( MAKE_HTML_DOC ) + +if ( MAKE_TEXT_DOC ) + set ( + TEXT_A2X_ARGS + --format=text + ) + + set ( TEXT_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/text" ) + + add_custom_command ( + OUTPUT "${TEXT_DOC_TMP}/" + COMMAND mkdir -p ${TEXT_DOC_TMP} + ) + + add_custom_command ( + OUTPUT snort_reference.text + COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . + COMMAND ${ASCIIDOC_A2X_EXE} ${TEXT_A2X_ARGS} snort_reference.txt + COMMAND mv snort_reference.text ../ + DEPENDS ref_built_sources "${TEXT_DOC_TMP}/" + WORKING_DIRECTORY ${TEXT_DOC_TMP} + COMMENT "Documents: building snort_reference.text" + ) + + add_custom_target ( + docs-reference-text + DEPENDS snort_reference.text + ) + +endif ( MAKE_TEXT_DOC ) + +if ( MAKE_PDF_DOC ) + set ( + PDF_A2X_ARGS + --format=pdf + --attribute=imagesdir=. + ) + + set ( PDF_DOC_TMP "${CMAKE_CURRENT_BINARY_DIR}/pdf" ) + + add_custom_command ( + OUTPUT "${PDF_DOC_TMP}/" + COMMAND mkdir -p ${PDF_DOC_TMP} + ) + + add_custom_command ( + OUTPUT snort_reference.pdf + COMMAND cp ${LIST_DIR_SOURCES} ${BINARY_DIR_BUILT_SOURCES} . + COMMAND ${ASCIIDOC_A2X_EXE} ${PDF_A2X_ARGS} snort_reference.txt + COMMAND mv snort_reference.pdf ../ + DEPENDS ref_built_sources "${PDF_DOC_TMP}/" + WORKING_DIRECTORY ${PDF_DOC_TMP} + COMMENT "Documents: building snort_reference.pdf" + ) + + add_custom_target ( + docs-reference-pdf + DEPENDS snort_reference.pdf + ) + +endif ( MAKE_PDF_DOC ) + +install ( + FILES + ${UNBUILT_SOURCES} + ${DEFAULT_MANUALS} + DESTINATION + ${CMAKE_INSTALL_DOCDIR} +) + +set ( + EXTRA_CLEAN + ${EXTRA_CLEAN} + ${BINARY_DIR_BUILT_SOURCES} +) + +if ( NOT CMAKE_CURRENT_LIST_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR ) + list ( + APPEND + EXTRA_CLEAN + ${BINARY_DIR_UNBUILT_SOURCES} + ) +endif () + +if ( EXTRA_CLEAN ) + set_property ( + DIRECTORY + PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES ${EXTRA_CLEAN} + ) +endif ( EXTRA_CLEAN ) + diff --git a/doc/reference.txt b/doc/reference/appendix.txt similarity index 83% rename from doc/reference.txt rename to doc/reference/appendix.txt index b975319f5..749a4ebbb 100644 --- a/doc/reference.txt +++ b/doc/reference/appendix.txt @@ -1,3 +1,4 @@ + === Build Options include::building.txt[] @@ -37,12 +38,6 @@ documentation and are not applicable elsewhere. include::signals.txt[] -=== Configuration Changes - ----- -include::config_changes.txt[] ----- - === Module Listing include::modules.txt[] @@ -51,6 +46,3 @@ include::modules.txt[] include::plugins.txt[] -=== Limitations - -include::reload_limitations.txt[] diff --git a/doc/building.txt b/doc/reference/building.txt similarity index 100% rename from doc/building.txt rename to doc/reference/building.txt diff --git a/doc/enviro.txt b/doc/reference/enviro.txt similarity index 100% rename from doc/enviro.txt rename to doc/reference/enviro.txt diff --git a/doc/scripts/generate_help.sh b/doc/reference/scripts/generate_help.sh similarity index 100% rename from doc/scripts/generate_help.sh rename to doc/reference/scripts/generate_help.sh diff --git a/doc/scripts/generate_list.sh b/doc/reference/scripts/generate_list.sh similarity index 100% rename from doc/scripts/generate_list.sh rename to doc/reference/scripts/generate_list.sh diff --git a/doc/scripts/generate_module.sh b/doc/reference/scripts/generate_module.sh similarity index 100% rename from doc/scripts/generate_module.sh rename to doc/reference/scripts/generate_module.sh diff --git a/doc/snort_manual.text b/doc/reference/snort_reference.text similarity index 59% rename from doc/snort_manual.text rename to doc/reference/snort_reference.text index 1a9a60b2b..d4a510a4a 100644 --- a/doc/snort_manual.text +++ b/doc/reference/snort_reference.text @@ -1,5846 +1,347 @@ --------------------------------------------------------------------- -Snort 3 User Manual +Snort 3 Reference Manual --------------------------------------------------------------------- The Snort Team ---------------------------------------------------------------------- - -Table of Contents - -1. Overview - - 1.1. First Steps - 1.2. Configuration - 1.3. Output - -2. Concepts - - 2.1. Terminology - 2.2. Modules - 2.3. Parameters - 2.4. Plugins - 2.5. Operation - 2.6. Rules - 2.7. Pattern Matching - -3. Tutorial - - 3.1. Dependencies - 3.2. Building - 3.3. Running - 3.4. Tips - 3.5. Help - 3.6. Common Errors - 3.7. Gotchas - 3.8. Known Issues - -4. Usage - - 4.1. Help - 4.2. Sniffing and Logging - 4.3. Configuration - 4.4. IDS mode - 4.5. Plugins - 4.6. Output Files - 4.7. DAQ Alternatives - 4.8. Logger Alternatives - 4.9. Shell - 4.10. Signals - -5. Features - - 5.1. Active Response - 5.2. AppId - 5.3. Binder - 5.4. Byte rule options - 5.5. DCE Inspectors - 5.6. File Processing - 5.7. High Availability - 5.8. FTP - 5.9. HTTP Inspector - 5.10. HTTP/2 Inspector - 5.11. Performance Monitor - 5.12. POP and IMAP - 5.13. Port Scan - 5.14. Sensitive Data Filtering - 5.15. SMTP - 5.16. Telnet - 5.17. Trace - 5.18. Wizard - -6. Basic Modules - - 6.1. active - 6.2. alerts - 6.3. attribute_table - 6.4. classifications - 6.5. daq - 6.6. decode - 6.7. detection - 6.8. event_filter - 6.9. event_queue - 6.10. high_availability - 6.11. host_cache - 6.12. host_tracker - 6.13. hosts - 6.14. inspection - 6.15. ips - 6.16. latency - 6.17. memory - 6.18. network - 6.19. output - 6.20. packet_tracer - 6.21. packets - 6.22. payload_injector - 6.23. process - 6.24. profiler - 6.25. rate_filter - 6.26. references - 6.27. rule_state - 6.28. search_engine - 6.29. side_channel - 6.30. snort - 6.31. suppress - 6.32. trace - -7. Codec Modules - - 7.1. arp - 7.2. auth - 7.3. ciscometadata - 7.4. eapol - 7.5. erspan2 - 7.6. erspan3 - 7.7. esp - 7.8. eth - 7.9. fabricpath - 7.10. gre - 7.11. gtp - 7.12. icmp4 - 7.13. icmp6 - 7.14. igmp - 7.15. ipv4 - 7.16. ipv6 - 7.17. llc - 7.18. mpls - 7.19. pbb - 7.20. pgm - 7.21. pppoe - 7.22. tcp - 7.23. token_ring - 7.24. udp - 7.25. vlan - 7.26. wlan - -8. Connector Modules - - 8.1. file_connector - 8.2. tcp_connector - -9. Inspector Modules - - 9.1. appid - 9.2. appid_listener - 9.3. arp_spoof - 9.4. back_orifice - 9.5. binder - 9.6. cip - 9.7. data_log - 9.8. dce_http_proxy - 9.9. dce_http_server - 9.10. dce_smb - 9.11. dce_tcp - 9.12. dce_udp - 9.13. dnp3 - 9.14. dns - 9.15. domain_filter - 9.16. dpx - 9.17. file_id - 9.18. file_log - 9.19. ftp_client - 9.20. ftp_data - 9.21. ftp_server - 9.22. gtp_inspect - 9.23. http2_inspect - 9.24. http_inspect - 9.25. imap - 9.26. mem_test - 9.27. modbus - 9.28. normalizer - 9.29. packet_capture - 9.30. perf_monitor - 9.31. pop - 9.32. port_scan - 9.33. reputation - 9.34. rna - 9.35. rpc_decode - 9.36. s7commplus - 9.37. sip - 9.38. smtp - 9.39. so_proxy - 9.40. ssh - 9.41. ssl - 9.42. stream - 9.43. stream_file - 9.44. stream_icmp - 9.45. stream_ip - 9.46. stream_tcp - 9.47. stream_udp - 9.48. stream_user - 9.49. telnet - 9.50. wizard - -10. IPS Action Modules - - 10.1. react - 10.2. reject - 10.3. rewrite - -11. IPS Option Modules - - 11.1. ack - 11.2. appids - 11.3. asn1 - 11.4. base64_decode - 11.5. ber_data - 11.6. ber_skip - 11.7. bufferlen - 11.8. byte_extract - 11.9. byte_jump - 11.10. byte_math - 11.11. byte_test - 11.12. cip_attribute - 11.13. cip_class - 11.14. cip_conn_path_class - 11.15. cip_instance - 11.16. cip_req - 11.17. cip_rsp - 11.18. cip_service - 11.19. cip_status - 11.20. classtype - 11.21. content - 11.22. cvs - 11.23. dce_iface - 11.24. dce_opnum - 11.25. dce_stub_data - 11.26. detection_filter - 11.27. dnp3_data - 11.28. dnp3_func - 11.29. dnp3_ind - 11.30. dnp3_obj - 11.31. dsize - 11.32. enable - 11.33. enip_command - 11.34. enip_req - 11.35. enip_rsp - 11.36. file_data - 11.37. file_type - 11.38. flags - 11.39. flow - 11.40. flowbits - 11.41. fragbits - 11.42. fragoffset - 11.43. gid - 11.44. gtp_info - 11.45. gtp_type - 11.46. gtp_version - 11.47. http2_decoded_header - 11.48. http2_frame_header - 11.49. http_client_body - 11.50. http_cookie - 11.51. http_header - 11.52. http_method - 11.53. http_param - 11.54. http_raw_body - 11.55. http_raw_cookie - 11.56. http_raw_header - 11.57. http_raw_request - 11.58. http_raw_status - 11.59. http_raw_trailer - 11.60. http_raw_uri - 11.61. http_stat_code - 11.62. http_stat_msg - 11.63. http_trailer - 11.64. http_true_ip - 11.65. http_uri - 11.66. http_version - 11.67. icmp_id - 11.68. icmp_seq - 11.69. icode - 11.70. id - 11.71. ip_proto - 11.72. ipopts - 11.73. isdataat - 11.74. itype - 11.75. md5 - 11.76. metadata - 11.77. modbus_data - 11.78. modbus_func - 11.79. modbus_unit - 11.80. msg - 11.81. mss - 11.82. pcre - 11.83. pkt_data - 11.84. pkt_num - 11.85. priority - 11.86. raw_data - 11.87. reference - 11.88. regex - 11.89. rem - 11.90. replace - 11.91. rev - 11.92. rpc - 11.93. s7commplus_content - 11.94. s7commplus_func - 11.95. s7commplus_opcode - 11.96. sd_pattern - 11.97. seq - 11.98. service - 11.99. sha256 - 11.100. sha512 - 11.101. sid - 11.102. sip_body - 11.103. sip_header - 11.104. sip_method - 11.105. sip_stat_code - 11.106. so - 11.107. soid - 11.108. ssl_state - 11.109. ssl_version - 11.110. stream_reassemble - 11.111. stream_size - 11.112. tag - 11.113. target - 11.114. tos - 11.115. ttl - 11.116. urg - 11.117. window - 11.118. wscale - -12. Search Engine Modules -13. SO Rule Modules -14. Logger Modules - - 14.1. alert_csv - 14.2. alert_ex - 14.3. alert_fast - 14.4. alert_full - 14.5. alert_json - 14.6. alert_sfsocket - 14.7. alert_syslog - 14.8. alert_talos - 14.9. alert_unixsock - 14.10. log_codecs - 14.11. log_hext - 14.12. log_pcap - 14.13. unified2 - -15. DAQ Configuration and Modules - - 15.1. Building the DAQ Library and Its Bundled DAQ Modules - 15.2. Configuration - 15.3. Interaction With Multiple Packet Threads - 15.4. DAQ Modules Included With Snort 3 - -16. Snort 3 vs Snort 2 - - 16.1. Features New to Snort 3 - 16.2. Features Improved over Snort 2 - 16.3. Build Options - 16.4. Command Line - 16.5. Conf File - 16.6. Rules - 16.7. Output - 16.8. Sensitive Data - 16.9. Features Not Yet Supported by Snort 3 - -17. Snort2Lua - - 17.1. Snort2Lua Command Line - 17.2. Known Problems - 17.3. Usage - -18. Extending Snort - - 18.1. Plugins - 18.2. Modules - 18.3. Inspectors - 18.4. Codecs - 18.5. IPS Actions - 18.6. Piglet Test Harness - 18.7. Piglet Lua API - 18.8. Developers Guide - 18.9. Performance Considerations for Developers - -19. Coding Style - - 19.1. General - 19.2. C++ Specific - 19.3. Naming - 19.4. Comments - 19.5. Logging - 19.6. Types - 19.7. Macros (aka defines) - 19.8. Formatting - 19.9. Headers - 19.10. Warnings - 19.11. Uncrustify - -20. Reference - - 20.1. Build Options - 20.2. Environment Variables - 20.3. Command Line Options - 20.4. Configuration - 20.5. Counts - 20.6. Generators - 20.7. Builtin Rules - 20.8. Command Set - 20.9. Signals - 20.10. Configuration Changes - 20.11. Module Listing - 20.12. Plugin Listing - 20.13. Limitations - -Snorty - - ,,_ -*> Snort++ <*- -o" )~ Version 3.0.2 (Build 2) - '''' By Martin Roesch & The Snort Team - http://snort.org/contact#team - Copyright (C) 2014-2020 Cisco and/or its affiliates. All rights reserved. - Copyright (C) 1998-2013 Sourcefire, Inc., et al. - - ---------------------------------------------------------------------- - -1. Overview - ---------------------------------------------------------------------- - -Snort 3.0 is an updated version of the Snort Intrusion Prevention -System (IPS) which features a new design that provides a superset of -Snort 2.X functionality with better throughput, detection, -scalability, and usability. Some of the key features of Snort 3.0 -are: - - * Support multiple packet processing threads - * Use a shared configuration and attribute table - * Autodetect services for portless configuration - * Modular design - * Plugin framework with over 200 plugins - * More scalable memory profile - * LuaJIT configuration, loggers, and rule options - * Hyperscan support - * Rewritten TCP handling - * New rule parser and syntax - * Service rules like alert http - * Rule "sticky" buffers - * Way better SO rules - * New HTTP inspector - * New performance monitor - * New time and space profiling - * New latency monitoring and enforcement - * Piglets to facilitate component testing - * Inspection Events - * Automake and Cmake - * Autogenerate reference documentation - -Additional features are on the road map: - - * Use a shared network map - * Support hardware offload for fast pattern acceleration - * Provide support for DPDK and ODP - * Support pipelining of packet processing - * Support proxy mode - * Multi-tennant support - * Incremental reload - * New serialization of perf data and events - * Enhanced rule processing - * Windows support - * Anomaly detection - * and more! - -The remainder of this section provides a high level survey of the -inputs, processing, and outputs available with Snort 3.0. - -Snort++ is the project that is creating Snort 3.0. In this manual -"Snort" or "Snort 3" refers to the 3.0 version and earlier versions -will be referred to as "Snort 2" where the distinction is relevant. - - -1.1. First Steps - --------------- - -Snort can be configured to perform complex packet processing and deep -packet inspection but it is best start simply and work up to more -interesting tasks. Snort won’t do anything you didn’t specifically -ask it to do so it is safe to just try things out and see what -happens. Let’s start by just running Snort with no arguments: - -$ snort - -That will output usage information including some basic help -commands. You should run all of these commands now to see what is -available: - -$ snort -V -$ snort -? -$ snort --help - -Note that Snort has extensive command line help available so if -anything below isn’t clear, there is probably a way to get the exact -information you need from the command line. - -Now let’s examine the packets in a capture file (pcap): - -$ snort -r a.pcap - -Snort will decode and count the packets in the file and output some -statistics. Note that the output excludes non-zero numbers so it is -easy to see what is there. - -You may have noticed that there are command line options to limit the -number of packets examined or set a filter to select particular -packets. Now is a good time to experiment with those options. - -If you want to see details on each packet, you can dump the packets -to console like this: - -$ snort -r a.pcap -L dump - -Add the -d option to see the TCP and UDP payload. Now let’s switch to -live traffic. Replace eth0 in the below command with an available -network interface: - -$ snort -i eth0 -L dump - -Unless the interface is taken down, Snort will just keep running, so -enter Control-C to terminate or use the -n option to limit the number -of packets. - -Generally it is better to capture the packets for later analysis like -this: - -$ snort -i eth0 -L pcap -n 10 - -Snort will write 10 packets to log.pcap.# where # is a timestamp -value. You can read these back with -r and dump to console or pcap -with -L. You get the idea. - -Note that you can do similar things with other tools like tcpdump or -Wireshark however these commands are very useful when you want to -check your Snort setup. - -The examples above use the default pcap DAQ. Snort supports non-pcap -interfaces as well via the DAQ (data acquisition) library. Other DAQs -provide additional functionality such as inline operation and/or -higher performance. There are even DAQs that support raw file -processing (ie without packets), socket processing, and plain text -packets. To load external DAQ libraries and see available DAQs or -select a particular DAQ use one of these commands: - -$ snort --daq-dir --daq-list -$ snort --daq-dir --daq - -Be sure to put the --daq-dir option ahead of the --daq-list option or -the external DAQs won’t appear in the list. - -To leverage intrusion detection features of Snort you will need to -provide some configuration details. The next section breaks down what -must be done. - - -1.2. Configuration - --------------- - -Effective configuration of Snort is done via the environment, command -line, a Lua configuration file, and a set of rules. - -Note that backwards compatibility with Snort 2 was sacrificed to -obtain new and improved functionality. While Snort 3 leverages some -of the Snort 2 code base, a lot has changed. The configuration of -Snort 3 is done with Lua, so your old conf won’t work as is. Rules -are still text based but with syntax tweaks, so your 2.X rules must -be fixed up. However, snort2lua will help you convert your conf and -rules to the new format. - -1.2.1. Command Line - -A simple command line might look like this: - -snort -c snort.lua -R cool.rules -r some.pcap -A cmg - -To understand what that does, you can start by just running snort -with no arguments by running snort --help. Help for all configuration -and rule options is available via a suitable command line. In this -case: - --c snort.lua is the main configuration file. This is a Lua script -that is executed when loaded. - --R cool.rules contains some detection rules. You can write your own -or obtain them from Talos (native 3.0 rules are not yet available -from Talos so you must convert them with snort2lua). You can also put -your rules directly in your configuration file. - --r some.pcap tells Snort to read network traffic from the given -packet capture file. You could instead use -i eth0 to read from a -live interface. There many other options available too depending on -the DAQ you use. - --A cmg says to output intrusion events in "cmg" format, which has -basic header details followed by the payload in hex and text. - -Note that you add to and/or override anything in your configuration -file by using the --lua command line option. For example: - ---lua 'ips = { enable_builtin_rules = true }' - -will load the built-in decoder and inspector rules. In this case, ips -is overwritten with the config you see above. If you just want to -change the config given in your configuration file you would do it -like this: - ---lua 'ips.enable_builtin_rules = true' - -1.2.2. Configuration File - -The configuration file gives you complete control over how Snort -processes packets. Start with the default snort.lua included in the -distribution because that contains some key ingredients. Note that -most of the configurations look like: - -stream = { } - -This means enable the stream module using internal defaults. To see -what those are, you could run: - -snort --help-config stream - -Snort is organized into a collection of builtin and plugin modules. -If a module has parameters, it is configured by a Lua table of the -same name. For example, we can see what the active module has to -offer with this command: - -$ snort --help-module active - -What: configure responses - -Type: basic - -Configuration: - -int active.attempts = 0: number of TCP packets sent per response (with -varying sequence numbers) { 0:20 } - -string active.device: use 'ip' for network layer responses or 'eth0' etc -for link layer - -string active.dst_mac: use format '01:23:45:67:89:ab' - -int active.max_responses = 0: maximum number of responses { 0: } - -int active.min_interval = 255: minimum number of seconds between -responses { 1: } - -This says active is a basic module that has several parameters. For -each, you will see: - -type module.name = default: help { range } - -For example, the active module has a max_responses parameter that -takes non-negative integer values and defaults to zero. We can change -that in Lua as follows: - -active = { max_responses = 1 } - -or: - -active = { } -active.max_responses = 1 - -If we also wanted to limit retries to at least 5 seconds, we could -do: - -active = { max_responses = 1, min_interval = 5 } - -1.2.3. Whitelist - -When Snort is run with the --warn-conf-strict option, warnings will -be generated for all Lua tables present in the configuration files -that do not map to Snort module names. Like with other warnings, -these will upgraded to errors when Snort is run in pedantic mode. - -To dynamically add exceptions that should bypass this strict -validation, two Lua functions are made available to be called during -the evaluation of Snort configuration files: snort_whitelist_append() -and snort_whitelist_add_prefix(). Each function takes a -whitespace-delimited list, the former a list of exact table names and -the latter a list of table name prefixes to allow. - -Examples: snort_whitelist_append("table1 table2") -snort_whitelist_add_prefix("local_ foobar_") - -The accumulated contents of the whitelist (both exact and prefix) -will be dumped when Snort is run in verbose mode (-v). - -1.2.4. Rules - -Rules determine what Snort is looking for. They can be put directly -in your Lua configuration file with the ips module, on the command -line with --lua, or in external files. Generally you will have many -rules obtained from various sources such as Talos and loading -external files is the way to go so we will summarize that here. Add -this to your Lua configuration: - -ips = { include = 'rules.txt' } - -to load the external rules file named rules.txt. You can only specify -one file this way but rules files can include other rules files with -the include statement. In addition you can load rules like: - -$ sort -c snort.lua -R rules.txt - -You can use both approaches together. - -1.2.5. Includes - -Your configuration file file may include other files, either directly -via Lua or via various parameters. Snort will find relative includes -in the following order: - - 1. If you specify --include-path, this directory will be tried - first. - 2. Snort will try the directory containing the including file. - 3. Snort will try the directory containing the -c configuration - file. - -Some things to keep in mind: - - * If you use the Lua dofile function, then you must specify - absolute paths or paths relative to your working directory since - Lua will execute the include before Snort sees the file contents. - * For best results, use include in place of dofile. This function - is provided to follow Snort’s include logic. - * As of now, appid and reputation paths must be absolute or - relative to the working directory. These will be updated in a - future release. - -1.2.6. Converting Your 2.X Configuration - -If you have a working 2.X configuration snort2lua makes it easy to -get up and running with Snort 3. This tool will convert your -configuration and/or rules files automatically. You will want to -clean up the results and double check that it is doing exactly what -you need. - -snort2lua -c snort.conf - -The above command will generate snort.lua based on your 2.X -configuration. For more information and options for more -sophisticated use cases, see the Snort2Lua section later in the -manual. - - -1.3. Output - --------------- - -Snort can produce quite a lot of data. In the following we will -summarize the key aspects of the core output types. Additional data -such as from appid is covered later. - -1.3.1. Basic Statistics - -At shutdown, Snort will output various counts depending on -configuration and the traffic processed. Generally, you may see: - - * Packet Statistics - this includes data from the DAQ and decoders - such as the number of packets received and number of UDP packets. - * Module Statistics - each module tracks activity via a set of peg - counts that indicate how many times something was observed or - performed. This might include the number of HTTP GET requests - processed and the number of TCP reset packets trimmed. - * File Statistics - look here for a breakdown of file type, bytes, - signatures. - * Summary Statistics - this includes total runtime for packet - processing and the packets per second. Profiling data will appear - here as well if configured. - -Note that only the non-zero counts are output. Run this to see the -available counts: - -$ snort --help-counts - -1.3.2. Alerts - -If you configured rules, you will need to configure alerts to see the -details of detection events. Use the -A option like this: - -$ snort -c snort.lua -r a.pcap -A cmg - -There are many types of alert outputs possible. Here is a brief list: - - * -A cmg is the same as -A fast -d -e and will show information - about the alert along with packet headers and payload. - * -A u2 is the same as -A unified2 and will log events and - triggering packets in a binary file that you can feed to other - tools for post processing. Note that Snort 3 does not provide the - raw packets for alerts on PDUs; you will get the actual buffer - that alerted. - * -A csv will output various fields in comma separated value - format. This is entirely customizable and very useful for pcap - analysis. - -To see the available alert types, you can run this command: - -$ snort --list-plugins | grep logger - -1.3.3. Files and Paths - -Note that output is specific to each packet thread. If you run 4 -packet threads with u2 output, you will get 4 different u2 files. The -basic structure is: - -/[][][] - -where: - - * logdir is set with -l and defaults to ./ - * run_prefix is set with --run-prefix else not used - * id# is the packet thread number that writes the file; with one - packet thread, id# (zero) is omitted without --id-zero - * X is / if you use --id-subdir, else _ if id# is used - * name is based on module name that writes the file - -Additional considerations: - - * There is no way to explicitly configure a full path to avoid - issues with multiple packet threads. - * All text mode outputs default to stdout - -1.3.4. Performance Statistics - -Still more data is available beyond the above. - - * By configuring the perf_monitor module you can capture a - configurable set of peg counts during runtime. This is useful to - feed to an external program so you can see what is happening - without stopping Snort. - * The profiler module allows you to track time and space used by - module and rules. Use this data to tune your system for best - performance. The output will show up under Summary Statistics at - shutdown. - - ---------------------------------------------------------------------- - -2. Concepts +Revision History +Revision 3.0.2 (Build 2) 2020-07-23 11:20:26 EDT TST --------------------------------------------------------------------- -This section provides background on essential aspects of Snort’s -operation. - - -2.1. Terminology - --------------- - - * basic module: a module integrated into Snort that does not come - from a plugin. - * binder: inspector that maps configuration to traffic - * builtin rules: codec and inspector rules for anomalies detected - internally. - * codec: short for coder / decoder. These plugins are used for - basic protocol decoding, anomaly detection, and construction of - active responses. - * data module: an adjunct configuration plugin for use with certain - inspectors. - * dynamic rules: plugin rules loaded at runtime. See SO rules. - * fast pattern: the content in an IPS rule that must be found by - the search engine in order for a rule to be evaluated. - * fast pattern matcher: see search engine. - * hex: a type of protocol magic that the wizard uses to identify - binary protocols. - * inspector: plugin that processes packets (similar to the Snort 2 - preprocessor) - * IPS: intrusion prevention system, like Snort. - * IPS action: plugin that allows you to perform custom actions when - events are generated. Unlike loggers, these are invoked before - thresholding and can be used to control external agents or send - active responses. - * IPS option: this plugin is the building blocks of IPS rules. - * logger: a plugin that performs output of events and packets. - Events are thresholded before reaching loggers. - * module: the user facing portion of a Snort component. Modules - chiefly provide configuration parameters, but may also provide - commands, builtin rules, profiling statistics, peg counts, etc. - Note that not all modules are plugins and not all plugins have - modules. - * peg count: the number of times a given event or condition occurs. - * plugin: one of several types of software components that can be - loaded from a dynamic library when Snort starts up. Some plugins - are coupled with the main engine in such a way that they must be - built statically, but a newer version can be loaded dynamically. - * search engine: a plugin that performs multipattern searching of - packets and payload to find rules that should be evaluated. There - are currently no specific modules, although there are several - search engine plugins. Related configuration is done with the - basic detection module. Aka fast pattern matcher. - * SO rule: a IPS rule plugin that performs custom detection that - can’t be done by a text rule. These rules typically do not have - associated modules. SO comes from shared object, meaning dynamic - library. - * spell: a type of protocol magic that the wizard uses to identify - ASCII protocols. - * text rule: a rule loaded from the configuration that has a header - and body. The header specifies action, protocol, source and - destination IP addresses and ports, and direction. The body - specifies detection and non-detection options. - * wizard: inspector that applies protocol magic to determine which - inspectors should be bound to traffic absent a port specific - binding. See hex and spell. - - -2.2. Modules - --------------- - -Modules are the building blocks of Snort. They encapsulate the types -of data that many components need including parameters, peg counts, -profiling, builtin rules, and commands. This allows Snort to handle -them generically and consistently. You can learn quite a lot about -any given module from the command line. For example, to see what -stream_tcp is all about, do this: - -$ snort --help-config stream_tcp - -Modules are configured using Lua tables with the same name. So the -stream_tcp module is configured with defaults like this: - -stream_tcp = { } - -The earlier help output showed that the default session tracking -timeout is 30 seconds. To change that to 60 seconds, you can -configure it this way: - -stream_tcp = { session_timeout = 60 } - -Or this way: - -stream_tcp = { } -stream_tcp.session_timeout = 60 - -More on parameters is given in the next section. - -Other things to note about modules: - - * Shutdown output will show the non-zero peg counts for all - modules. For example, if stream_tcp did anything, you would see - the number of sessions processed among other things. - * Providing the builtin rules allows the documentation to include - them automatically and also allows for autogenerating the rules - at startup. - * Only a few module provide commands at this point, most notably - the snort module. - - -2.3. Parameters - --------------- - -Parameters are given with this format: - -type name = default: help { range } - -The following types are used: - - * addr: any valid IP4 or IP6 address or CIDR - * addr_list: a space separated list of addr values - * bit_list: a list of consecutive integer values from 1 to the - range maximum - * bool: true or false - * dynamic: a select type determined by loaded plugins - * enum: a string selected from the given range - * implied: an IPS rule option that takes no value but means true - * int: a whole number in the given range - * interval: a set of ints (see below) - * ip4: an IP4 address or CIDR - * mac: an ethernet address with the form 01:02:03:04:05:06 - * multi: one or more space separated strings from the given range - * port: an int in the range 0:65535 indicating a TCP or UDP port - number - * real: a real number in the given range - * select: a string selected from the given range - * string: any string with no more than the given length, if any - -The parameter name may be adorned in various ways to indicate -additional information about the type and use of the parameter: - - * For Lua configuration (not IPS rules), if the name ends with [] - it is a list item and can be repeated. - * For IPS rules only, names starting with ~ indicate positional - parameters. The names of such parameters do not appear in the - rule. - * IPS rules may also have a wild card parameter, which is indicated - by a *. Used for unquoted, comma-separated lists such as service - and metadata. - * The snort module has command line options starting with a -. - * $ denotes variable names, eg rule_state.$gid_sid which would be - used like rule_state["1:23456"] = { }. - -Some additional details to note: - - * Table and variable names are case sensitive; use lower case only. - * String values are case sensitive too; use lower case only. - * Numeric ranges may be of the form low:high where low and high are - bounds included in the range. If either is omitted, there is no - hard bound. E.g. 0: means any x where x >= 0. - * Strings may have a numeric range indicating a length limit; - otherwise there is no hard limit. - * bit_list is typically used to store a set of byte, port, or VLAN - ID values. - * interval takes the form [operator]i, j<>k, or j<⇒k where i,j,k - are integers and operator is one of =, !, != (same as !), <, ⇐, - >, >=. j<>k means j < int < k and j<⇒k means j ⇐ int ⇐ k. - * Ranges may use maxXX like { 1:max32 } since max32 is easier to - read than 4294967295. To get the values of maxXX, use snort - --help-limits. - - -2.4. Plugins - --------------- - -Snort uses a variety of plugins to accomplish much of its processing -objectives, including: - - * Codec - to decode and encode packets - * Inspector - like Snort 2 preprocessors, for normalization, etc. - * IpsOption - for detection in Snort rules - * IpsAction - for custom actions - * Logger - for handling events - * Mpse - for fast pattern matching - * So - for dynamic rules - -The power of plugins is that they have a very focused purpose and can -be created with relative ease. For example, you can extend the rule -language by writing your own IpsOption and it will plug in and -function just like existing options. The extra directory has examples -of each type of plugin. - -Most plugins can be built statically or dynamically. By default they -are all static. There is no difference in functionality between -static or dynamic plugins but the dynamic build generates a slightly -lighter weight binary. Either way you can add dynamic plugins with ---plugin-path and newer versions will replace older versions, even -when built statically. - -A single dynamic library may contain more than one plugin. For -example, an inspector will typically be packaged together with any -associated rule options. - - -2.5. Operation - --------------- - -Snort is a signature-based IPS, which means that as it receives -network packets it reassembles and normalizes the content so that a -set of rules can be evaluated to detect the presence of any -significant conditions that merit further action. A rough processing -flow is as follows: - -Snort 2 - -The steps are: - - 1. Decode each packet to determine the basic network characteristics - such as source and destination addresses and ports. A typical - packet might have ethernet containing IP containing TCP - containing HTTP (ie eth:ip:tcp:http). The various encapsulating - protocols are examined for sanity and anomalies as the packet is - decoded. This is essentially a stateless effort. - 2. Preprocess each decoded packet using accumulated state to - determine the purpose and content of the innermost message. This - step may involve reordering and reassembling IP fragments and TCP - segments to produce the original application protocol data unit - (PDU). Such PDUs are analyzed and normalized as needed to support - further processing. - 3. Detection is a two step process. For efficiency, most rules - contain a specific content pattern that can be searched for such - that if no match is found no further processing is necessary. - Upon start up, the rules are compiled into pattern groups such - that a single, parallel search can be done for all patterns in - the group. If any match is found, the full rule is examined - according to the specifics of the signature. - 4. The logging step is where Snort saves any pertinent information - resulting from the earlier steps. More generally, this is where - other actions can be taken as well such as blocking the packet. - -2.5.1. Snort 2 Processing - -The preprocess step in Snort 2 is highly configurable. Arbitrary -preprocessors can be loaded dynamically at startup, configured in -snort.conf, and then executed at runtime. Basically, the -preprocessors are put into a list which is iterated for each packet. -Recent versions have tweaked the list handling some, but the same -basic architecture has allowed Snort 2 to grow from a sniffer, with -no preprocessing, to a full-fledged IPS, with lots of preprocessing. - -While this "list of plugins" approach has considerable flexibility, -it hampers future development when the flow of data from one -preprocessor to the next depends on traffic conditions, a common -situation with advanced features like application identification. In -this case, a preprocessor like HTTP may be extracting and normalizing -data that ultimately is not used, or appID may be repeatedly checking -for data that is just not available. - -Callbacks help break out of the preprocess straitjacket. This is -where one preprocessor supplies another with a function to call when -certain data is available. Snort has started to take this approach to -pass some HTTP and SIP preprocessor data to appID. However, it -remains a peripheral feature and still requires the production of -data that may not be consumed. - -2.5.2. Snort 3 Processing - -One of the goals of Snort 3 is to provide a more flexible framework -for packet processing by implementing an event-driven approach. -Another is to produce data only when needed to minimize expensive -normalizations. However, the basic packet processing provides very -similar functionality. - -The basic processing steps Snort 3 takes are similar to Snort 2 as -seen in the following diagram. The preprocess step employs specific -inspector types instead of a generalized list, but the basic -procedure includes stateless packet decoding, TCP stream reassembly, -and service specific analysis in both cases. (Snort 3 provides hooks -for arbitrary inspectors, but they are not central to basic flow -processing and are not shown.) - -Snort 3 - -However, Snort 3 also provides a more flexible mechanism than -callback functions. By using inspection events, it is possible for an -inspector to supply data that other inspectors can process. This is -known as the observer pattern or publish-subscribe pattern. - -Note that the data is not actually published. Instead, access to the -data is published, and that means that subscribers can access the raw -or normalized version(s) as needed. Normalizations are done only on -the first access, and subsequent accesses get the previously -normalized data. This results in just in time (JIT) processing. - -A basic example of this in action is provided by the extra data_log -plugin. It is a passive inspector, ie it does nothing until it -receives the data it subscribed for (other in the above diagram). By -adding the following to your snort.lua configuration, you will get a -simple URI logger. - -data_log = { key = 'http_raw_uri' } - -Inspection events coupled with pluggable inspectors provide a very -flexible framework for implementing new features. And JIT buffer -stuffers allow Snort to work smarter, not harder. These capabilities -will be leveraged more and more as Snort development continues. - - -2.6. Rules - --------------- - -Rules tell Snort how to detect interesting conditions, such as an -attack, and what to do when the condition is detected. Here is an -example rule: - -alert tcp any any -> 192.168.1.1 80 ( msg:"A ha!"; content:"attack"; sid:1; ) - -The structure is: - -action proto source dir dest ( body ) - -Where: - -action - tells Snort what to do when a rule "fires", ie when the -signature matches. In this case Snort will log the event. It can also -do thing like block the flow when running inline. - -proto - tells Snort what protocol applies. This may be ip, icmp, tcp, -udp, http, etc. - -source - specifies the sending IP address and port, either of which -can be the keyword any, which is a wildcard. - -dir - must be either unidirectional as above or bidirectional -indicated by <>. - -dest - similar to source but indicates the receiving end. - -body - detection and other information contained in parenthesis. - -There are many rule options available to construct as sophisticated a -signature as needed. In this case we are simply looking for the -"attack" in any TCP packet. A better rule might look like this: - -alert http -( - msg:"Gotcha!"; - flow:established, to_server; - http_uri:"attack"; - sid:2; -) - -Note that these examples have a sid option, which indicates the -signature ID. In general rules are specified by gid:sid:rev notation, -where gid is the generator ID and rev is the revision of the rule. By -default, text rules are gid 1 and shared-object (SO) rules are gid 3. -The various components within Snort that generate events have 1XX -gids, for example the decoder is gid 116. You can list the internal -gids and sids with these commands: - -$ snort --list-gids -$ snort --list-builtin - -For details on these and other options, see the reference section. - - -2.7. Pattern Matching - --------------- - -Snort evaluates rules in a two-step process which includes a fast -pattern search and full evaluation of the signature. More details on -this process follow. - -2.7.1. Rule Groups - -When Snort starts or reloads configuration, rules are grouped by -protocol, port and service. For example, all TCP rules using the -HTTP_PORTS variable will go in one group and all service HTTP rules -will go in another group. These rule groups are compiled into -multipattern search engines (MPSE) which are designed to search for -all patterns with just a single pass through a given packet or -buffer. You can select the algorithm to use for fast pattern searches -with search_engine.search_method which defaults to ac_bnfa, which -balances speed and memory. For a faster search at the expense of -significantly more memory, use ac_full. For best performance and -reasonable memory, download the hyperscan source from Intel. - -2.7.2. Fast Patterns - -Fast patterns are content strings that have the fast_pattern option -or which have been selected by Snort automatically to be used as a -fast pattern. Snort will by default choose the longest pattern in the -rule since that is likely to be most unique. That is not always the -case so add fast_pattern to the appropriate content option for best -performance. The ideal fast pattern is one which, if found, is very -likely to result in a rule match. Fast patterns that match frequently -for unrelated traffic will cause Snort to work hard with little to -show for it. - -Certain contents are not eligible to be used as fast patterns. -Specifically, if a content is negated, then if it is also relative to -another content, case sensitive, or has non-zero offset or depth, -then it is not eligible to be used as a fast pattern. - -2.7.3. Rule Evaluation - -For each fast pattern match, the corresponding rule(s) are evaluated -left-to-right. Rule evaluation requires checking each detection -option in a rule and is a fairly costly process which is why fast -patterns are so important. Rule evaluation aborts on the first -non-matching option. - -When rule evaluation takes place, the fast pattern match will -automatically be skipped if possible. Note that this differs from -Snort 2 which provided the fast_pattern:only option to designate such -cases. This is one less thing for the rule writer to worry about. - +Table of Contents ---------------------------------------------------------------------- +1. Help +2. Basic Modules + + 2.1. active + 2.2. alerts + 2.3. attribute_table + 2.4. classifications + 2.5. daq + 2.6. decode + 2.7. detection + 2.8. event_filter + 2.9. event_queue + 2.10. high_availability + 2.11. host_cache + 2.12. host_tracker + 2.13. hosts + 2.14. inspection + 2.15. ips + 2.16. latency + 2.17. memory + 2.18. network + 2.19. output + 2.20. packet_tracer + 2.21. packets + 2.22. payload_injector + 2.23. process + 2.24. profiler + 2.25. rate_filter + 2.26. references + 2.27. rule_state + 2.28. search_engine + 2.29. side_channel + 2.30. snort + 2.31. suppress + 2.32. trace + +3. Codec Modules + + 3.1. arp + 3.2. auth + 3.3. ciscometadata + 3.4. eapol + 3.5. erspan2 + 3.6. erspan3 + 3.7. esp + 3.8. eth + 3.9. fabricpath + 3.10. gre + 3.11. gtp + 3.12. icmp4 + 3.13. icmp6 + 3.14. igmp + 3.15. ipv4 + 3.16. ipv6 + 3.17. llc + 3.18. mpls + 3.19. pbb + 3.20. pgm + 3.21. pppoe + 3.22. tcp + 3.23. token_ring + 3.24. udp + 3.25. vlan + 3.26. wlan + +4. Connector Modules + + 4.1. file_connector + 4.2. tcp_connector + +5. Inspector Modules + + 5.1. appid + 5.2. appid_listener + 5.3. arp_spoof + 5.4. back_orifice + 5.5. binder + 5.6. cip + 5.7. data_log + 5.8. dce_http_proxy + 5.9. dce_http_server + 5.10. dce_smb + 5.11. dce_tcp + 5.12. dce_udp + 5.13. dnp3 + 5.14. dns + 5.15. domain_filter + 5.16. dpx + 5.17. file_id + 5.18. file_log + 5.19. ftp_client + 5.20. ftp_data + 5.21. ftp_server + 5.22. gtp_inspect + 5.23. http2_inspect + 5.24. http_inspect + 5.25. imap + 5.26. mem_test + 5.27. modbus + 5.28. normalizer + 5.29. null_trace_logger + 5.30. packet_capture + 5.31. perf_monitor + 5.32. pop + 5.33. port_scan + 5.34. reputation + 5.35. rna + 5.36. rpc_decode + 5.37. s7commplus + 5.38. sip + 5.39. smtp + 5.40. so_proxy + 5.41. ssh + 5.42. ssl + 5.43. stream + 5.44. stream_file + 5.45. stream_icmp + 5.46. stream_ip + 5.47. stream_tcp + 5.48. stream_udp + 5.49. stream_user + 5.50. telnet + 5.51. wizard + +6. IPS Action Modules + + 6.1. react + 6.2. reject + 6.3. rewrite + +7. IPS Option Modules + + 7.1. ack + 7.2. appids + 7.3. asn1 + 7.4. base64_decode + 7.5. ber_data + 7.6. ber_skip + 7.7. bufferlen + 7.8. byte_extract + 7.9. byte_jump + 7.10. byte_math + 7.11. byte_test + 7.12. cip_attribute + 7.13. cip_class + 7.14. cip_conn_path_class + 7.15. cip_instance + 7.16. cip_req + 7.17. cip_rsp + 7.18. cip_service + 7.19. cip_status + 7.20. classtype + 7.21. content + 7.22. cvs + 7.23. dce_iface + 7.24. dce_opnum + 7.25. dce_stub_data + 7.26. detection_filter + 7.27. dnp3_data + 7.28. dnp3_func + 7.29. dnp3_ind + 7.30. dnp3_obj + 7.31. dsize + 7.32. enable + 7.33. enip_command + 7.34. enip_req + 7.35. enip_rsp + 7.36. file_data + 7.37. file_type + 7.38. flags + 7.39. flow + 7.40. flowbits + 7.41. fragbits + 7.42. fragoffset + 7.43. gid + 7.44. gtp_info + 7.45. gtp_type + 7.46. gtp_version + 7.47. http2_decoded_header + 7.48. http2_frame_header + 7.49. http_client_body + 7.50. http_cookie + 7.51. http_header + 7.52. http_method + 7.53. http_param + 7.54. http_raw_body + 7.55. http_raw_cookie + 7.56. http_raw_header + 7.57. http_raw_request + 7.58. http_raw_status + 7.59. http_raw_trailer + 7.60. http_raw_uri + 7.61. http_stat_code + 7.62. http_stat_msg + 7.63. http_trailer + 7.64. http_true_ip + 7.65. http_uri + 7.66. http_version + 7.67. icmp_id + 7.68. icmp_seq + 7.69. icode + 7.70. id + 7.71. ip_proto + 7.72. ipopts + 7.73. isdataat + 7.74. itype + 7.75. md5 + 7.76. metadata + 7.77. modbus_data + 7.78. modbus_func + 7.79. modbus_unit + 7.80. msg + 7.81. mss + 7.82. pcre + 7.83. pkt_data + 7.84. pkt_num + 7.85. priority + 7.86. raw_data + 7.87. reference + 7.88. regex + 7.89. rem + 7.90. replace + 7.91. rev + 7.92. rpc + 7.93. s7commplus_content + 7.94. s7commplus_func + 7.95. s7commplus_opcode + 7.96. sd_pattern + 7.97. seq + 7.98. service + 7.99. sha256 + 7.100. sha512 + 7.101. sid + 7.102. sip_body + 7.103. sip_header + 7.104. sip_method + 7.105. sip_stat_code + 7.106. so + 7.107. soid + 7.108. ssl_state + 7.109. ssl_version + 7.110. stream_reassemble + 7.111. stream_size + 7.112. tag + 7.113. target + 7.114. tos + 7.115. ttl + 7.116. urg + 7.117. window + 7.118. wscale + +8. Search Engine Modules +9. SO Rule Modules +10. Logger Modules + + 10.1. alert_csv + 10.2. alert_ex + 10.3. alert_fast + 10.4. alert_full + 10.5. alert_json + 10.6. alert_sfsocket + 10.7. alert_syslog + 10.8. alert_talos + 10.9. alert_unixsock + 10.10. log_codecs + 10.11. log_hext + 10.12. log_pcap + 10.13. unified2 + +11. Appendix + + 11.1. Build Options + 11.2. Environment Variables + 11.3. Command Line Options + 11.4. Configuration + 11.5. Counts + 11.6. Generators + 11.7. Builtin Rules + 11.8. Command Set + 11.9. Signals + 11.10. Module Listing + 11.11. Plugin Listing -3. Tutorial --------------------------------------------------------------------- -The section will walk you through building and running Snort. It is -not exhaustive but, once you master this material, you should be able -to figure out more advanced usage. - - -3.1. Dependencies - --------------- - -Required: - - * a compiler that supports the C++14 feature set - * cmake to build from source - * daq from https://github.com/snort3/libdaq for packet IO - * dnet from https://github.com/dugsong/libdnet.git for network - utility functions - * hwloc from https://www.open-mpi.org/projects/hwloc/ for CPU - affinity management - * LuaJIT from http://luajit.org for configuration and scripting - * OpenSSL from https://www.openssl.org/source/ for SHA and MD5 file - signatures, the protected_content rule option, and SSL service - detection - * pcap from http://www.tcpdump.org for tcpdump style logging - * pcre from http://www.pcre.org for regular expression pattern - matching - * pkgconfig from https://www.freedesktop.org/wiki/Software/ - pkg-config/ to locate build dependencies - * zlib from http://www.zlib.net for decompression (>= 1.2.8 - recommended) - -Optional: - - * asciidoc from http://www.methods.co.nz/asciidoc/ to build the - HTML manual - * cpputest from http://cpputest.github.io to run additional unit - tests with make check - * dblatex from http://dblatex.sourceforge.net to build the pdf - manual (in addition to asciidoc) - * flatbuffers from https://google.github.io/flatbuffers/ for - enabling the flatbuffers serialization format - * hyperscan >= 4.4.0 from https://github.com/01org/hyperscan to - build new the regex and sd_pattern rule options and hyperscan - search engine. Hyperscan is large so it recommended to follow - their instructions for building it as a shared library. - * iconv from https://ftp.gnu.org/pub/gnu/libiconv/ for converting - UTF16-LE filenames to UTF8 (usually included in glibc) - * libunwind from https://www.nongnu.org/libunwind/ to attempt to - dump a somewhat readable backtrace when a fatal signal is - received - * lzma >= 5.1.2 from http://tukaani.org/xz/ for decompression of - SWF and PDF files - * safec >= 3.5 from https://github.com/rurban/safeclib/ for runtime - bounds checks on certain legacy C-library calls - * source-highlight from http://www.gnu.org/software/src-highlite/ - to generate the dev guide - * w3m from http://sourceforge.net/projects/w3m/ to build the plain - text manual - * uuid from uuid-dev package for unique identifiers - - -3.2. Building - --------------- - - * Optionally built features are listed in the reference section. - * Create an install path: - - export my_path=/path/to/snorty - mkdir -p $my_path - - * If LibDAQ was installed to a custom, non-system path: - - export PKG_CONFIG_PATH=/libdaq/install/path/lib/pkgconfig:$PKG_CONFIG_PATH - - * Now do one of the following: - - a. To build with cmake and make, run configure_cmake.sh. It will - automatically create and populate a new subdirectory named - build. - - ./configure_cmake.sh --prefix=$my_path - cd build - make -j - make install - ln -s $my_path/conf $my_path/etc - - b. You can also specify a cmake project generator: - - ./configure_cmake.sh --generator=Xcode --prefix=$my_path - - c. Or use ccmake directly to configure and generate from an - arbitrary build directory like one of these: - - ccmake -G Xcode /path/to/Snort++/tree - open snort.xcodeproj - - ccmake -G "Eclipse CDT4 - Unix Makefiles" /path/to/Snort++/tree - run eclipse and do File > Import > Existing Eclipse Project - - * To build with g++ on OS X where clang is installed, do this - first: - - export CXX=g++ - - -3.3. Running - --------------- - -Examples: - - * Get some help: - - $my_path/bin/snort --help - $my_path/bin/snort --help-module suppress - $my_path/bin/snort --help-config | grep thread - - * Examine and dump a pcap: - - $my_path/bin/snort -r - $my_path/bin/snort -L dump -d -e -q -r - - * Verify config, with or w/o 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/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/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/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. - - -3.4. Tips - --------------- - -One of the goals of Snort 3 is to make it easier to configure your -sensor. Here is a summary of tips and tricks you may find useful. - -General Use - - * Snort tries hard not to error out too quickly. It will report - multiple semantic errors. - * Snort always assumes the simplest mode of operation. Eg, you can - omit the -T option to validate the conf if you don’t provide a - packet source. - * Warnings are not emitted unless --warn-* is specified. --warn-all - enables all warnings, and --pedantic makes such warnings fatal. - * You can process multiple sources at one time by using the -z or - --max-threads option. - * To make it easy to find the important data, zero counts are not - output at shutdown. - * Load plugins from the command line with --plugin-path /path/to/ - install/lib. - * You can process multiple sources at one time by using the -z or - --max-threads option. - * Unit tests are configured with --enable-unit-tests. They can then - be run with snort --catch-test [tags]|all. - -Lua Configuration - - * Configure the wizard and default bindings will be created based - on configured inspectors. No need to explicitly bind ports in - this case. - * You can override or add to your Lua conf with the --lua command - line option. - * The Lua conf is a live script that is executed when loaded. You - can add functions, grab environment variables, compute values, - etc. - * You can also rename symbols that you want to disable. For - example, changing normalizer to Xnormalizer (an unknown symbol) - will disable the normalizer. This can be easier than commenting - in some cases. - * By default, symbols unknown to Snort are silently ignored. You - can generate warnings for them with --warn-unknown. To ignore - such symbols, export them in the environment variable - SNORT_IGNORE. - -Writing and Loading Rules - -Snort rules allow arbitrary whitespace. Multi-line rules make it -easier to structure your rule for clarity. There are multiple ways to -add comments to your rules: - - * The # character starts a comment to end of line. In addition, all - lines between #begin and #end are comments. - * The rem option allows you to write a comment that is conveyed - with the rule. - * C style multi-line comments are allowed, which means you can - comment out portions of a rule while testing it out by putting - the options between /* and */. - -There are multiple ways to load rules too: - - * Set ips.rules or ips.include. - * include statements can be used in rules files. - * Use -R to load a rules file. - * Use --stdin-rules with command line redirection. - * Use --lua to specify one or more rules as a command line - argument. - -Output Files - -To make it simple to configure outputs when you run with multiple -packet threads, output files are not explicitly configured. Instead, -you can use the options below to format the paths: - -/[][][] - - * logdir is set with -l and defaults to ./ - * run_prefix is set with --run-prefix else not used - * id# is the packet thread number that writes the file; with one - packet thread, id# (zero) is omitted without --id-zero - * X is / if you use --id-subdir, else _ if id# is used - * name is based on module name that writes the file - * all text mode outputs default to stdout - - -3.5. Help - --------------- - -Snort has several options to get more help: - --? list command line options (same as --help) ---help this overview of help ---help-commands [] output matching commands ---help-config [] output matching config options ---help-counts [] output matching peg counts ---help-limits print the int upper bounds denoted by max* ---help-module output description of given module ---help-modules list all available modules with brief help ---help-plugins list all available plugins with brief help ---help-options [