libaudit

README

go-libaudit

go-libaudit is a library for Go (golang) for communicating with the Linux Audit Framework. The Linux Audit Framework provides system call auditing in the kernel and logs the events to user-space using netlink sockets. This library facilitates user-space applications that want to receive audit events.

Installation and Usage

Package documentation can be found on GoDoc.

Installation can be done with a normal go get:

$ go get github.com/elastic/go-libaudit

go-libaudit has two example applications that you can use to try the library. The first is audit which registers to receive audit events from the kernel and outputs the data it receives to stdout. The system's auditd process should be stopped first.

$ go install github.com/elastic/go-libaudit/cmd/audit
$ sudo $GOPATH/bin/audit -d -format=json

The second is auparse which parses the log files from the Linux auditd process.

$ go install github.com/elastic/go-libaudit/cmd/auparse
$ sudo cat /var/log/audit/audit.log | auparse | jq .
{
  "@timestamp": "2017-03-31 22:08:25.96 +0000 UTC",
  "a0": "4",
  "a1": "7f808e0c4408",
  "a2": "10",
  "a3": "0",
  "arch": "x86_64",
  "auid": "4294967295",
  "comm": "ntpd",
  "egid": "38",
  "euid": "38",
  "exe": "/usr/sbin/ntpd",
  "exit": "0",
  "fsgid": "38",
  "fsuid": "38",
  "gid": "38",
  "items": "0",
  "pid": "1106",
  "ppid": "1",
  "raw_msg": "audit(1490998105.960:595907): arch=c000003e syscall=42 success=yes exit=0 a0=4 a1=7f808e0c4408 a2=10 a3=0 items=0 ppid=1 pid=1106 auid=4294967295 uid=38 gid=38 euid=38 suid=38 fsuid=38 egid=38 sgid=38 fsgid=38 tty=(none) ses=4294967295 comm=\"ntpd\" exe=\"/usr/sbin/ntpd\" subj=system_u:system_r:ntpd_t:s0 key=(null)",
  "record_type": "SYSCALL",
  "sequence": "595907",
  "ses": "4294967295",
  "sgid": "38",
  "subj": "system_u:system_r:ntpd_t:s0",
  "success": "yes",
  "suid": "38",
  "syscall": "connect",
  "tty": "(none)",
  "uid": "38"
}

Documentation

Index

• Constants
• func ParseNetlinkError(netlinkData []byte) error
• type AuditClient
  • func NewAuditClient(resp io.Writer) (*AuditClient, error)
  • func (c *AuditClient) Close() error
  • func (c *AuditClient) GetStatus() (*AuditStatus, error)
  • func (c *AuditClient) Receive(nonBlocking bool) (*RawAuditMessage, error)
  • func (c *AuditClient) SetBacklogLimit(limit uint32, wm WaitMode) error
  • func (c *AuditClient) SetEnabled(enabled bool, wm WaitMode) error
  • func (c *AuditClient) SetPID(wm WaitMode) error
  • func (c *AuditClient) SetRateLimit(perSecondLimit uint32, wm WaitMode) error
• type AuditStatus
• type AuditStatusMask
• type NetlinkClient
  • func NewNetlinkClient(proto int, readBuf []byte, resp io.Writer) (*NetlinkClient, error)
  • func (c *NetlinkClient) Close() error
  • func (c *NetlinkClient) Receive(nonBlocking bool, p NetlinkParser) ([]syscall.NetlinkMessage, error)
  • func (c *NetlinkClient) Send(msg syscall.NetlinkMessage) (uint32, error)
• type NetlinkErrno
  • func (e NetlinkErrno) Error() string
• type NetlinkParser
• type NetlinkReceiver
• type NetlinkSendReceiver
• type NetlinkSender
• type RawAuditMessage
• type WaitMode

Constants

const (
	AuditGet uint16 = iota + 1000
	AuditSet
)

Audit command and control message types.

const (
	// AuditMessageMaxLength is the maximum length of an audit message (data
	// portion of a NetlinkMessage).
	// https://github.com/linux-audit/audit-userspace/blob/990aa27ccd02f9743c4f4049887ab89678ab362a/lib/libaudit.h#L435
	AuditMessageMaxLength = 8970
)

