From: Bhagya Tholpady (bbantwal) Date: Thu, 16 Jul 2020 01:19:40 +0000 (+0000) Subject: Merge pull request #2311 in SNORT/snort3 from ~OSERHIIE/snort3:trace_logger_inspector... X-Git-Tag: 3.0.2-3~22 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b423765b42d08ee038815694e092df3de7ec1322;p=thirdparty%2Fsnort3.git Merge pull request #2311 in SNORT/snort3 from ~OSERHIIE/snort3:trace_logger_inspector_plugin to master Squashed commit of the following: commit 1e5c3cb1704f6119c84b4eb38a7a9b903c99d13f Author: Oleksandr Serhiienko Date: Wed Jul 8 23:17:54 2020 +0300 doc: update extending.txt about TraceLogger plugin commit 6d22ce349ddb432eef50c32b7d5d0844346a3ac9 Author: Oleksandr Serhiienko 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 c7413e985..dde8f14c5 100644 --- 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 23426f4eb..e3bd32d06 100644 --- 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 4138096d6..b7e73987e 100644 --- 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 4a8da6d03..c55fb2e60 100644 --- 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 39836ba7c..c5b2d4252 100644 --- 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 1c9d2db6f..b0761afb8 100644 --- 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 adc9fbded..e9a22d0e3 100644 --- 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 +// trace_logger.h author Oleksandr Serhiienko -#ifndef TRACE_LOG_BASE_H -#define TRACE_LOG_BASE_H +#ifndef TRACE_LOGGER_H +#define TRACE_LOGGER_H #include @@ -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 6f52714a0..269953d0b 100644 --- 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 +// trace_loggers.cc author Oleksandr Serhiienko #ifdef HAVE_CONFIG_H #include "config.h" #endif -#include "trace_log.h" +#include "trace_loggers.h" #include #include 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 34096ee0c..ab3c42108 100644 --- 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 +// trace_loggers.h author Oleksandr Serhiienko -#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 abe6feb38..68f8e6368 100644 --- 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"