process

Documentation

Overview

Package process fetches process and socket information from the operating system. It can find the process owning a network connection.

Index

• Constants
• Variables
• func All() map[int]*Process
• func CleanProcessStorage(activePIDs map[int]struct{})
• func GetPidOfConnection(ctx context.Context, pktInfo *packet.Info) (pid int, connInbound bool, err error)
• func GetProcessGroupID(ctx context.Context, pid int) (int, error)
• func RegisterTagHandler(th TagHandler) error
• func SetDBController(controller *database.Controller)
• type MatchingData
  • func (md *MatchingData) Cmdline() string
  • func (md *MatchingData) Env() map[string]string
  • func (md *MatchingData) MatchingPath() string
  • func (md *MatchingData) Path() string
  • func (md *MatchingData) Tags() []profile.Tag
• type Process
  • func GetNetworkHost(ctx context.Context, remoteIP net.IP) (process *Process, err error)
  • func GetOrFindProcess(ctx context.Context, pid int) (*Process, error)
  • func GetProcessByRequestOrigin(ar *api.Request) (*Process, error)
  • func GetProcessFromStorage(key string) (*Process, bool)
  • func GetProcessWithProfile(ctx context.Context, pid int) (process *Process, err error)
  • func GetProcessesWithProfile(ctx context.Context, profileSource profile.ProfileSource, profileID string, ...) []*Process
  • func GetSystemProcess(ctx context.Context) *Process
  • func GetUnidentifiedProcess(ctx context.Context) *Process
  • func GetUnsolicitedProcess(ctx context.Context) *Process
  • func (p *Process) CreateProfileCallback() *profile.Profile
  • func (p *Process) Delete()
  • func (p *Process) Equal(other *Process) bool
  • func (p *Process) FindProcessGroupLeader(ctx context.Context) error
  • func (p *Process) GetExecHash(algorithm string) (string, error)
  • func (p *Process) GetKey() string
  • func (p *Process) GetLastSeen() int64
  • func (p *Process) GetProfile(ctx context.Context) (changed bool, err error)
  • func (p *Process) GetTag(tagID string) (profile.Tag, bool)
  • func (p *Process) HasValidPID() bool
  • func (p *Process) IsIdentified() bool
  • func (p *Process) IsSystemResolver() bool
  • func (p *Process) Leader() *Process
  • func (p *Process) MatchingData() *MatchingData
  • func (p *Process) Profile() *profile.LayeredProfile
  • func (p *Process) RefetchProfile(ctx context.Context) error
  • func (p *Process) Save()
  • func (p *Process) SetLastSeen(lastSeen int64)
  • func (p *Process) String() string
• type TagDescription
• type TagHandler

Constants

const (
	// SystemProcessID is the PID of the System/Kernel itself.
	SystemProcessID = 0

	// SystemInitID is the PID of the system init process.
	SystemInitID = 1
)

const (
	// UndefinedProcessID is not used by any (virtual) process and signifies that
	// the PID is unset.
	UndefinedProcessID = -1

	// UnidentifiedProcessID is the PID used for outgoing connections that could
	// not be attributed to a PID for any reason.
	UnidentifiedProcessID = -2

	// UnsolicitedProcessID is the PID used for incoming connections that could
	// not be attributed to a PID for any reason.
	UnsolicitedProcessID = -3

	// NetworkHostProcessID is the PID used for requests served to the network.
	NetworkHostProcessID = -255
)

Variables

var (
	CfgOptionEnableProcessDetectionKey = "core/enableProcessDetection"
)

Configuration Keys.

Functions

func All

func All() map[int]*Process

All returns a copy of all process objects.

func CleanProcessStorage

func CleanProcessStorage(activePIDs map[int]struct{})

CleanProcessStorage cleans the storage from old processes.

func GetPidOfConnection

func GetPidOfConnection(ctx context.Context, pktInfo *packet.Info) (pid int, connInbound bool, err error)

GetPidOfConnection returns the PID of the process that owns the described connection. Always returns valid data. Errors are logged and returned for information or special handling purposes.

func GetProcessGroupID

func GetProcessGroupID(ctx context.Context, pid int) (int, error)

GetProcessGroupID returns the process group ID of the given PID.

func RegisterTagHandler

func RegisterTagHandler(th TagHandler) error

RegisterTagHandler registers a tag handler.

func SetDBController

func SetDBController(controller *database.Controller)

SetDBController sets the database controller and allows the package to push database updates on a save. It must be set by the package that registers the "network" database.

Types

type MatchingData

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

MatchingData provides a interface compatible view on the process for profile matching.

func (*MatchingData) Cmdline

func (md *MatchingData) Cmdline() string

Cmdline returns the command line of the process.

func (*MatchingData) Env

func (md *MatchingData) Env() map[string]string

Env returns process.Env.

func (*MatchingData) MatchingPath

func (md *MatchingData) MatchingPath() string

MatchingPath returns process.MatchingPath.

func (*MatchingData) Path

func (md *MatchingData) Path() string

Path returns process.Path.

func (*MatchingData) Tags

func (md *MatchingData) Tags() []profile.Tag

Tags returns process.Tags.

type Process

type Process struct {
	record.Base
	sync.Mutex

	Name     string
	UserID   int
	UserName string
	UserHome string

	Pid       int
	CreatedAt int64

	ParentPid       int
	ParentCreatedAt int64

	LeaderPid int

	Path     string
	ExecName string
	Cwd      string
	CmdLine  string
	FirstArg string
	Env      map[string]string

	// Tags holds extended information about the (virtual) process, which is used
	// to find a profile.
	Tags []profile.Tag
	// MatchingPath holds an alternative binary path that can be used to find a
	// profile.
	MatchingPath string

	// PrimaryProfileID holds the scoped ID of the primary profile.
	PrimaryProfileID string

	FirstSeen int64
	LastSeen  int64
	Error     string // Cache errors

	ExecHashes map[string]string
	// contains filtered or unexported fields
}

