aucoalesce

Documentation

Overview

Package aucoalesce provides functions to coalesce compound audit messages into a single event and normalize all message types with some common fields.

Index

• func LoadNormalizationConfig(b []byte) (syscalls map[string]*Normalization, recordTypes map[string][]*Normalization, ...)
• func ResolveIDs(event *Event)
• func ResolveIDsFromCaches(event *Event, users UserCache, groups GroupCache)
• type Actor
• type Address
• type AuditEventType
  • func GetAuditEventType(t AuditMessageType) AuditEventType
  • func (t AuditEventType) MarshalText() (text []byte, err error)
  • func (t AuditEventType) String() string
• type Direction
  • func (d Direction) MarshalText() ([]byte, error)
  • func (d Direction) String() string
• type Event
  • func CoalesceMessages(msgs []*auparse.AuditMessage) (*Event, error)
• type File
• type GroupCache
  • func NewGroupCache(expiration time.Duration) GroupCache
  • func (c GroupCache) LookupGID(gid string) string
• type Network
• type Normalization
• type NormalizationConfig
• type Object
• type ObjectMapping
• type Process
  • func (p Process) IsEmpty() bool
• type Strings
  • func (s *Strings) UnmarshalYAML(unmarshal func(interface{}) error) error
• type SubjectMapping
• type Summary
• type User
• type UserCache
  • func NewUserCache(expiration time.Duration) UserCache
  • func (c UserCache) LookupUID(uid string) string

Functions

func LoadNormalizationConfig

func LoadNormalizationConfig(b []byte) (syscalls map[string]*Normalization, recordTypes map[string][]*Normalization, err error)

func ResolveIDs

func ResolveIDs(event *Event)

ResolveIDs translates all uid and gid values to their associated names. Prior to Go 1.9 this requires cgo on Linux. UID and GID values are cached for 60 seconds from the time they are read.

func ResolveIDsFromCaches

func ResolveIDsFromCaches(event *Event, users UserCache, groups GroupCache)

ResolveIDsFromCaches translates all uid and gid values to their associated names using the provided caches. Prior to Go 1.9 this requires cgo on Linux.

Types

type Actor

type Actor struct {
	Primary   string `json:"primary,omitempty"   yaml:"primary,omitempty"`
	Secondary string `json:"secondary,omitempty" yaml:"secondary,omitempty"`
}

type Address

type Address struct {
	Hostname string `json:"hostname,omitempty" yaml:"hostname,omitempty"` // Hostname.
	IP       string `json:"ip,omitempty"       yaml:"ip,omitempty"`       // IPv4 or IPv6 address.
	Port     string `json:"port,omitempty"     yaml:"port,omitempty"`     // Port number.
	Path     string `json:"path,omitempty"     yaml:"path,omitempty"`     // Unix socket path.
}

type AuditEventType

type AuditEventType uint16

AuditEventType is a categorization of a simple or compound audit event.

const (
	EventTypeUnknown AuditEventType = iota
	EventTypeUserspace
	EventTypeSystemServices
	EventTypeConfig
	EventTypeTTY
	EventTypeUserAccount
	EventTypeUserLogin
	EventTypeAuditDaemon
	EventTypeMACDecision
	EventTypeAnomoly
	EventTypeIntegrity
	EventTypeAnomolyResponse
	EventTypeMAC
	EventTypeCrypto
	EventTypeVirt
	EventTypeAuditRule
	EventTypeDACDecision
	EventTypeGroupChange
)

func GetAuditEventType

func GetAuditEventType(t AuditMessageType) AuditEventType

func (AuditEventType) MarshalText

func (t AuditEventType) MarshalText() (text []byte, err error)

func (AuditEventType) String

func (t AuditEventType) String() string

type Direction

type Direction uint8

const (
	IncomingDir Direction = iota + 1
	OutgoingDir
)

func (Direction) MarshalText

func (d Direction) MarshalText() ([]byte, error)

func (Direction) String

func (d Direction) String() string

type Event

type Event struct {
	Timestamp time.Time                `json:"@timestamp"       yaml:"timestamp"`
	Sequence  uint32                   `json:"sequence"         yaml:"sequence"`
	Category  AuditEventType           `json:"category"         yaml:"category"`
	Type      auparse.AuditMessageType `json:"record_type"      yaml:"record_type"`
	Result    string                   `json:"result,omitempty" yaml:"result,omitempty"`
	Session   string                   `json:"session"          yaml:"session"`
	Tags      []string                 `json:"tags,omitempty"   yaml:"tags,omitempty"`

	Summary Summary  `json:"summary"               yaml:"summary"`
	User    User     `json:"user"                  yaml:"user"`
	Process Process  `json:"process,omitempty"     yaml:"process,omitempty"`
	File    *File    `json:"file,omitempty"        yaml:"file,omitempty"`
	Source  *Address `json:"source,omitempty"      yaml:"source,omitempty"`
	Dest    *Address `json:"destination,omitempty" yaml:"destination,omitempty"`
	Net     *Network `json:"network,omitempty"     yaml:"network,omitempty"`

	Data  map[string]string   `json:"data,omitempty"  yaml:"data,omitempty"`
	Paths []map[string]string `json:"paths,omitempty" yaml:"paths,omitempty"`

	Warnings []error `json:"-" yaml:"-"`
}

