filter

Documentation

Overview

Package filter is a separate container for the 'Filter' struct that can be used to target a specific process or one that matches an attribute set.

Index

• Constants
• Variables
• func UnmarshalStream(r data.Reader, f **Filter) error
• type Filter
  • func B(f bool) *Filter
  • func E(s ...string) *Filter
  • func F() *Filter
  • func I(s ...string) *Filter
  • func (f *Filter) Clear() *Filter
  • func (f *Filter) Empty() bool
  • func (Filter) Handle(_ uint32) (uintptr, error)
  • func (Filter) HandleFunc(_ uint32, _ filter) (uintptr, error)
  • func (f Filter) MarshalJSON() ([]byte, error)
  • func (f *Filter) MarshalStream(w data.Writer) error
  • func (f Filter) Select() (uint32, error)
  • func (f Filter) SelectFunc(_ filter) (uint32, error)
  • func (f *Filter) SetElevated(e bool) *Filter
  • func (f *Filter) SetExclude(n ...string) *Filter
  • func (f *Filter) SetFallback(i bool) *Filter
  • func (f *Filter) SetInclude(n ...string) *Filter
  • func (f *Filter) SetPID(p uint32) *Filter
  • func (f *Filter) SetSession(s bool) *Filter
  • func (Filter) Thread(_ uint32) (uintptr, error)
  • func (Filter) ThreadFunc(_ uint32, _ filter) (uintptr, error)
  • func (Filter) Token(_ uint32) (uintptr, error)
  • func (Filter) TokenFunc(_ uint32, _ filter) (uintptr, error)
  • func (f *Filter) UnmarshalJSON(b []byte) error
  • func (f *Filter) UnmarshalStream(r data.Reader) error

Constants

const (
	// True is the 'true' bool value.
	True = boolean(2)
	// False is the 'false' bool value.
	False = boolean(1)
	// Empty represents the absence of a value.
	Empty = boolean(0)
)

Variables

var (
	// Any will attempt to locate a parent process that may be elevated
	// based on the current process permissions.
	//
	// This one will fall back to non-elevated if all checks fail.
	Any = (&Filter{Fallback: true}).SetElevated(true)
	// Random is a Filter that can be used by default to select ANY random
	// process on the target device to be used as the parent process without
	// creating a new Filter struct.
	Random = &Filter{Fallback: false}
)

var ErrNoProcessFound = xerr.Sub("could not find a suitable process", 0x3E)

ErrNoProcessFound is returned by the SetParent* functions on Windows devices when a specified parent could not be found.

Functions

func UnmarshalStream

func UnmarshalStream(r data.Reader, f **Filter) error

UnmarshalStream will attempt to read the Filter data from the supplied Reader and return any errors that may occur.

This function takes a pointer of the Filter pointer so it can fill in any nil or empty Filters with data for a new Filter struct.

Types

type Filter

type Filter struct {
	// Exclude and Include determine the processes that can be included or omitted
	// during process listing. 'Exclude' always takes precedence over 'Include'.
	//
	// Either one being nil or empty means no processes are included/excluded.
	// All matches are case-insensitive.
	Exclude []string
	Include []string
	// PID will attempt to select the PID to be used for the parent.
	// If set to zero, it will be ignored. Values less than 5 are not valid!
	PID uint32
	// Fallback specifies if the opts routine should try again with less constraints
	// than the previous attempt. All attempts will still respect the 'Exclude'
	// and 'Ignore' directives.
	Fallback bool
	// Session can be set to 'True' or 'False' to attempt to target processes that
	// are either in or not in a DWM session environment (ie: in a user desktop
	// [True] or a service context [False]). This value is ignored if set to 'Empty'.
	Session boolean
	// Elevated can be set 'True' or 'False' to attempt to target processes that
	// are in a High/System or Lower integrity context. 'True' will attempt to
	// select elevated processes, while 'False' will select lower integrity or
	// non-elevated processes. If set to 'Empty' or omitted, this will choose
	// any process, regardless of integrity level.
	Elevated boolean
}

Filter is a struct that can be used to set the Parent process for many types of 'Runnable' compatible interfaces.

Each option can be set directly or chained using the function calls which all return the struct for chain usage.

This struct can be serialized into JSON or written using a Stream Marshaler.

func B

func B(f bool) *Filter

B is a shortcut for '&Filter{Fallback: f}'

func E

func E(s ...string) *Filter

E is a shortcut for '&Filter{Exclude: s}'

func F

func F() *Filter

F is a shortcut for 'new(Filter)'

func I

func I(s ...string) *Filter

I is a shortcut for '&Filter{Include: s}'

func (*Filter) Clear

func (f *Filter) Clear() *Filter

