27.4.5. Output
27.4.5.1. Low Level Logging
Suricata's alert, protocol, and other types of output are built up from a set of low level loggers. These loggers include:
Packet logging (alerts)
Flow logging
Transaction logging (application layer)
File information logging
File data logging (file extraction)
Statistics
These low level logging facilities are used to build up Suricata's logging include EVE, but they can also be hooked into by plugins or applications using Suricata as a library.
Note
At this time only a C API exists to hook into the low level logging functions.
The Suricata source code contains an example plugin demonstrating how to hook into some of these APIs. See https://github.com/OISF/suricata/blob/master/examples/plugins/c-custom-loggers/custom-logger.c.
27.4.5.1.1. Packet Logging
Packet loggers can be registered with the
SCOutputRegisterPacketLogger
function:
/** \brief Register a packet logger.
*
* \param logger_id An ID used to distinguish this logger from others
* while profiling.
* \param name An informational name for this logger. Used only for
* debugging.
* \param LogFunc A function that will be called to log each packet
* that passes the condition test.
* \param ConditionFunc A function to test if the packet should be passed to
* the logging function.
* \param initdata Initialization data that will pass to the
* ThreadInitFunc.
* \param ThreadInitFunc Thread initialization function.
* \param ThreadDeinitFunc Thread de-initialization function.
*
* \retval 0 on success, -1 on failure.
*/
int SCOutputRegisterPacketLogger(LoggerId logger_id, const char *name, PacketLogger LogFunc,
PacketLogCondition ConditionFunc, void *initdata, ThreadInitFunc, ThreadDeinitFunc);
27.4.5.1.2. Flow Logging
Flow loggers can be registered with the SCOutputRegisterFlowLogger
function:
/** \brief Register a flow logger.
*
* \param name An informational name for this logger. Used only for
* debugging.
* \param LogFunc A function that will be called to log each flow.
* \param initdata A pointer to initialization data that will be
* passed the ThreadInit.
* \param ThreadInit Thread initialization callback.
* \param ThreadDeinit Thread de-initialization callback.
*
* \retval 0 on success, -1 on failure.
*/
int SCOutputRegisterFlowLogger(const char *name, FlowLogger LogFunc, void *initdata,
ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);
27.4.5.1.3. Transaction Logging
Transaction logger can be registered with the
SCOutputRegisterTxLogger
function:
Attention
Transaction loggers cannot be registered from a plugin at this time, see https://redmine.openinfosecfoundation.org/issues/7236 for more information.
/** \brief Register a transaction logger.
*
* \param logger_id An ID used to distinguish this logger from others
* while profiling. For transaction logging this is only used for
* some internal state tracking.
*
* \param name An informational name for this logger. Used for
* debugging.
*
* \param alproto The application layer protocol this logger is for,
* for example ALPROTO_DNS.
*
* \param LogFunc A pointer to the logging function.
*
* \param initdata Initialization data that will be provided to the
* ThreadInit callback.
*
* \param tc_log_progress The to_client progress state required for
* the log function to be called.
*
* \param ts_log_progress The to_server progress state required for
* the log function to be called.
*
* \param LogCondition A pointer to a function that will be called
* before the log function to test if the log function should be
* called.
*
* \param ThreadInitFunc Callback a thread initialization function,
* initdata will be provided.
*
* \param ThreadDeinitFunc Callback to a thread de-initialization
* function for cleanup.
*/
int SCOutputRegisterTxLogger(LoggerId id, const char *name, AppProto alproto, TxLogger LogFunc,
void *, int tc_log_progress, int ts_log_progress, TxLoggerCondition LogCondition,
ThreadInitFunc, ThreadDeinitFunc);
27.4.5.1.4. Stream Logging
Stream logging allows for the logging of streaming data such as TCP reassembled data and HTTP body data. The provided log function will be called each time a new chunk of data is available.
Stream loggers can be registered with the
SCOutputRegisterStreamingLogger
function:
/** \brief Register a streaming logger.
*
* \param logger_id An ID to uniquely identify this logger.
*
* \param name An informational name for this logger.
*
* \param LogFunc Pointer to logging function.
*
* \param initdata Initialization data that will be passed the
* ThreadInit.
*
* \param stream_type Type of stream to log, see
* SCOutputStreamingType.
*
* \param ThreadInit Pointer to thread initialization function.
*
* \param ThreadDeinit Pointer to thread de-initialization function.
*/
int SCOutputRegisterStreamingLogger(LoggerId logger_id, const char *name, SCStreamingLogger LogFunc,
void *initdata, enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit,
ThreadDeinitFunc ThreadDeinit);
27.4.5.1.5. File Logging
File loggers can be registered with the SCOutputRegisterFileLogger
function:
/** \brief Register a file logger.
*
* \param logger_id An ID used to distinguish this logger from others
* while profiling.
*
* \param name An informational name for this logger. Used only for
* debugging.
*
* \param LogFunc A function that will be called to log each file to be logged.
*
* \param initdata Initialization data that will pass to the
* ThreadInitFunc.
*
* \param ThreadInitFunc Thread initialization function.
*
* \param ThreadDeinitFunc Thread de-initialization function.
*
* \retval 0 on success, -1 on failure.
*/
int SCOutputRegisterFileLogger(LoggerId id, const char *name, SCFileLogger LogFunc, void *initdata,
ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);
27.4.5.1.6. File-data Logging
File-data loggers can be registered with the
SCOutputRegisterFileDataLogger
function:
/** \brief Register a file-data logger.
*
* \param logger_id An ID used to distinguish this logger from others
* while profiling.
*
* \param name An informational name for this logger. Used only for
* debugging.
*
* \param LogFunc A function that will be called to log each file-data.
*
* \param initdata Initialization data that will pass to the
* ThreadInitFunc.
*
* \param ThreadInitFunc Thread initialization function.
*
* \param ThreadDeinitFunc Thread de-initialization function.
*
* \retval 0 on success, -1 on failure.
*/
int SCOutputRegisterFiledataLogger(LoggerId id, const char *name, SCFiledataLogger LogFunc,
void *initdata, ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);