func CoalesceMessages

func CoalesceMessages(msgs []*auparse.AuditMessage) (*Event, error)

CoalesceMessages combines the given messages into a single event. It assumes that all the messages in the slice have the same timestamp and sequence number. An error is returned is msgs is empty or nil or only contains and EOE (end-of-event) message.

type File

type File struct {
	Path    string            `json:"path,omitempty"    yaml:"path,omitempty"`
	Device  string            `json:"device,omitempty"  yaml:"device,omitempty"`
	Inode   string            `json:"inode,omitempty"   yaml:"inode,omitempty"`
	Mode    string            `json:"mode,omitempty"    yaml:"mode,omitempty"` // Permissions
	UID     string            `json:"uid,omitempty"     yaml:"uid,omitempty"`
	GID     string            `json:"gid,omitempty"     yaml:"gid,omitempty"`
	Owner   string            `json:"owner,omitempty"   yaml:"owner,omitempty"`
	Group   string            `json:"group,omitempty"   yaml:"group,omitempty"`
	SELinux map[string]string `json:"selinux,omitempty" yaml:"selinux,omitempty"` // SELinux labels.
}

type GroupCache

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

GroupCache is a cache of GID to group name.

func NewGroupCache

func NewGroupCache(expiration time.Duration) GroupCache

NewGroupCache returns a new GroupCache. GroupCache is not thread-safe.

func (GroupCache) LookupGID

func (c GroupCache) LookupGID(gid string) string

LookupGID looks up a GID and returns the group associated with it. If no group could be found an empty string is returned. The value will be cached for a minute. This requires cgo on Linux.

type Network

type Network struct {
	Direction Direction `json:"direction" yaml:"direction"`
}

type Normalization

type Normalization struct {
	Subject     SubjectMapping `yaml:"subject"`
	Action      string         `yaml:"action"`
	Object      ObjectMapping  `yaml:"object"`
	How         Strings        `yaml:"how"`
	RecordTypes Strings        `yaml:"record_types"`
	Syscalls    Strings        `yaml:"syscalls"`
	SourceIP    Strings        `yaml:"source_ip"`
	HasFields   Strings        `yaml:"has_fields"`
}

type NormalizationConfig

type NormalizationConfig struct {
	Default        Normalization `yaml:"default"`
	Normalizations []Normalization
}

type Object

type Object struct {
	Type      string `json:"type,omitempty"      yaml:"type,omitempty"`
	Primary   string `json:"primary,omitempty"   yaml:"primary,omitempty"`
	Secondary string `json:"secondary,omitempty" yaml:"secondary,omitempty"`
}

type ObjectMapping

type ObjectMapping struct {
	PrimaryFieldName   Strings `yaml:"primary"`
	SecondaryFieldName Strings `yaml:"secondary"`
	What               string  `yaml:"what"`
	PathIndex          int     `yaml:"path_index"`
}

type Process

type Process struct {
	PID   string   `json:"pid,omitempty"   yaml:"pid,omitempty"`
	PPID  string   `json:"ppid,omitempty"  yaml:"ppid,omitempty"`
	Title string   `json:"title,omitempty" yaml:"title,omitempty"`
	Name  string   `json:"name,omitempty"  yaml:"name,omitempty"` // Comm
	Exe   string   `json:"exe,omitempty"   yaml:"exe,omitempty"`
	CWD   string   `json:"cwd,omitempty"   yaml:"cwd,omitempty"`
	Args  []string `json:"args,omitempty"  yaml:"args,omitempty"`
}

func (Process) IsEmpty

func (p Process) IsEmpty() bool

type Strings

type Strings struct {
	Values []string
}

Strings is a custom type to enable YAML values that can be either a string or a list of strings.

func (*Strings) UnmarshalYAML

func (s *Strings) UnmarshalYAML(unmarshal func(interface{}) error) error

type SubjectMapping

type SubjectMapping struct {
	PrimaryFieldName   Strings `yaml:"primary"`
	SecondaryFieldName Strings `yaml:"secondary"`
}

type Summary

type Summary struct {
	Actor  Actor  `json:"actor"             yaml:"actor"`
	Action string `json:"action,omitempty"  yaml:"action,omitempty"`
	Object Object `json:"object,omitempty"  yaml:"object,omitempty"`
	How    string `json:"how,omitempty"     yaml:"how,omitempty"`
}

type User

type User struct {
	IDs     map[string]string `json:"ids,omitempty"     yaml:"ids,omitempty"`     // Identifying data like auid, uid, euid, suid, fsuid, gid, egid, sgid, fsgid.
	Names   map[string]string `json:"names,omitempty"   yaml:"names,omitempty"`   // Mappings of ID to name (auid -> "root").
	SELinux map[string]string `json:"selinux,omitempty" yaml:"selinux,omitempty"` // SELinux labels.
}

type UserCache

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

UserCache is a cache of UID to username.

func NewUserCache

func NewUserCache(expiration time.Duration) UserCache

NewUserCache returns a new UserCache. UserCache is not thread-safe.

func (UserCache) LookupUID

func (c UserCache) LookupUID(uid string) string

LookupUID looks up a UID and returns the username associated with it. If no username could be found an empty string is returned. The value will be cached for a minute. This requires cgo on Linux.