handle

Documentation

Index

• Constants
• func CloseTimeout() error
• func Duplicate(h handle.Handle, pid uint32, access handle.DuplicateAccess) (handle.Handle, error)
• func FormatKey(key string) (registry.Key, string)
• func GetAlpcPort(h handle.Handle) (*htypes.AlpcPortInfo, error)
• func GetHandleWithTimeout(handle handle.Handle, timeout uint32) (string, error)
• func GetMutant(h handle.Handle) (*htypes.MutantInfo, error)
• func GetShortName(typ string) string
• func QueryName(handle handle.Handle, typ string, withTimeout bool) (string, htypes.Meta, error)
• func QueryType(handle handle.Handle) (string, error)
• type CreateCallback
• type DestroyCallback
• type ObjectTypeStore
  • func NewObjectTypeStore() ObjectTypeStore
• type SnapshotBuildCompleted
• type Snapshotter
  • func NewFromKcap(handles []htypes.Handle) Snapshotter
  • func NewSnapshotter(config *config.Config, fn SnapshotBuildCompleted) Snapshotter
• type SnapshotterMock
  • func (s *SnapshotterMock) FindByObject(object uint64) (htypes.Handle, bool)
  • func (s *SnapshotterMock) FindHandles(pid uint32) ([]htypes.Handle, error)
  • func (s *SnapshotterMock) GetSnapshot() []htypes.Handle
  • func (s *SnapshotterMock) RegisterCreateCallback(fn CreateCallback)
  • func (s *SnapshotterMock) RegisterDestroyCallback(fn DestroyCallback)
  • func (s *SnapshotterMock) Remove(kevt *kevent.Kevent) error
  • func (s *SnapshotterMock) Write(kevt *kevent.Kevent) error

Constants

const (
	// ALPCPort represents the ALPC (Advanced Local Procedure Call) object ports
	ALPCPort = "ALPC Port"
	// Directory designates directory objects. They exist only within the object manager scope and do not correspond to any directory on the disk.
	Directory = "Directory"
	// EtwRegistration represents the ETW registration object
	EtwRegistration = "EtwRegistration"
	// EtwConsumer represents the ETW consumer object
	EtwConsumer = "EtwConsumer"
	// Event denotest the event object
	Event = "Event"
	// File designates file handles (e.g. pipe, device, mailslot)
	File = "File"
	// Key represents the registry key object
	Key = "Key"
	// Job represents the job object
	Job = "Job"
	// WaitCompletionPacket is the wait completion packet object
	WaitCompletionPacket = "WaitCompletionPacket"
	// IRTimer is the IR timer object
	IRTimer = "IRTimer"
	// TpWorkerFactory represents the thread pool worker factory object
	TpWorkerFactory = "TpWorkerFactory"
	// IoCompletion represents the IO completion object
	IoCompletion = "IoCompletion"
	// Thread is the thread object
	Thread = "Thread"
	// Semaphore represents the semaphore object
	Semaphore = "Semaphore"
	// Section represents the section object
	Section = "Section"
	// Mutant represents the mutant object
	Mutant = "Mutant"
	// Desktop represents the desktop object
	Desktop = "Desktop"
	// WindowStation represents the window station object
	WindowStation = "WindowStation"
	// Token represents the token object
	Token = "Token"
	// UserApcReserve represents the user APC reserve object
	UserApcReserve = "UserApcReserve"
	// Process represents the process object
	Process = "Process"
	// SymbolicLink represents the symbolic link object
	SymbolicLink = "SymbolicLink"
	// Driver represents the device driver object
	Driver = "Driver"
	// Unknown is the unknown handle object
	Unknown = "Unknown"
)

Functions

func CloseTimeout

func CloseTimeout() error

CloseTimeout releases handle timeut resources.

func Duplicate

func Duplicate(h handle.Handle, pid uint32, access handle.DuplicateAccess) (handle.Handle, error)

Duplicate duplicates the handle in the caller process's address space.

func FormatKey

func FormatKey(key string) (registry.Key, string)

FormatKey produces a root,key tuple from registry native key name.

func GetAlpcPort

func GetAlpcPort(h handle.Handle) (*htypes.AlpcPortInfo, error)

GetAlpcPort get ALPC port information for the specified ALPC handle and process id.

func GetHandleWithTimeout

func GetHandleWithTimeout(handle handle.Handle, timeout uint32) (string, error)