Functions

func ParseNetlinkError

func ParseNetlinkError(netlinkData []byte) error

ParseNetlinkError parses the errno from the data section of a syscall.NetlinkMessage. If netlinkData is less than 4 bytes an error describing the problem will be returned.

Types

type AuditClient

type AuditClient struct {
	Netlink NetlinkSendReceiver
}

AuditClient is a client for communicating with the Linux kernels audit interface over netlink.

func NewAuditClient

func NewAuditClient(resp io.Writer) (*AuditClient, error)

NewAuditClient creates a new AuditClient. The resp parameter is optional. If provided resp will receive a copy of all data read from the netlink socket. This is useful for debugging purposes.

func (*AuditClient) Close

func (c *AuditClient) Close() error

Close closes the AuditClient and frees any associated resources.

func (*AuditClient) GetStatus

func (c *AuditClient) GetStatus() (*AuditStatus, error)

GetStatus returns the current status of the kernel's audit subsystem.

func (*AuditClient) Receive

func (c *AuditClient) Receive(nonBlocking bool) (*RawAuditMessage, error)

Receive reads an audit message from the netlink socket. If you are going to use the returned message then you should make a copy of the raw data before calling receive again because the raw data is backed by the read buffer.

func (*AuditClient) SetBacklogLimit

func (c *AuditClient) SetBacklogLimit(limit uint32, wm WaitMode) error

SetBacklogLimit sets the queue length for audit events awaiting transfer to the audit daemon. The default value is 64 which can potentially be overrun by bursts of activity. When the backlog limit is reached, the kernel consults the failure_flag to see what action to take.

func (*AuditClient) SetEnabled

func (c *AuditClient) SetEnabled(enabled bool, wm WaitMode) error

SetEnabled is used to control whether or not the audit system is active. When the audit system is enabled (enabled set to 1), every syscall will pass through the audit system to collect information and potentially trigger an event.

func (*AuditClient) SetPID

func (c *AuditClient) SetPID(wm WaitMode) error

SetPID sends a netlink message to the kernel telling it the PID of the client that should receive audit messages. https://github.com/linux-audit/audit-userspace/blob/990aa27ccd02f9743c4f4049887ab89678ab362a/lib/libaudit.c#L432-L464

func (*AuditClient) SetRateLimit

func (c *AuditClient) SetRateLimit(perSecondLimit uint32, wm WaitMode) error

SetRateLimit will set the maximum number of messages that the kernel will send per second. This can be used to throttle the rate if systems become unresponsive. Of course the trade off is that events will be dropped. The default value is 0, meaning no limit.

type AuditStatus

type AuditStatus struct {
	Mask            AuditStatusMask // Bit mask for valid entries.
	Enabled         uint32          // 1 = enabled, 0 = disabled
	Failure         uint32          // Failure-to-log action.
	PID             uint32          // PID of auditd process.
	RateLimit       uint32          // Messages rate limit (per second).
	BacklogLimit    uint32          // Waiting messages limit.
	Lost            uint32          // Messages lost.
	Backlog         uint32          // Messages waiting in queue.
	FeatureBitmap   uint32          // Bitmap of kernel audit features (previously to 3.19 it was the audit api version number).
	BacklogWaitTime uint32          // Message queue wait timeout.
}

AuditStatus is a status message and command and control message exchanged between the kernel and user-space. https://github.com/linux-audit/audit-kernel/blob/v4.7/include/uapi/linux/audit.h#L413-L427

type AuditStatusMask

type AuditStatusMask uint32

AuditStatusMask is a bitmask used to convey the fields used in AuditStatus. https://github.com/linux-audit/audit-kernel/blob/v4.7/include/uapi/linux/audit.h#L318-L325

const (
	AuditStatusEnabled AuditStatusMask = 1 << iota
	AuditStatusFailure
	AuditStatusPID
	AuditStatusRateLimit
	AuditStatusBacklogLimit
	AuditStatusBacklogWaitTime
)

Mask types for AuditStatus.

type NetlinkClient

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

NetlinkClient is a generic client for sending and receiving netlink messages.

func NewNetlinkClient

func NewNetlinkClient(proto int, readBuf []byte, resp io.Writer) (*NetlinkClient, error)

