Merge pull request #2311 in SNORT/snort3 from ~OSERHIIE/snort3:trace_logger_inspector...

Squashed commit of the following:

commit 1e5c3cb1704f6119c84b4eb38a7a9b903c99d13f
Author: Oleksandr Serhiienko <oserhiie@cisco.com>
Date:   Wed Jul 8 23:17:54 2020 +0300

    doc: update extending.txt about TraceLogger plugin

commit 6d22ce349ddb432eef50c32b7d5d0844346a3ac9
Author: Oleksandr Serhiienko <oserhiie@cisco.com>
Date:   Fri Jul 3 11:07:16 2020 +0300

    trace: add support for extending TraceLogger as a passive inspector plugin

    Changelist:

        * extend installed headers list for 'trace'
        * rename trace log files
        * extend TraceApi to handle external plugins
        * update dev_notes.txt and docs (Snort 3 Manual)

diff --git a/doc/extending.txt b/doc/extending.txt
index c7413e9850d243ef81bd64d8b30db2825f4c88ac..dde8f14c5281ed625c6908905e46004678d56eb7 100644 (file)
--- a/doc/extending.txt
+++ b/doc/extending.txt
@@ -69,6 +69,8 @@ executed when:
 * IT_PROBE - process all packets after all the above (e.g. perf_monitor,
   port_scan)
 
+* IT_PASSIVE - for configuration only or data consuming
+
 
 === Codecs
 
@@ -254,6 +256,41 @@ Action plugins specify a builtin action in the API which is used to
 determine verdict.  (Conversely, builtin actions don't have an associated
 plugin function.)
 
+
+=== Trace Loggers
+
+The Trace Loggers print trace messages. They can be implemented as inspector
+plugins.
+
+The first step is creating a custom logger by inheriting from the Snort
+TraceLogger class. The following is an example TraceLogger.
+
+    class FooLogger : public TraceLogger
+    {
+    public:
+        void log(const char*, const char*, uint8_t, const char*, const Packet*) override
+        { printf("%s%s\n", "Foo", "Bar"); }
+    };
+
+To instantiate logger objects it's needed to create a logger factory derived
+from the Snort TraceLoggerFactory class.
+
+    class FooFactory : public TraceLoggerFactory
+    {
+    public:
+        TraceLogger* instantiate() override
+        { return new FooLogger(); }
+    };
+
+Once the Factory is created, Inspector and appropriate Module are needed.
+*Inspector::configure()* must initialize the logger factory.
+
+    bool FooInspector::configure(SnortConfig* sc) override
+    {
+        return TraceApi::override_logger_factory(sc, new FooFactory());
+    }
+
+
 === Piglet Test Harness
 
 In order to assist with plugin development, an experimental mode called "piglet" mode

