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 HardcodeGroups(groups ...user.Group)
• func HardcodeUsers(users ...user.User)
• func LoadNormalizationConfig(b []byte) (syscalls map[string]*Normalization, recordTypes map[string][]*Normalization, ...)
• func ResolveIDs(event *Event)
• func ResolveIDsFromCaches(event *Event, users, groups *EntityCache)
• 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 ECSEntity
• type ECSEntityData
• type ECSEvent
• type ECSFieldMapping
• type ECSFields
• type ECSMapping
• type EntityCache
  • func NewGroupCache(expiration time.Duration) *EntityCache
  • func NewUserCache(expiration time.Duration) *EntityCache
  • func (c *EntityCache) LookupID(uid string) string
  • func (c *EntityCache) LookupName(name string) string
• type Event
  • func CoalesceMessages(msgs []*auparse.AuditMessage) (*Event, error)
• type File
• 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

Functions

func HardcodeGroups

func HardcodeGroups(groups ...user.Group)

HardcodeGroups is useful for injecting values for testing.

func HardcodeUsers

func HardcodeUsers(users ...user.User)

HardcodeUsers is useful for injecting values for testing.

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, groups *EntityCache)

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
	EventTypeAnomaly
	EventTypeIntegrity
	EventTypeAnomalyResponse
	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 ECSEntity

type ECSEntity struct {
	ECSEntityData `yaml:",inline"`
	Effective     ECSEntityData `json:"effective" yaml:"effective"`
	Target        ECSEntityData `json:"target" yaml:"target"`
	Changes       ECSEntityData `json:"changes" yaml:"changes"`
}

type ECSEntityData

type ECSEntityData struct {
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	ID   string `json:"id,omitempty" yaml:"id,omitempty"`
}

type ECSEvent

type ECSEvent struct {
	Kind     string   `json:"kind,omitempty" yaml:"kind,omitempty"`
	Category []string `json:"category,omitempty" yaml:"category,omitempty"`
	Type     []string `json:"type,omitempty" yaml:"type,omitempty"`
	Outcome  string   `json:"outcome,omitempty" yaml:"outcome,omitempty"`
}

ECSEvent contains ECS-specific categorization fields

type ECSFieldMapping

type ECSFieldMapping struct {
	From readReference  `yaml:"from" json:"from"`
	To   writeReference `yaml:"to" json:"to"`
}

type ECSFields

type ECSFields struct {
	Event ECSEvent      `json:"event" yaml:"event"`
	User  ECSEntity     `json:"user" yaml:"user"`
	Group ECSEntityData `json:"group" yaml:"group"`
}

type ECSMapping

type ECSMapping struct {
	Kind     string            `yaml:"kind"`
	Category Strings           `yaml:"category"`
	Type     Strings           `yaml:"type"`
	Mappings []ECSFieldMapping `yaml:"mappings"`
}

type EntityCache

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

EntityCache is a cache of IDs and usernames.

func NewGroupCache

func NewGroupCache(expiration time.Duration) *EntityCache

NewGroupCache returns a new EntityCache to resolve groups. EntityCache is thread-safe.

func NewUserCache

func NewUserCache(expiration time.Duration) *EntityCache

NewUserCache returns a new EntityCache to resolve users. EntityCache is thread-safe.

func (*EntityCache) LookupID

func (c *EntityCache) LookupID(uid string) string

LookupID looks up an UID/GID and returns the user/group name associated with it. If no name could be found an empty string is returned. The value will be cached for a minute.

func (*EntityCache) LookupName

func (c *EntityCache) LookupName(name string) string

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

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"`

	ECS ECSFields `json:"ecs" yaml:"ecs"`

	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 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"` // Apply the normalization if all fields are present.
	ECS         ECSMapping     `yaml:"ecs"`
}

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.
}