ceflog

README

ceflog

Common Event Format Logger

about

The ArcSight Common Event Format (CEF) can be used to emit audit logs in a format which threat analysis and monitoring tools are able to ingest. There doesn't seem to be a de-facto specification online for CEF but if you search for CEF log you will find redistributions.

usage

The library is modeled as a logger rather than a sink which can be plugged into other logging libraries. This is because you only want to log audit-worthy events rather than logging everything. This would typically be tuned by adjusting the level (debug, info, warn, error, etc.) of a log message. This will not work in this case because some of the audit events you want to emit are not errors.

This library does not append syslog headers onto the message. You should ensure that your syslog forwarder adds these.

logger := ceflog.New(w, "vendor", "product", "version")

logger.LogEvent(
    "auth.new",
    "User login",
    ceflog.Sev(0),
    ceflog.Ext("dst", "127.0.0.1"),
)

More complete documentation can be found in the GoDoc.

Documentation

Index

• type Extension
  • func Ext(pairs ...string) Extension
  • func (e Extension) String() string
• type Logger
  • func New(w io.Writer, vendor, product, version string) *Logger
  • func (l *Logger) LogEvent(signature, name string, sev Severity, ext Extension)
• type Pair
• type Severity
  • func Sev(s int) Severity

Types

type Extension

type Extension []Pair

An Extension is the part of the event which can contain extra metadata to be added to the log. It should not be created without using the Ext function.

func Ext

func Ext(pairs ...string) Extension

Ext creates an extension which can be added to a log event. It takes a pairwise list of repeated key-values. CEF defines a specific set of valid keys. This library does not check for their validity.

func (Extension) String

func (e Extension) String() string

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger can be used to log events in the Common Event Format to an io.Writer.

func New

func New(w io.Writer, vendor, product, version string) *Logger

New creates a new Logger which logs to the provided io.Writer.

func (*Logger) LogEvent

func (l *Logger) LogEvent(signature, name string, sev Severity, ext Extension)

LogEvent emits a new audit event to the log.

type Pair

type Pair struct {
	Key   string
	Value string
}

A Pair is a single piece of metadata which can be added to the event. It should never be directly used by the user.

type Severity

type Severity int

Severity represents the severity level of logged events.

func Sev

func Sev(s int) Severity

Sev converts an integer into a Severity level. CEF only allows severity levels between 0 and 10. If the input is less than 0 then it will be clamped to 0. If the input is greater than 10 then it will be clamped to 10.