Documentation ¶
Overview ¶
Package 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.
Index ¶
- Constants
- func ParseNetlinkError(netlinkData []byte) error
- type AuditClient
- func (c *AuditClient) AddRule(rule []byte) error
- func (c *AuditClient) Close() error
- func (c *AuditClient) DeleteRule(rule []byte) error
- func (c *AuditClient) DeleteRules() (int, error)
- func (c *AuditClient) GetRules() ([][]byte, 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) SetFailure(fm FailureMode, wm WaitMode) error
- func (c *AuditClient) SetPID(wm WaitMode) error
- func (c *AuditClient) SetRateLimit(perSecondLimit uint32, wm WaitMode) error
- func (c *AuditClient) WaitForPendingACKs() error
- type AuditStatus
- type AuditStatusMask
- type FailureMode
- type NetlinkClient
- type NetlinkParser
- type NetlinkReceiver
- type NetlinkSendReceiver
- type NetlinkSender
- type RawAuditMessage
- type Reassembler
- type Stream
- type WaitMode
Constants ¶
const ( AuditGet uint16 = iota + 1000 AuditSet )
Audit command and control message types.
const ( NetlinkGroupNone = iota // Group 0 not used NetlinkGroupReadLog // "best effort" read only socket )
Netlink groups.
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 )
Variables ¶
This section is empty.
Functions ¶
func ParseNetlinkError ¶
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 // contains filtered or unexported fields }
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 NewMulticastAuditClient ¶ added in v0.0.6
func NewMulticastAuditClient(resp io.Writer) (*AuditClient, error)
NewMulticastAuditClient creates a new AuditClient that binds to the multicast socket subscribes to the audit group. The process should have the CAP_AUDIT_READ capability to use this. This audit client should not be used for command and control. 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) AddRule ¶ added in v0.0.4
func (c *AuditClient) AddRule(rule []byte) error
AddRule adds the given rule to the kernel's audit rule list.
func (*AuditClient) Close ¶
func (c *AuditClient) Close() error
Close closes the AuditClient and frees any associated resources.
func (*AuditClient) DeleteRule ¶ added in v0.0.4
func (c *AuditClient) DeleteRule(rule []byte) error
DeleteRule deletes the given rule (specified in binary format).
func (*AuditClient) DeleteRules ¶ added in v0.0.4
func (c *AuditClient) DeleteRules() (int, error)
DeleteRules deletes all rules.
func (*AuditClient) GetRules ¶ added in v0.0.4
func (c *AuditClient) GetRules() ([][]byte, error)
GetRules returns a list of audit rules (in binary format).
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) SetFailure ¶ added in v0.0.4
func (c *AuditClient) SetFailure(fm FailureMode, wm WaitMode) error
SetFailure sets the action that the kernel will perform when the backlog limit is reached or when it encounters an error and cannot proceed.
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.
func (*AuditClient) WaitForPendingACKs ¶ added in v0.0.7
func (c *AuditClient) WaitForPendingACKs() error
WaitForPendingACKs waits for acknowledgements messages for operations executed with a WaitMode of NoWait. Such ACK messages are expected in the same order as the operations have been performed. If it receives an error, it is returned and no further ACKs are processed.
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 FailureMode ¶ added in v0.0.4
type FailureMode uint32
FailureMode defines the kernel's behavior on critical errors.
const ( // SilentOnFailure ignores errors. SilentOnFailure FailureMode = 0 // LogOnFailure logs errors using printk. LogOnFailure // PanicOnFailure causes a kernel panic on error. PanicOnFailure )
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, groups uint32, 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 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 { Type auparse.AuditMessageType Data []byte // RawData is backed by the read buffer so make a copy. }
RawAuditMessage is a raw audit message received from the kernel.
type Reassembler ¶ added in v0.0.2
type Reassembler struct {
// contains filtered or unexported fields
}
Reassembler combines related messages in to an event based on their timestamp and sequence number. It handles messages that may be have been received out of order or are interleaved. Reassembler is concurrency-safe.
The Reassembler uses callbacks (see Stream interface) to notify the user of completed messages. Callbacks for reassembled events will occur in order of sequence number unless a late message is received that falls outside of the sequences held in memory.
func NewReassembler ¶ added in v0.0.2
NewReassembler returns a new Reassembler. maxInFlight controls the maximum number of events (based on timestamp + sequence) that are buffered. timeout controls how long the Reassembler waits for an EOE message (end-of-event) before evicting the event. And stream receives the callbacks for completed events and lost events.
func (*Reassembler) Close ¶ added in v0.0.2
func (r *Reassembler) Close() error
Close flushes any cached events and closes the Reassembler.
func (*Reassembler) Maintain ¶ added in v0.0.2
func (r *Reassembler) Maintain() error
Maintain performs maintenance on the cached message. It can be called periodically to evict timed-out events. It returns a non-nil error if the Reassembler has been closed.
func (*Reassembler) Push ¶ added in v0.0.2
func (r *Reassembler) Push(typ auparse.AuditMessageType, rawData []byte) error
Push pushes a new audit message into the Reassembler. This is a convenence function that handles calling auparse.Parse() to extract the message's timestamp and sequence number. If parsing fails then an error will be returned. See PushMessage.
func (*Reassembler) PushMessage ¶ added in v0.0.2
func (r *Reassembler) PushMessage(msg *auparse.AuditMessage)
PushMessage pushes a new AuditMessage message into the Reassembler. Callbacks may be triggered as a result.
type Stream ¶ added in v0.0.2
type Stream interface { // ReassemblyComplete notifies that a complete group of events has been // received and provides those events. ReassemblyComplete(msgs []*auparse.AuditMessage) // EventsLost notifies that some events were lost. This is based on gaps // in the sequence numbers of received messages. Lost events can be caused // by a slow receiver or because the kernel is configured to rate limit // events. EventsLost(count int) }
Stream is implemented by the user of the Reassembler to handle reassembled audit data.
Directories ¶
Path | Synopsis |
---|---|
Package aucoalesce provides functions to coalesce compound audit messages into a single event and normalize all message types with some common fields.
|
Package aucoalesce provides functions to coalesce compound audit messages into a single event and normalize all message types with some common fields. |
Package auparse is a pure Go audit log parsing library.
|
Package auparse is a pure Go audit log parsing library. |
cmd
|
|
audit
audit is an example that receives audit messages from the kernel and outputs them to stdout.
|
audit is an example that receives audit messages from the kernel and outputs them to stdout. |
flags
Package flags provides parsing of audit rules as specified using CLI flags in accordance to the man page for auditctl (from the auditd userspace tools).
|
Package flags provides parsing of audit rules as specified using CLI flags in accordance to the man page for auditctl (from the auditd userspace tools). |