NewNetlinkClient creates a new NetlinkClient. It creates a socket and binds it. readBuf is an optional byte buffer used for reading data from the socket. The size of the buffer limits the maximum message size the can be read. If no buffer is provided one will be allocated using the OS page size. resp is optional and can be used to receive a copy of all bytes read from the socket (this is useful for debugging).

The returned NetlinkClient must be closed with Close() when finished.

func (*NetlinkClient) Close

func (c *NetlinkClient) Close() error

Close closes the netlink client's raw socket.

func (*NetlinkClient) Receive

func (c *NetlinkClient) Receive(nonBlocking bool, p NetlinkParser) ([]syscall.NetlinkMessage, error)

Receive receives data from the netlink socket and uses the provided parser to convert the raw bytes to NetlinkMessages. See NetlinkReceiver docs.

func (*NetlinkClient) Send

func (c *NetlinkClient) Send(msg syscall.NetlinkMessage) (uint32, error)

Send sends a netlink message and returns the sequence number used in the message and an error if it occurred. If the PID is not set then the value will be populated automatically (recommended).

type NetlinkErrno

type NetlinkErrno uint32

NetlinkErrno represent the error code contained in a netlink message of type NLMSG_ERROR.

const (
	NLE_SUCCESS NetlinkErrno = iota
	NLE_FAILURE
	NLE_INTR
	NLE_BAD_SOCK
	NLE_AGAIN
	NLE_NOMEM
	NLE_EXIST
	NLE_INVAL
	NLE_RANGE
	NLE_MSGSIZE
	NLE_OPNOTSUPP
	NLE_AF_NOSUPPORT
	NLE_OBJ_NOTFOUND
	NLE_NOATTR
	NLE_MISSING_ATTR
	NLE_AF_MISMATCH
	NLE_SEQ_MISMATCH
	NLE_MSG_OVERFLOW
	NLE_MSG_TRUNC
	NLE_NOADDR
	NLE_SRCRT_NOSUPPORT
	NLE_MSG_TOOSHORT
	NLE_MSGTYPE_NOSUPPORT
	NLE_OBJ_MISMATCH
	NLE_NOCACHE
	NLE_BUSY
	NLE_PROTO_MISMATCH
	NLE_NOACCESS
	NLE_PERM
	NLE_PKTLOC_FILE
	NLE_PARSE_ERR
	NLE_NODEV
	NLE_IMMUTABLE
	NLE_DUMP_INTR
	NLE_ATTRSIZE
)

Netlink error codes.

func (NetlinkErrno) Error

func (e NetlinkErrno) Error() string

type NetlinkParser

type NetlinkParser func([]byte) ([]syscall.NetlinkMessage, error)

NetlinkParser parses the raw bytes read from the netlink socket into netlink messages.

type NetlinkReceiver

type NetlinkReceiver interface {
	Receive(nonBlocking bool, p NetlinkParser) ([]syscall.NetlinkMessage, error)
}

NetlinkReceiver receives data from the netlink socket and uses the provided parser to convert the raw bytes to NetlinkMessages. For most uses cases syscall.ParseNetlinkMessage should be used. If nonBlocking is true then instead of blocking when no data is available, EWOULDBLOCK is returned.

type NetlinkSendReceiver

type NetlinkSendReceiver interface {
	io.Closer
	NetlinkSender
	NetlinkReceiver
}

NetlinkSendReceiver combines the Send and Receive into one interface.

type NetlinkSender

type NetlinkSender interface {
	Send(msg syscall.NetlinkMessage) (uint32, error)
}

NetlinkSender sends a netlink message and returns the sequence number used in the message and an error if it occurred.

type RawAuditMessage

type RawAuditMessage struct {
	MessageType uint16
	RawData     []byte // RawData is backed by the read buffer so make a copy.
}

RawAuditMessage is a raw audit message received from the kernel.

type WaitMode

type WaitMode uint8

WaitMode is a flag to control the behavior of methods that abstract asynchronous communication for the caller.

const (
	// WaitForReply mode causes a call to wait for a reply message.
	WaitForReply WaitMode = iota + 1
	// NoWait mode causes a call to return without waiting for a reply message.
	NoWait
)