separate modules by type in doc

diff --git a/.gitignore b/.gitignore
index 03d416d74090bcf3074399a71d94f579918a6a6d..5281308b28a545fc734f465e9f23362961de84b1 100644 (file)
--- 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 450c6acb6a45a8940678a28b86365954cf1c65b4..c66823058b8e67cdc6e50931515c2e91e07c2fce 100644 (file)
--- 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 e38bb53336df616b3dccf16b5ed7295ef72a0305..cd54042bef357761b1ee3e4619a535a05612fd58 100644 (file)
--- 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 9052e900dca75f6e2c4772cfaf49d7b482cc608b..6c0640755d54afd584195f7a7f0213d8bb40aa4e 100644 (file)
--- 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 333dee1ee5169767f84d76421aebfebf5fe07b02..72b55357993de91783457101c238b2ef413ca601 100644 (file)
--- a/src/helpers/markup.cc
+++ b/src/helpers/markup.cc
@@ -19,6 +19,8 @@
 // markup.cc author Russ Combs <rucombs@cisco.com>
 
 #include "markup.h"
+#include <string.h>
+
 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 92d2f80a1fc04eca9e347e244d66d53e25cb41a5..d40d56199cfe373b5410da5da0f2b84ec832ffcf 100644 (file)
--- 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 c2aa22baec7242c416d252af5e8ac789a5fac3b7..c9d3cd4006b4f9fccc5c1bcf17ddd7046d151130 100644 (file)
--- 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 bdcc505285e82895fbc9cb6d5fd1e02a83d88757..d99983c83c94fe5ff2aba277c4957e5be915f11b 100644 (file)
--- 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 d677e1b6567447416f02dd220bedfe8dedd2545c..91ac2a07b495085c30b51c2e16b2f70037b6dba1 100644 (file)
--- 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,
       "[<module prefix>] output matching generators" },
 
-    { "--list-modules", Parameter::PT_IMPLIED, nullptr, nullptr,
-      "list all known modules" },
+    { "--list-modules", Parameter::PT_STRING, "(optional)", nullptr,
+      "[<module type>] 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 37163baf961221e42d14bd551b52c5acc219c041..4c7a61c9fbd5eea0e103cf92bf303b09e13fb556 100644 (file)
--- 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 0990c8e2fd36cb9c4bada96e03d5470e0ae166e4..f3e813e0a0647cba622ad5aa778b4fe8c8b5894d 100644 (file)
--- 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 766012815f7daffcb727611b86d83d50094f84d4..406bbede797658972f38c40c4bbcc4b92e11c21a 100644 (file)
--- 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 f2f9136ea08bd73e0af64e95f347ccba43d9e973..49019cc9aed743063226245bc37bee291a750e61 100644 (file)
--- 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 90e3412aa7cfa6ffb04072ebf93da03c14fc457d..264cd8db0b683c3718a63fc0d07aea6215a89c2d 100644 (file)
--- 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 8cdf04ac7e66725f31a2ebeed078b210e01c6e29..b6ef1f87ff0c6695161e1eba346753ea19fa1c64 100644 (file)
--- 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 fa79bfe0e6021a60dd44b5117cdcfbf9693d1634..c4276ec0491330413b33af96e095444b51198dec 100644 (file)
--- 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 100787dc8c14457bd1095c2aa5b4049c99ae6ead..b3212bad60097bc8871cccc591349226142cff02 100644 (file)
--- 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[] =
 {