Clear clears the Filter settings, except for 'Fallback' and returns itself.

func (*Filter) Empty

func (f *Filter) Empty() bool

Empty will return true if this Filter is nil or unset.

func (Filter) Handle

func (Filter) Handle(_ uint32) (uintptr, error)

Handle will attempt to find a process with the specified Filter options. If a suitable process is found, the Process Handle will be returned. The first argument is the access rights requested, expressed as an uint32.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (Filter) HandleFunc

func (Filter) HandleFunc(_ uint32, _ filter) (uintptr, error)

HandleFunc will attempt to find a process with the specified Filter options. If a suitable process is found, the Process Handle will be returned.

This function allows for a filtering function to be passed along that will be supplied with the ProcessID, if the process is elevated, the process name and process handle. The function supplied should return true if the process passes the filter. The function argument may be nil.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (Filter) MarshalJSON

func (f Filter) MarshalJSON() ([]byte, error)

MarshalJSON will attempt to convert the data in this Filter into the returned JSON byte array.

func (*Filter) MarshalStream

func (f *Filter) MarshalStream(w data.Writer) error

MarshalStream will attempt to write the Filter data to the supplied Writer and return any errors that may occur.

func (Filter) Select

func (f Filter) Select() (uint32, error)

Select will attempt to find a process with the specified Filter options. If a suitable process is found, the Process ID will be returned.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices if a PID is not set.

func (Filter) SelectFunc

func (f Filter) SelectFunc(_ filter) (uint32, error)

SelectFunc will attempt to find a process with the specified Filter options. If a suitable process is found, the Process ID will be returned.

This function allows for a filtering function to be passed along that will be supplied with the ProcessID, if the process is elevated, the process name and process handle. The function supplied should return true if the process passes the filter. The function argument may be nil.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices if a PID is not set.

func (*Filter) SetElevated

func (f *Filter) SetElevated(e bool) *Filter

SetElevated sets the Elevated setting to 'True' or 'False' and returns itself.

func (*Filter) SetExclude

func (f *Filter) SetExclude(n ...string) *Filter

SetExclude sets the Exclusion list and returns itself.

func (*Filter) SetFallback

func (f *Filter) SetFallback(i bool) *Filter

SetFallback sets the Fallback setting and returns itself.

func (*Filter) SetInclude

func (f *Filter) SetInclude(n ...string) *Filter

SetInclude sets the Inclusion list and returns itself.

func (*Filter) SetPID

func (f *Filter) SetPID(p uint32) *Filter

SetPID sets the target PID and returns the Filter struct.

func (*Filter) SetSession

func (f *Filter) SetSession(s bool) *Filter

SetSession sets the Session setting to 'True' or 'False' and returns itself.

func (Filter) Thread

func (Filter) Thread(_ uint32) (uintptr, error)

Thread will attempt to find a process with the specified Filter options. If a suitable process is found, a handle to the first Thread in the Process will be returned. The first argument is the access rights requested, expressed as an uint32.

An 'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (Filter) ThreadFunc

func (Filter) ThreadFunc(_ uint32, _ filter) (uintptr, error)

ThreadFunc will attempt to find a process with the specified Filter options. If a suitable process is found, a handle to the first Thread in the Process will be returned. The first argument is the access rights requested, expressed as an uint32.

This function allows for a filtering function to be passed along that will be supplied with the ProcessID, if the process is elevated, the process name and process handle. The function supplied should return true if the process passes the filter. The function argument may be nil.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (Filter) Token

func (Filter) Token(_ uint32) (uintptr, error)

Token will attempt to find a process with the specified Filter options. If a suitable process is found, the Process Token Handle will be returned. The first argument is the access rights requested, expressed as an uint32.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (Filter) TokenFunc

func (Filter) TokenFunc(_ uint32, _ filter) (uintptr, error)

TokenFunc will attempt to find a process with the specified Filter options. If a suitable process is found, the Process Token Handle will be returned. The first argument is the access rights requested, expressed as an uint32.

This function allows for a filtering function to be passed along that will be supplied with the ProcessID, if the process is elevated, the process name and process handle. The function supplied should return true if the process passes the filter. The function argument may be nil.

An'ErrNoProcessFound' error will be returned if no processes that match the Filter are found.

This function returns 'ErrNoWindows' on non-Windows devices.

func (*Filter) UnmarshalJSON

func (f *Filter) UnmarshalJSON(b []byte) error

UnmarshalJSON will attempt to parse the supplied JSON into this Filter.

func (*Filter) UnmarshalStream

func (f *Filter) UnmarshalStream(r data.Reader) error

UnmarshalStream will attempt to read the Filter data from the supplied Reader and return any errors that may occur.