diff --git a/src/trace/CMakeLists.txt b/src/trace/CMakeLists.txt
index 23426f4eb534a18cd721974939ca1c247d659739..e3bd32d065b7e7b6391429af78d8a2c81940c43e 100644 (file)
--- a/src/trace/CMakeLists.txt
+++ b/src/trace/CMakeLists.txt
@@ -1,6 +1,7 @@
 set ( INCLUDES
     trace.h
     trace_api.h
+    trace_logger.h
 )
 
 set ( TRACE_SOURCES
@@ -8,9 +9,8 @@ set ( TRACE_SOURCES
     trace_api.cc
     trace_config.cc
     trace_config.h
-    trace_log.cc
-    trace_log.h
-    trace_log_base.h
+    trace_loggers.cc
+    trace_loggers.h
     trace_module.cc
     trace_module.h
     trace_parser.cc

diff --git a/src/trace/dev_notes.txt b/src/trace/dev_notes.txt
index 4138096d6526025a1d473c188a1ae48459046a68..b7e73987e2d65860bdd9bb3b955b9cf596fc127b 100644 (file)
--- a/src/trace/dev_notes.txt
+++ b/src/trace/dev_notes.txt
@@ -6,8 +6,8 @@ This directory contains the trace logger framework.
     is created per each packet thread and one for the main thread. The logging configuration
     happens in the module. The logger factory is used to init/cleanup loggers.
 
-    Include "trace_log_base.h" to get TraceLogger base class.
-    Derived loggers placed into "trace_log.h/trace_log.cc".
+    Include "trace_logger.h" to get TraceLogger base class.
+    Built-in loggers are defined in "trace_loggers.h/trace_loggers.cc".
 
 * TraceLoggerFactory
 
@@ -15,8 +15,8 @@ This directory contains the trace logger framework.
     thread. One factory instance exists which used to init/cleanup loggers and placed
     into TraceConfig. The factory object instantiates in the module due to configuration.
 
-    Include "trace_log_base.h" to get TraceLoggerFactory base class and template function
-    to create particular objects. Derived factories placed into "trace_log.h/trace_log.cc".
+    Include "trace_logger.h" to get TraceLoggerFactory base class and template function
+    to create particular objects. Built-in factories are defined in "trace_loggers.h/trace_loggers.cc".
 
 * TraceConfig
 
@@ -85,7 +85,15 @@ This directory contains the trace logger framework.
     TraceConfig should be configured in SnortConfig before TraceApi init.
 
     To create specific TraceLogger/TraceLoggerFactory pair just inherit base classes placed
-    into "trace_log_base.h" and init TraceConfig with a new factory during configuration.
+    into "trace_logger.h" and init TraceConfig with a new factory during configuration.
+
+* Extending the trace logger framework with TraceLogger plugins
+
+    It's possible to create a trace logger as an inspector plugin to handle a custom logic of trace
+    messages printing. The workflow here is to implement the custom logger and logger factory by
+    inheriting from the Snort TraceLogger and TraceLoggerFactory classes, put them into a separate
+    plugin, and call TraceApi::override_logger_factory() during the plugin configuration to
+    initialize the framework with the custom logger factory.
 
 * Disabling packet constraints matching
 

diff --git a/src/trace/trace_api.cc b/src/trace/trace_api.cc
index 4a8da6d0368fe348c2134a9b05732500d2753bfe..c55fb2e604e32887a946d4fcebde7139ab9c0569 100644 (file)
--- a/src/trace/trace_api.cc
+++ b/src/trace/trace_api.cc
@@ -24,12 +24,13 @@
 #include "trace_api.h"
 
 #include "framework/packet_constraints.h"
+#include "main/snort.h"
 #include "main/snort_config.h"
 #include "main/thread.h"
 #include "protocols/packet.h"
 
 #include "trace_config.h"
-#include "trace_log_base.h"
+#include "trace_logger.h"
 
 using namespace snort;
 
@@ -74,6 +75,23 @@ void TraceApi::thread_reinit(const TraceConfig* trace_config)
     trace_config->setup_module_trace();
 }
 
+bool TraceApi::override_logger_factory(SnortConfig* sc, TraceLoggerFactory* factory)
+{
+    if ( !sc or !sc->trace_config or !factory )
+        return false;
+
+    delete sc->trace_config->logger_factory;
+    sc->trace_config->logger_factory = factory;
+
+    if ( !Snort::is_reloading() )
+    {
+        delete g_trace_logger;
+        g_trace_logger = sc->trace_config->logger_factory->instantiate();
+    }
+
+    return true;
+}
+
 void TraceApi::log(const char* log_msg, const char* name,
     uint8_t log_level, const char* trace_option, const Packet* p)
 {

diff --git a/src/trace/trace_api.h b/src/trace/trace_api.h
index 39836ba7c2e0e5eea5e58a4ca623c63d43e5dbee..c5b2d42525ab4f48464267c406bec6a9b283b714 100644 (file)
--- a/src/trace/trace_api.h
+++ b/src/trace/trace_api.h
@@ -29,6 +29,9 @@ class TraceConfig;
 namespace snort
 {
 struct Packet;
+struct SnortConfig;
+
+class TraceLoggerFactory;
 
 class SO_PUBLIC TraceApi
 {
@@ -37,6 +40,10 @@ public:
     static void thread_reinit(const TraceConfig* tc);
     static void thread_term();
 
+    // This method will change an ownership of the passed TraceLoggerFactory
+    // from the caller to the passed SnortConfig
+    static bool override_logger_factory(SnortConfig*, TraceLoggerFactory*);
+
     static void log(const char* log_msg, const char* name,
         uint8_t log_level, const char* trace_option, const Packet* p);
     static void filter(const Packet& p);

diff --git a/src/trace/trace_config.cc b/src/trace/trace_config.cc
index 1c9d2db6f09628391f3decc0e76dac9f6ad6ee98..b0761afb8280c136eb22429bc66cab8304d02501 100644 (file)
--- a/src/trace/trace_config.cc
+++ b/src/trace/trace_config.cc
@@ -29,7 +29,7 @@
 #include "framework/packet_constraints.h"
 #include "managers/module_manager.h"
 
-#include "trace_log_base.h"
+#include "trace_logger.h"
 
 using namespace snort;
 

diff --git a/src/trace/trace_log_base.h b/src/trace/trace_logger.h
similarity index 90%
rename from src/trace/trace_log_base.h
rename to src/trace/trace_logger.h
index adc9fbded92b763880d064371afd288c0b2a0308..e9a22d0e38b299d20a5a9b570cd5ed20f6da9b9d 100644 (file)
--- a/src/trace/trace_log_base.h
+++ b/src/trace/trace_logger.h
@@ -15,10 +15,10 @@
 // with this program; if not, write to the Free Software Foundation, Inc.,
 // 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //--------------------------------------------------------------------------
-// trace_log_base.h author Oleksandr Serhiienko <oserhiie@cisco.com>
+// trace_logger.h author Oleksandr Serhiienko <oserhiie@cisco.com>
 
-#ifndef TRACE_LOG_BASE_H
-#define TRACE_LOG_BASE_H
+#ifndef TRACE_LOGGER_H
+#define TRACE_LOGGER_H
 
 #include <cstdint>
 
@@ -44,5 +44,5 @@ public:
 };
 }
 
-#endif // TRACE_LOG_BASE_H
+#endif // TRACE_LOGGER_H
 

diff --git a/src/trace/trace_log.cc b/src/trace/trace_loggers.cc
similarity index 96%
rename from src/trace/trace_log.cc
rename to src/trace/trace_loggers.cc
index 6f52714a009431a7cafe0f38c73d2aed7b9b04d4..269953d0ba0e7ebf2022f5377973ce007a9e4442 100644 (file)
--- a/src/trace/trace_log.cc
+++ b/src/trace/trace_loggers.cc
@@ -15,13 +15,13 @@
 // with this program; if not, write to the Free Software Foundation, Inc.,
 // 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //--------------------------------------------------------------------------
-// trace_log.cc author Oleksandr Serhiienko <oserhiie@cisco.com>
+// trace_loggers.cc author Oleksandr Serhiienko <oserhiie@cisco.com>
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
 
-#include "trace_log.h"
+#include "trace_loggers.h"
 
 #include <cstdio>
 #include <syslog.h>

diff --git a/src/trace/trace_log.h b/src/trace/trace_loggers.h
similarity index 91%
rename from src/trace/trace_log.h
rename to src/trace/trace_loggers.h
index 34096ee0cb542b98d345e17803a5251df6ae493d..ab3c42108b144518484930c3d4ef03061a6e462f 100644 (file)
--- a/src/trace/trace_log.h
+++ b/src/trace/trace_loggers.h
@@ -15,12 +15,12 @@
 // with this program; if not, write to the Free Software Foundation, Inc.,
 // 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //--------------------------------------------------------------------------
-// trace_log.h author Oleksandr Serhiienko <oserhiie@cisco.com>
+// trace_loggers.h author Oleksandr Serhiienko <oserhiie@cisco.com>
 
-#ifndef TRACE_LOG_H
-#define TRACE_LOG_H
+#ifndef TRACE_LOGGERS_H
+#define TRACE_LOGGERS_H
 
-#include "trace_log_base.h"
+#include "trace_logger.h"
 
 //-----------------------------------------------
 //  Logger factories
@@ -46,5 +46,5 @@ public:
     snort::TraceLogger* instantiate() override;
 };
 
-#endif // TRACE_LOG_H
+#endif // TRACE_LOGGERS_H
 

diff --git a/src/trace/trace_module.cc b/src/trace/trace_module.cc
index abe6feb38ba292090ca2bd1ea93cfe8a28703f5d..68f8e63684da9d8790831b3d0bf74633c3627285 100644 (file)
--- a/src/trace/trace_module.cc
+++ b/src/trace/trace_module.cc
@@ -30,7 +30,7 @@
 #include "managers/module_manager.h"
 
 #include "trace_config.h"
-#include "trace_log.h"
+#include "trace_loggers.h"
 #include "trace_parser.h"
 #include "trace_swap.h"