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);