From: Russ Combs Date: Fri, 10 Oct 2014 19:26:37 +0000 (-0400) Subject: separate modules by type in doc X-Git-Tag: 3.0.0-233~1388^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=279ade8dbe5d9766077e8bb969955793a1765728;p=thirdparty%2Fsnort3.git separate modules by type in doc --- diff --git a/.gitignore b/.gitignore index 03d416d74..5281308b2 100644 --- a/.gitignore +++ b/.gitignore @@ -37,6 +37,13 @@ doc/snort_manual.html doc/snort_manual.pdf doc/snort_manual.tgz doc/snort_manual.xml +doc/basic.txt +doc/codec.txt +doc/data.txt +doc/inspector.txt +doc/ips_action.txt +doc/ips_option.txt +doc/logger.txt extra/rule.xxd extra/snort_examples-1.0.tar.gz install-sh diff --git a/ChangeLog b/ChangeLog index 450c6acb6..c66823058 100644 --- a/ChangeLog +++ b/ChangeLog @@ -23,6 +23,7 @@ -- commented out ppm, profile, and normalizer in snort.lua since these require special conditions to be enabled -- added --dump-defaults to get Lua formatted defaults +-- split doc for modules into separate sections by type 123 -- refactored documentation diff --git a/doc/Makefile.am b/doc/Makefile.am index e38bb5333..cd54042be 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -8,10 +8,20 @@ commands.txt \ config.txt \ gids.txt \ help.txt \ -modules.txt \ options.txt \ signals.txt \ -version.txt +version.txt \ +basic.txt \ +codec.txt \ +data.txt \ +inspector.txt \ +ips_action.txt \ +ips_option.txt \ +logger.txt + +# currently no modules for these +#search_engine.txt +#so_rule.txt unbuilt_sources = \ snort_manual.txt \ @@ -68,11 +78,51 @@ gids.txt: $(snort) help.txt: $(snort) $(snort) --help > $@ -modules.txt: $(snort) - for m in `$(snort) --list-modules` ; do \ +basic.txt: $(snort) + for m in `$(snort) --list-modules basic` ; do \ $(snort) --markup --help-module $$m ; \ done > $@ +codec.txt: $(snort) + for m in `$(snort) --list-modules codec` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +data.txt: $(snort) + for m in `$(snort) --list-modules data` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +inspector.txt: $(snort) + for m in `$(snort) --list-modules inspector` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +ips_action.txt: $(snort) + for m in `$(snort) --list-modules ips_action` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +ips_option.txt: $(snort) + for m in `$(snort) --list-modules ips_action` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +logger.txt: $(snort) + for m in `$(snort) --list-modules logger` ; do \ + $(snort) --markup --help-module $$m ; \ + done > $@ + +#search_engine.txt: $(snort) +# for m in `$(snort) --list-modules search_engine` ; do \ +# $(snort) --markup --help-module $$m ; \ +# done > $@ + +#so_rule.txt: $(snort) +# for m in `$(snort) --list-modules so_rule` ; do \ +# $(snort) --markup --help-module $$m ; \ +# done > $@ + options.txt: $(snort) $(snort) --markup --help-options | sort > $@ diff --git a/doc/snort_manual.txt b/doc/snort_manual.txt index 9052e900d..6c0640755 100644 --- a/doc/snort_manual.txt +++ b/doc/snort_manual.txt @@ -22,9 +22,73 @@ include::tips.txt[] include::differences.txt[] -== Modules +== Basic Modules -include::modules.txt[] +Internal modules which are plugins are termed "basic". These include +configuration for core processing. + +include::basic.txt[] + +== Codec Modules + +Codec is short for coder / decoder. These modules are used for basic +protocol decoding, anomaly detection, and construction of active responses. + +include::codec.txt[] + +== Data Modules + +Data modules are adjunct configurations for use with certain inspectors. + +include::data.txt[] + +== Inspector Modules + +These modules perform a variety of functions, including analysis of +protocols beyond basic decoding. + +include::inspector.txt[] + +== IPS Action Modules + +IPS actions allow you to perform custom actions when events are generated. +Unlike loggers, these are invoked before thresholding and can be used to +control external agents. + +include::ips_action.txt[] + +== IPS Option Modules + +IPS options are the building blocks of IPS rules. + +include::ips_option.txt[] + +== Search Engine Modules + +Search engines perform 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. Releated configuration +is done with the basic detection module. + +//// +include::search_engine.txt[] +//// + +== SO Rule Modules + +SO rules are dynamic rules that require custom coding to perform detection +not possible with the existing rule options. These rules typically do not +have associated modules. + +//// +include::so_rule.txt[] +//// + +== Logger Modules + +All output of events and packets is done by Loggers. + +include::logger.txt[] == Reference diff --git a/src/helpers/markup.cc b/src/helpers/markup.cc index 333dee1ee..72b553579 100644 --- a/src/helpers/markup.cc +++ b/src/helpers/markup.cc @@ -19,6 +19,8 @@ // markup.cc author Russ Combs #include "markup.h" +#include + using namespace std; bool Markup::enabled = false; @@ -26,8 +28,16 @@ bool Markup::enabled = false; void Markup::enable(bool e) { enabled = e; } -const char* Markup::head() -{ return enabled ? "=== " : ""; } +const char* Markup::head(unsigned level) +{ + static const char* hn = "========== "; + unsigned max = strlen(hn); + + if ( level >= max ) + level = max - 1; + + return enabled ? hn+max-level-1 : ""; +} const char* Markup::item() { return enabled ? "* " : ""; } diff --git a/src/helpers/markup.h b/src/helpers/markup.h index 92d2f80a1..d40d56199 100644 --- a/src/helpers/markup.h +++ b/src/helpers/markup.h @@ -28,7 +28,7 @@ class Markup public: static void enable(bool = true); - static const char* head(); + static const char* head(unsigned level = 1); static const char* item(); static const char* emphasis_on(); diff --git a/src/main/help.cc b/src/main/help.cc index c2aa22bae..c9d3cd400 100644 --- a/src/main/help.cc +++ b/src/main/help.cc @@ -182,7 +182,7 @@ static void show_help(SnortConfig* sc, const char* val, HelpType ht) InspectorManager::dump_buffers(); break; case HT_LST: - ModuleManager::list_modules(); + ModuleManager::list_modules(val); break; case HT_PLG: PluginManager::list_plugins(); diff --git a/src/main/modules.cc b/src/main/modules.cc index bdcc50528..d99983c83 100644 --- a/src/main/modules.cc +++ b/src/main/modules.cc @@ -354,7 +354,7 @@ static const Parameter profile_params[] = }; static const char* profile_help = - "configure profiling of rules and/or modules"; + "configure profiling of rules and/or modules (requires --enable-perf-profiling)"; class ProfileModule : public Module { diff --git a/src/main/snort_module.cc b/src/main/snort_module.cc index d677e1b65..91ac2a07b 100644 --- a/src/main/snort_module.cc +++ b/src/main/snort_module.cc @@ -277,8 +277,8 @@ static const Parameter s_params[] = { "--list-gids", Parameter::PT_STRING, "(optional)", nullptr, "[] output matching generators" }, - { "--list-modules", Parameter::PT_IMPLIED, nullptr, nullptr, - "list all known modules" }, + { "--list-modules", Parameter::PT_STRING, "(optional)", nullptr, + "[] list all known modules of given type" }, { "--list-plugins", Parameter::PT_IMPLIED, nullptr, nullptr, "list all known plugins" }, diff --git a/src/managers/module_manager.cc b/src/managers/module_manager.cc index 37163baf9..4c7a61c9f 100644 --- a/src/managers/module_manager.cc +++ b/src/managers/module_manager.cc @@ -657,12 +657,26 @@ void ModuleManager::reset_errors() unsigned ModuleManager::get_errors() { return s_errors; } -void ModuleManager::list_modules() +void ModuleManager::list_modules(const char* s) { + PlugType pt = s ? PluginManager::get_type(s) : PT_MAX; s_modules.sort(comp_mods); + unsigned c = 0; for ( auto* p : s_modules ) - LogMessage("%s\n", p->mod->get_name()); + { + if ( + !s || !*s || + (p->api && p->api->type == pt) || + (!p->api && !strcmp(s, "basic")) + ) + { + LogMessage("%s\n", p->mod->get_name()); + c++; + } + } + if ( !c ) + cout << "no match" << endl; } void ModuleManager::show_modules() @@ -709,7 +723,7 @@ void ModuleManager::show_module(const char* name) if ( strcmp(m->get_name(), name) ) continue; - cout << endl << Markup::head() << Markup::sanitize(name) << endl << endl; + cout << endl << Markup::head(3) << Markup::sanitize(name) << endl << endl; if ( const char* h = m->get_help() ) cout << endl << "What: " << Markup::sanitize(h) << endl; diff --git a/src/managers/module_manager.h b/src/managers/module_manager.h index 0990c8e2f..f3e813e0a 100644 --- a/src/managers/module_manager.h +++ b/src/managers/module_manager.h @@ -37,7 +37,7 @@ public: static Module* get_module(const char*); static const char* get_current_module(); - static void list_modules(); + static void list_modules(const char* = nullptr); static void dump_modules(); static void show_modules(); diff --git a/src/managers/plugin_manager.cc b/src/managers/plugin_manager.cc index 766012815..406bbede7 100644 --- a/src/managers/plugin_manager.cc +++ b/src/managers/plugin_manager.cc @@ -110,6 +110,15 @@ static Symbol symbols[PT_MAX] = }; #endif +PlugType PluginManager::get_type(const char* s) +{ + for ( int i = 0; i < PT_MAX; i++ ) + if ( !strcmp(s, symbols[i].name) ) + return (PlugType)i; + + return PT_MAX; +} + const char* PluginManager::get_type_name(PlugType pt) { if ( pt >= PT_MAX ) diff --git a/src/managers/plugin_manager.h b/src/managers/plugin_manager.h index f2f9136ea..49019cc9a 100644 --- a/src/managers/plugin_manager.h +++ b/src/managers/plugin_manager.h @@ -51,8 +51,10 @@ public: static void dump_plugins(); static void release_plugins(); - static const BaseApi* get_api(PlugType, const char* name); + static PlugType get_type(const char*); static const char* get_type_name(PlugType); + + static const BaseApi* get_api(PlugType, const char* name); static const char* get_current_plugin(); static void instantiate(const BaseApi*, Module*, SnortConfig*); diff --git a/src/network_inspectors/port_scan/ps_module.h b/src/network_inspectors/port_scan/ps_module.h index 90e3412aa..264cd8db0 100644 --- a/src/network_inspectors/port_scan/ps_module.h +++ b/src/network_inspectors/port_scan/ps_module.h @@ -29,10 +29,10 @@ #include "main/thread.h" #define PS_NAME "port_scan" -#define PS_HELP "port scan detection" +#define PS_HELP "port scan inspector; also configure port_scan_global" #define PSG_NAME "port_scan_global" -#define PSG_HELP "shared settings for port_scan inspectors" +#define PSG_HELP "shared settings for port_scan inspectors for use with port_scan" extern THREAD_LOCAL SimpleStats spstats; extern THREAD_LOCAL ProfileStats psPerfStats; diff --git a/src/service_inspectors/ftp_telnet/ftp_module.cc b/src/service_inspectors/ftp_telnet/ftp_module.cc index 8cdf04ac7..b6ef1f87f 100644 --- a/src/service_inspectors/ftp_telnet/ftp_module.cc +++ b/src/service_inspectors/ftp_telnet/ftp_module.cc @@ -29,10 +29,10 @@ using namespace std; #define FTP_SERVER "ftp_server" static const char* ftp_client_help = - "FTP client configuration module"; + "FTP client configuration module for use with ftp_server"; static const char* ftp_server_help = - "main FTP module"; + "main FTP module; ftp_client should also be configured"; //------------------------------------------------------------------------- // client stuff diff --git a/src/service_inspectors/http_inspect/hi_module.cc b/src/service_inspectors/http_inspect/hi_module.cc index fa79bfe0e..c4276ec04 100644 --- a/src/service_inspectors/http_inspect/hi_module.cc +++ b/src/service_inspectors/http_inspect/hi_module.cc @@ -138,7 +138,7 @@ static const RuleMap hi_global_rules[] = }; static const char* hi_global_help = - "http inspector global configuration and client rules"; + "http inspector global configuration and client rules for use with http_server"; HttpInspectModule::HttpInspectModule() : Module(GLOBAL_KEYWORD, hi_global_help, hi_global_params) @@ -421,7 +421,7 @@ static const RuleMap hi_server_rules[] = }; static const char* hi_server_help = - "http inspection and server rules"; + "http inspection and server rules; also configure http_inpsect"; HttpServerModule::HttpServerModule() : Module(SERVER_KEYWORD, hi_server_help, hi_server_params) diff --git a/src/time/ppm_module.cc b/src/time/ppm_module.cc index 100787dc8..b3212bad6 100644 --- a/src/time/ppm_module.cc +++ b/src/time/ppm_module.cc @@ -29,7 +29,6 @@ #include "main/snort_config.h" #include "main/snort.h" - //------------------------------------------------------------------------- // ppm attributes //------------------------------------------------------------------------- @@ -38,8 +37,7 @@ static const char* s_name = "ppm"; static const char* s_help = - "packet and rule latency monitoring and control"; - + "packet and rule latency monitoring and control (requires --enable-ppm)"; static const Parameter s_params[] = {