A Process represents a process running on the operating system.

func GetNetworkHost

func GetNetworkHost(ctx context.Context, remoteIP net.IP) (process *Process, err error)

GetNetworkHost returns a *Process that represents a host on the network.

func GetOrFindProcess

func GetOrFindProcess(ctx context.Context, pid int) (*Process, error)

GetOrFindProcess returns the process for the given PID.

func GetProcessByRequestOrigin

func GetProcessByRequestOrigin(ar *api.Request) (*Process, error)

GetProcessByRequestOrigin returns the process that initiated the API request ar.

func GetProcessFromStorage

func GetProcessFromStorage(key string) (*Process, bool)

GetProcessFromStorage returns a process from the internal storage.

func GetProcessWithProfile

func GetProcessWithProfile(ctx context.Context, pid int) (process *Process, err error)

GetProcessWithProfile returns the process, including the profile. Always returns valid data. Errors are logged and returned for information or special handling purposes.

func GetProcessesWithProfile

func GetProcessesWithProfile(ctx context.Context, profileSource profile.ProfileSource, profileID string, preferProcessGroupLeader bool) []*Process

GetProcessesWithProfile returns all processes that use the given profile. If preferProcessGroupLeader is set, it returns the process group leader instead, if available.

func GetSystemProcess

func GetSystemProcess(ctx context.Context) *Process

GetSystemProcess returns the special process used for the Kernel.

func GetUnidentifiedProcess

func GetUnidentifiedProcess(ctx context.Context) *Process

GetUnidentifiedProcess returns the special process assigned to non-attributed outgoing connections.

func GetUnsolicitedProcess

func GetUnsolicitedProcess(ctx context.Context) *Process

GetUnsolicitedProcess returns the special process assigned to non-attributed incoming connections.

func (*Process) CreateProfileCallback

func (p *Process) CreateProfileCallback() *profile.Profile

CreateProfileCallback attempts to create a profile on special attributes of the process.

func (*Process) Delete

func (p *Process) Delete()

Delete deletes a process from the storage and propagates the change.

func (*Process) Equal

func (p *Process) Equal(other *Process) bool

Equal returns if the two processes are both identified and have the same PID.

func (*Process) FindProcessGroupLeader

func (p *Process) FindProcessGroupLeader(ctx context.Context) error

FindProcessGroupLeader returns the process that leads the process group. Returns nil when process ID is not valid (or virtual). If the process group leader is found, it is set on the process. If that process does not exist anymore, then the highest existing parent process is returned. If an error occurs, the best match is set.

func (*Process) GetExecHash

func (p *Process) GetExecHash(algorithm string) (string, error)

GetExecHash returns the hash of the executable with the given algorithm.

func (*Process) GetKey

func (p *Process) GetKey() string

GetKey returns the key that is used internally to identify the process. The key consists of the PID and the start time of the process as reported by the system.

func (*Process) GetLastSeen

func (p *Process) GetLastSeen() int64

GetLastSeen returns the unix timestamp when the process was last seen.

func (*Process) GetProfile

func (p *Process) GetProfile(ctx context.Context) (changed bool, err error)

GetProfile finds and assigns a profile set to the process.

func (*Process) GetTag

func (p *Process) GetTag(tagID string) (profile.Tag, bool)

GetTag returns the process tag with the given ID.

func (*Process) HasValidPID

func (p *Process) HasValidPID() bool

HasValidPID returns whether the process has valid PID of an actual process.

func (*Process) IsIdentified

func (p *Process) IsIdentified() bool

IsIdentified returns whether the process has been identified or if it represents some kind of unidentified process.

func (*Process) IsSystemResolver

func (p *Process) IsSystemResolver() bool

IsSystemResolver is a shortcut to check if the process is or belongs to the system resolver and needs special handling.

func (*Process) Leader

func (p *Process) Leader() *Process

Leader returns the process group leader that is attached to the process. This will not trigger a new search for the process group leader, it only returns existing data.

func (*Process) MatchingData

func (p *Process) MatchingData() *MatchingData

MatchingData returns the matching data for the process.

func (*Process) Profile

func (p *Process) Profile() *profile.LayeredProfile

Profile returns the assigned layered profile.

func (*Process) RefetchProfile

func (p *Process) RefetchProfile(ctx context.Context) error

RefetchProfile removes the profile and finds and assigns a new profile.

func (*Process) Save

func (p *Process) Save()

Save saves the process to the internal state and pushes an update.

func (*Process) SetLastSeen

func (p *Process) SetLastSeen(lastSeen int64)

SetLastSeen sets the unix timestamp when the process was last seen.

func (*Process) String

func (p *Process) String() string

String returns a string representation of process.

type TagDescription

type TagDescription struct {
	ID          string
	Name        string
	Description string
}

TagDescription describes a tag.

type TagHandler

type TagHandler interface {
	// Name returns the tag handler name.
	Name() string

	// TagDescriptions returns a list of all possible tags and their description
	// of this handler.
	TagDescriptions() []TagDescription

	// AddTags adds tags to the given process.
	AddTags(p *Process)

	// CreateProfile creates a profile based on the tags of the process.
	// Returns nil to skip.
	CreateProfile(p *Process) *profile.Profile
}

TagHandler is a collection of process tag related interfaces.