GetHandleWithTimeout is in charge of resolving handle names on handle instances that are under the risk of producing a deadlock, and thus hanging the caller thread. To prevent this kind of unwanted scenarios, deadlock aware timeout calls into `NtQueryObject` in a separate native thread. The thread is reused across invocations as it is blocked waiting to be signaled by an event, but the query thread also signals back the main thread after completion of the `NtQueryObject` call. If the query thread doesn't notify the main thread after a prudent timeout, then the query thread is killed. Subsequent calls for handle name resolution will recreate the thread in case of it not being alive.

func GetMutant

func GetMutant(h handle.Handle) (*htypes.MutantInfo, error)

GetMutant gets the information about specified mutant handle.

func GetShortName

func GetShortName(typ string) string

GetShortName returns the short name for the handle type.

func QueryName

func QueryName(handle handle.Handle, typ string, withTimeout bool) (string, htypes.Meta, error)

QueryName gets the name of the underlying handle reference and extra metadata if it is available.

func QueryType

func QueryType(handle handle.Handle) (string, error)

QueryType returns the type of the specified handle.

Types

type CreateCallback

type CreateCallback func(pid uint32, handle htypes.Handle)

CreateCallback defines the function that is triggered when new handle is conceived

type DestroyCallback

type DestroyCallback func(pid uint32, num handle.Handle)

DestroyCallback defines the function signature that is fired upon handle's destruction

type ObjectTypeStore

type ObjectTypeStore interface {
	FindByID(id uint8) string
	RegisterType(id uint8, typ string)
	TypeNames() []string
}

ObjectTypeStore holds all object type names as exposed by the Object Manager. The store represents a efficient way of resolving object type indices to human-friendly names.

func NewObjectTypeStore

func NewObjectTypeStore() ObjectTypeStore

NewObjectTypeStore creates a new object store instance.

type SnapshotBuildCompleted

type SnapshotBuildCompleted func(total uint64, withName uint64)

SnapshotBuildCompleted is the function type for snapshot completed signal

type Snapshotter

type Snapshotter interface {
	// Write updates the snapshotter state by storing a new entry for the inbound create handle event. It also notifies
	// the registered callback that a new handle has been created.
	Write(kevt *kevent.Kevent) error
	// Remove destroys the handle state for the specified handle object. The removal callback is triggered when an item
	// is deleted from the store.
	Remove(kevt *kevent.Kevent) error
	// FindHandles returns a list of all known handles for the specified process identifier.
	FindHandles(pid uint32) ([]htypes.Handle, error)
	// FindByObject returns the handle for the given handle object reference.
	FindByObject(object uint64) (htypes.Handle, bool)
	// RegisterCreateCallback registers a function that's triggered when new handle is created.
	RegisterCreateCallback(fn CreateCallback)
	// RegisterDestroyCallback registers a function that's called when existing handle is disposed.
	RegisterDestroyCallback(fn DestroyCallback)
	// GetSnapshot returns all the handles present in the snapshotter state.
	GetSnapshot() []htypes.Handle
}

Snapshotter keeps the system-wide snapshot of allocated handles always when handle kernel events are enabled or supported on the target system. It also provides facilities for obtaining a list of handles pertaining to the specific process.

func NewFromKcap

func NewFromKcap(handles []htypes.Handle) Snapshotter

NewFromKcap builds the handle snapshotter from kcap state.

func NewSnapshotter

func NewSnapshotter(config *config.Config, fn SnapshotBuildCompleted) Snapshotter

NewSnapshotter constructs a new instance of the handle snapshotter. If `SnapshotBuildCompleted` function is provided it will receive the total number of discovered handles as well as the count of the non-nameless handles.

type SnapshotterMock

type SnapshotterMock struct {
	mock.Mock
}

SnapshotterMock is the mock handle snapshotter used in tests.

func (*SnapshotterMock) FindByObject

func (s *SnapshotterMock) FindByObject(object uint64) (htypes.Handle, bool)

FindByObject method

func (*SnapshotterMock) FindHandles

func (s *SnapshotterMock) FindHandles(pid uint32) ([]htypes.Handle, error)

FindHandles method

func (*SnapshotterMock) GetSnapshot

func (s *SnapshotterMock) GetSnapshot() []htypes.Handle

GetSnapshot method

func (*SnapshotterMock) RegisterCreateCallback

func (s *SnapshotterMock) RegisterCreateCallback(fn CreateCallback)

RegisterCreateCallback method

func (*SnapshotterMock) RegisterDestroyCallback

func (s *SnapshotterMock) RegisterDestroyCallback(fn DestroyCallback)

RegisterDestroyCallback method

func (*SnapshotterMock) Remove

func (s *SnapshotterMock) Remove(kevt *kevent.Kevent) error

Remove method

func (*SnapshotterMock) Write

func (s *SnapshotterMock) Write(kevt *kevent.Kevent) error

Write method