device

package
v0.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2023 License: GPL-3.0 Imports: 22 Imported by: 3

Documentation

Overview

Package device contains many function that provide access to Operating System functions and resources. Many of these are OS agnostic and might not work as intended on some systems.

Index

Constants

View Source 
const (
	// EvadeWinPatchTrace is an evasion flag that instructs the client to patch
	// ETW tracing functions.
	EvadeWinPatchTrace uint8 = 1 << iota
	// EvadeWinPatchAmsi is an evasion flag that instructs the client to patch
	// Amsi detection functions.
	EvadeWinPatchAmsi
	// EvadeWinHideThreads is an evasion flag that instructs the client to hide
	// all of it's current threads from debuggers.
	EvadeWinHideThreads
	// EvadeEraseHeader is an evasion flag that instructs the client to hide it's
	// binary presense and prevent debugging by zeroing out it's PE stub in memory.
	// This should only be used if we /own/ and are the binary.
	EvadeEraseHeader
	// EvadeAll does exactly what it says, enables ALL Evasion functions.
	EvadeAll uint8 = 0xFF
)
View Source 
const (
	// IDSize is the amount of bytes used to store the Host ID and
	// SessionID values. The ID is the (HostID + SessionID).
	IDSize = 32
	// MachineIDSize is the amount of bytes that is used as the Host
	// specific ID value that does not change when on the same host.
	MachineIDSize = 28
)
View Source 
const (
	// Shell is the default machine specific command shell.
	Shell = "/bin/sh"
	// ShellArgs is the default machine specific command shell arguments to run
	// commands.
	ShellArgs = "-c"
	// PowerShell is the path to the PowerShell binary, which is based on the
	// underlying OS type.
	PowerShell = "pwsh"
)
View Source 
const Arch = arch.Current

Arch represents the current device Architecture type.

View Source 
const OS = Linux

OS is the local machine's Operating System type.

Variables

View Source 
var ErrNoWindows = xerr.Sub("only supported on Windows devices", 0x20)

ErrNoWindows is an error that is returned when a non-Windows device attempts a Windows specific function.

View Source 
var ErrQuit = xerr.Sub("quit", 0x1F)

ErrQuit is an error that can be returned from the DaemonFunction that will indicate a clean (non-error) break of the Daemon loop.

Functions

func Daemon added in v0.2.2 

func Daemon(_ string, f DaemonFunc) error

Daemon starts a "Service" (on Windows devices) and will run the function until interrupted. This function will block while running the function and can be interrupted via the Windows service control manager or SIGNALS (on Linux).

Any errors during runtime or returned from the functions will be returned.

NOTE: The 'name' argument is the service name on Windows, but is ignored on *nix systems.

func DaemonTicker added in v0.2.2 

func DaemonTicker(_ string, t time.Duration, f DaemonFunc) error

DaemonTicker starts a "Service" (on Windows devices) and will run the function every 't' duration until interrupted. This function will block while running and can be interrupted via the Windows service control manager or SIGNALS (on Linux).

Returning the error 'ErrQuit' will break the loop with a non-error.

Any errors during runtime or returned from the functions will be returned. Non-nil (non- ErrQuit) error returns will break the loop with an error.

NOTE: The 'name' argument is the service name on Windows, but is ignored on *nix systems.

func DumpProcess added in v0.2.2 

func DumpProcess(f *filter.Filter, w io.Writer) error

DumpProcess will attempt to copy the memory of the targeted Filter to the supplied Writer. This fill select the first process that matches the Filter.

If the Filter is nil or empty or if an error occurs during reading/writing an error will be returned.

This function may fail if attempting to dump a process that is a different CPU architecture that the host process.

func Evade added in v0.4.2 

func Evade(_ uint8) error

Evade will attempt to apply evasion techniques specified by the bitmask flag value supplied.

The flag values are in the form of 'Evade*' and are platform specific.

Any errors that occur during execution will stop the other evasion tasks scheduled in this function flags.

func Expand 

func Expand(s string) string

Expand attempts to determine environment variables from the current session and translate them from the supplied string.

This function supports both Windows (%var%) and *nix ($var or ${var}) variable substitutions.

func FreeOSMemory added in v0.3.0 

func FreeOSMemory()

FreeOSMemory forces a garbage collection followed by an attempt to return as much memory to the operating system as possible. (Even if this is not called, the runtime gradually returns memory to the operating system in a background task.)

On Windows, this function also calls 'SetProcessWorkingSetSizeEx(-1, -1, 0)' to force the OS to clear any free'd pages.

func GoExit added in v0.2.5 

func GoExit()

GoExit attempts to walk through the process threads and will forcefully kill all Golang based OS-Threads based on their starting address (which should be the same when starting from CGo).

This function can be used on binaries, shared libraries or Zombified processes.

Only works on Windows devices and is a wrapper for 'syscall.Exit(0)' for *nix devices.

DO NOT EXPECT ANYTHING (INCLUDING DEFERS) TO HAPPEN AFTER THIS FUNCTION.

func Impersonate added in v0.2.0 

func Impersonate(_ *filter.Filter) error

Impersonate attempts to steal the Token in use by the target process of the supplied filter.

This will set the permissions of all threads in use by the runtime. Once work has completed, it is recommended to call the 'RevertToSelf' function to revert the token changes.

Always returns 'ErrNoWindows' on non-Windows devices.

func ImpersonateUser added in v0.3.0 

func ImpersonateUser(_, _, _ string) error

ImpersonateUser attempts to log in with the supplied credentials and impersonate the logged in account.

This will set the permissions of all threads in use by the runtime. Once work has completed, it is recommended to call the 'RevertToSelf' function to revert the token changes.

This impersonation is locally based, similar to impersonating a Process token.

This also loads the user profile.

Always returns 'ErrNoWindows' on non-Windows devices.

func ImpersonateUserNetwork added in v0.4.2 

func ImpersonateUserNetwork(_, _, _ string) error

ImpersonateUserNetwork attempts to log in with the supplied credentials and impersonate the logged in account.

This will set the permissions of all threads in use by the runtime. Once work has completed, it is recommended to call the 'RevertToSelf' function to revert the token changes.

This impersonation is network based, unlike impersonating a Process token. (Windows-only).

Always returns 'ErrNoWindows' on non-Windows devices.

func IsDebugged added in v0.2.0 

func IsDebugged() bool

IsDebugged returns true if the current process is attached by a debugger.

func IsVirtual added in v0.5.1 

func IsVirtual() bool

IsVirtual attempts to determine if the underlying device is inside a container or is running in a virtual machine.

If this returns true, it is suspected that a non-physical device is present.

Different versions of this function are used depending on CPU type.

func Mounts added in v0.2.0 

func Mounts() ([]string, error)

Mounts attempts to get the mount points on the local device.

On Windows devices, this is the drive letters available, otherwise on nix* systems, this will be the mount points on the system.

The return result (if no errors occurred) will be a string list of all the mount points (or Windows drive letters).

func Proxy added in v0.2.0 

func Proxy(r *http.Request) (*url.URL, error)

Proxy returns the URL of the proxy to use for a given request, as indicated by the on-device settings.

Unix/Linux/BSD devices use the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes precedence over HTTP_PROXY for https requests.

Windows devices will query the Windows API and resolve the system setting values.

The environment values may be either a complete URL or a "host[:port]", in which case the "http" scheme is assumed. The schemes "http", "https", and "socks5" are supported. An error is returned if the value is a different form.

A nil URL and nil error are returned if no proxy is defined in the environment, or a proxy should not be used for the given request, as defined by NO_PROXY or ProxyBypass.

As a special case, if req.URL.Host is "localhost" (with or without a port number), then a nil URL and nil error will be returned.

NOTE(dij): I don't have handling of "<local>" (Windows specific) bypass 

rules in place. I would have to re-implement "httpproxy" code
and might not be worth it.

func RevertToSelf added in v0.2.0 

func RevertToSelf() error

RevertToSelf function terminates the impersonation of a client application. Returns an error if no impersonation is being done.

Always returns 'ErrNoWindows' on non-Windows devices.

func SetCritical added in v0.2.0 

func SetCritical(_ bool) (bool, error)

SetCritical will set the critical flag on the current process. This function requires administrative privileges and will attempt to get the "SeDebugPrivilege" first before running.

If successful, "critical" processes will BSOD the host when killed or will be prevented from running.

The boolean returned is the last Critical status. It's set to True if the process was already marked as critical.

Use this function with "false" to disable the critical flag.

NOTE: THIS MUST BE DISABLED ON PROCESS EXIT OTHERWISE THE HOST WILL BSOD!!!

Any errors when setting or obtaining privileges will be returned.

Always returns 'ErrNoWindows' on non-Windows devices.

func SetProcessName added in v0.2.2 

func SetProcessName(s string) error

SetProcessName will attempt to override the process name on *nix systems by overwriting the argv block. On Windows, this just overrides the command line arguments.

Linux support only allows for suppling a command line shorter the current command line.

Linux found here: https://stackoverflow.com/questions/14926020/setting-process-name-as-seen-by-ps-in-go

Always returns an EINVAL on WSAM/JS.

func UserHomeDir added in v0.5.1 

func UserHomeDir() string

UserHomeDir returns the current user's home directory.

On Unix, including macOS, it returns the $HOME environment variable. On Windows, it returns %USERPROFILE%. On Plan 9, it returns the $home environment variable. On JS/WASM it returns and empty string.

Golang compatibility helper function.

func Whoami added in v0.5.0 

func Whoami() (string, error)

Whoami returns the current user name. This function is different than the "local.Device.User" variable as this will be fresh everytime this is called, but also means that any API functions called will be re-done each call and are not cached.

If caching or multiple fast calls are needed, use the "local" package instead.

This function returns an error if determining the username results in an error.

Types

type Address added in v0.1.0 

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

Address represents an encoded IPv4 or IPv6 address.

The address struct was built on the great work from the great inet.af/netaddr package thanks and great work y'all!

GoDoc: https://pkg.go.dev/inet.af/netaddr

https://tailscale.com/blog/netaddr-new-ip-type-for-go/

func (Address) IP added in v0.1.0 

func (a Address) IP() net.IP

IP returns a 'net.IP' copy of this address.

This may be zero or empty depending on the type of address value this struct contains.

func (Address) Is4 added in v0.1.0 

func (a Address) Is4() bool

Is4 returns true if this struct represents an IPv4 based address or an IPv4 address wrapped in an IPv6 address.

func (Address) Is6 added in v0.1.0 

func (a Address) Is6() bool

Is6 returns true if this struct represents an IPv6 based address.

func (Address) IsBroadcast added in v0.1.0 

func (a Address) IsBroadcast() bool

IsBroadcast reports whether this is a broadcast address.

func (Address) IsGlobalUnicast added in v0.1.0 

func (a Address) IsGlobalUnicast() bool

IsGlobalUnicast reports whether this is a global unicast address.

The identification of global unicast addresses uses address type identification as defined in RFC 1122, RFC 4632 and RFC 4291 with the exception of IPv4 directed broadcast addresses.

It returns true even if this is in IPv4 private address space or local IPv6 unicast address space.

func (Address) IsLinkLocalMulticast added in v0.1.0 

func (a Address) IsLinkLocalMulticast() bool

IsLinkLocalMulticast reports whether this is a link-local multicast address.

func (Address) IsLinkLocalUnicast added in v0.1.0 

func (a Address) IsLinkLocalUnicast() bool

IsLinkLocalUnicast reports whether this is a link-local unicast address.

func (Address) IsLoopback added in v0.1.0 

func (a Address) IsLoopback() bool

IsLoopback reports whether this is a loopback address.

func (Address) IsMulticast added in v0.1.0 

func (a Address) IsMulticast() bool

IsMulticast reports whether this is a multicast address.

func (Address) IsUnspecified added in v0.1.0 

func (a Address) IsUnspecified() bool

IsUnspecified reports whether ip is an unspecified address, either the IPv4 address "0.0.0.0" or the IPv6 address "::".

func (Address) Len added in v0.1.0 

func (a Address) Len() int

Len returns the size of this IP address. It returns '32' for IPv4 and '128' for IPv6.

func (Address) MarshalJSON added in v0.1.0 

func (a Address) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Address) MarshalStream added in v0.1.0 

func (a Address) MarshalStream(w data.Writer) error

MarshalStream writes the data of this Address to the supplied Writer.

func (*Address) Set added in v0.1.0 

func (a *Address) Set(i net.IP)

Set will set the internal values of this address to the specified 'net.IP' address.

func (*Address) SetBytes added in v0.4.2 

func (a *Address) SetBytes(b [16]byte)

SetBytes will set the internal values of this address to the specified bytes contained in the byte array.

This function will attempt to detect zeros to determin if this is just a shortened IPv4 or IPv6 address.

func (Address) String added in v0.1.0 

func (a Address) String() string

String returns the string form of the IP address.

func (*Address) ToAddr added in v0.3.4 

func (a *Address) ToAddr() netip.Addr

ToAddr will return this Address as a netip.Addr struct. This will choose the type based on the underlying address size.

func (*Address) UnmarshalJSON added in v0.1.0 

func (a *Address) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Address) UnmarshalStream added in v0.1.0 

func (a *Address) UnmarshalStream(r data.Reader) error

UnmarshalStream reads the data of this Address from the supplied Reader.

type DaemonFunc added in v0.2.2 

type DaemonFunc func(context.Context) error

DaemonFunc is a function type that can be used as a Daemon. This function should return nil to indicate a successful run or ErrQuit to break out of a 'DaemonTicker' loop.

Any non-nil errors will be interpreted as exit code '1'.

type ID 

type ID [IDSize]byte

ID is an alias for a byte array that represents a 32 byte client identification number. This is used for tracking and detection purposes.

The first byte and the machine ID byte should NEVER be zero, otherwise it signals an invalid ID value or missing a random identifier.

func (ID) Empty 

func (i ID) Empty() bool

Empty returns true if this ID is considered empty.

func (ID) Full added in v0.1.0 

func (i ID) Full() string

Full returns the full string representation of this ID instance.

func (ID) Hash 

func (i ID) Hash() uint32

Hash returns the 32bit hash sum of this ID value. The hash mechanism used is similar to the hash/fnv mechanism.

func (*ID) Load 

func (i *ID) Load(s string) error

Load will attempt to load the Session UUID from the specified file. This function will return an error if the file cannot be read or not found.

func (ID) MarshalStream 

func (i ID) MarshalStream(w data.Writer) error

MarshalStream transform this struct into a binary format and writes to the supplied data.Writer.

func (*ID) Read 

func (i *ID) Read(r io.Reader) error

Read will attempt to read up to 'IDSize' bytes from the reader into this ID.

func (ID) Save 

func (i ID) Save(s string) error

Save will attempt to save the Session UUID to the specified file. This function will return an error if the file cannot be written to or created.

func (*ID) Seed 

func (i *ID) Seed(b []byte)

Seed will set the random portion of the ID value to the specified byte array value.

func (ID) Signature 

func (i ID) Signature() string

Signature returns the signature portion of the ID value. This value is constant and unique for each device.

func (ID) String 

func (i ID) String() string

String returns a representation of this ID instance.

func (*ID) UnmarshalStream 

func (i *ID) UnmarshalStream(r data.Reader) error

UnmarshalStream transforms this struct from a binary format that is read from the supplied data.Reader.

func (ID) Write 

func (i ID) Write(w io.Writer) error

Write will attempt to write the ID bytes into the supplied writer.

type Login added in v0.4.2 

type Login struct {
	Login     time.Time
	LastInput time.Time
	User      string
	Host      string
	From      Address
	ID        uint32
	Status    uint8
	// contains filtered or unexported fields
}

Login is a struct that represents a current user Session on the device.

func Logins added in v0.4.2 

func Logins() ([]Login, error)

Logins returns an array that contains information about current logged in users.

This call is OS-independent but many contain invalid session types.

Always returns an EINVAL on WSAM/JS.

func (Login) MarshalStream added in v0.4.2 

func (l Login) MarshalStream(w data.Writer) error

MarshalStream writes the data of this c to the supplied Writer.

func (Login) State added in v0.4.2 

func (l Login) State() string

State returns a string representation of the Login's Status type.

func (*Login) UnmarshalStream added in v0.4.2 

func (l *Login) UnmarshalStream(r data.Reader) error

UnmarshalStream reads the data of this Login from the supplied Reader.

type Machine 

type Machine struct {
	User     string
	Version  string
	Hostname string

	Network      Network
	PID, PPID    uint32
	Capabilities uint32

	ID       ID
	System   uint8
	Elevated uint8
}

Machine is a struct that contains information about a specific device. This struct contains generic Operating System Information such as Version, Arch and network information.

func (Machine) Arch 

func (m Machine) Arch() arch.Architecture

Arch returns the Machine's Architecture value. This value is gained by masking the OS bits of the 'System' value and returning the lower 4 bits.

func (Machine) IsDomainJoined added in v0.2.2 

func (m Machine) IsDomainJoined() bool

IsDomainJoined will return true if the domain joined flag is set to true on this device's 'Elevated' flags.

func (Machine) IsElevated added in v0.2.2 

func (m Machine) IsElevated() bool

IsElevated will return true if the elevated flag is set to true on this device's 'Elevated' flags.

func (Machine) MarshalStream 

func (m Machine) MarshalStream(w data.Writer) error

MarshalStream transforms this struct into a binary format and writes to the supplied data.Writer.

func (Machine) OS 

func (m Machine) OS() OSType

OS returns the Machine's OSType value. This value is gained by shifting the 'System' value by bits 4 to the right.

func (Machine) String 

func (m Machine) String() string

String returns a simple string representation of the Machine instance.

func (*Machine) UnmarshalStream 

func (m *Machine) UnmarshalStream(r data.Reader) error

UnmarshalStream transforms this struct from a binary format that is read from the supplied data.Reader.

type Network 

type Network []device

Network is a basic listing of network interfaces. Used to store and refresh interface lists.

func (Network) Len 

func (n Network) Len() int

Len returns the number of detected interfaces detected.

func (Network) MarshalStream 

func (n Network) MarshalStream(w data.Writer) error

MarshalStream writes the data of this Network to the supplied Writer.

func (*Network) Refresh 

func (n *Network) Refresh() error

Refresh collects the interfaces connected to this system and fills this Network object with the information.

If previous Network information is contained in this Network object, it is cleared before filling.

func (*Network) UnmarshalStream 

func (n *Network) UnmarshalStream(r data.Reader) error

UnmarshalStream reads the data of this Network from the supplied Reader.

type OSType added in v0.3.2 

type OSType uint8

OSType is a numerical representation of the device Operating System type. 

const (
	// Windows represents the Windows family of Operating Systems.
	Windows OSType = 0x0
	// Linux represents the Linux family of Operating Systems
	Linux OSType = 0x1
	// Unix represents the Unix/BSD family of Operating Systems
	Unix OSType = 0x2
	// Mac represents the macOS family of Operating Systems
	Mac OSType = 0x3
	// IOS represents the iOS family of Operating Systems
	// Technically is Mac, but deserves its own type for any special actions.
	IOS OSType = 0x4
	// Android represents the Android family of Operating Systems
	// Technically is Linux, but deserves its own type for any special actions.
	Android OSType = 0x5
	// Plan9 represents the Plan9 family of Operating Systems
	Plan9 OSType = 0x6
	// Unsupported represents a device type that does not have direct support
	// any may not work properly.
	Unsupported OSType = 0xF
)

func (OSType) String added in v0.3.2 

func (o OSType) String() string

String returns a string representation of the OSType.

Source Files

View all Source files

Directories

Path Synopsis
Package arch contains platform architecture constants and a specific type that correlates to the current system architecture.
 Package arch contains platform architecture constants and a specific type that correlates to the current system architecture.
Package local contains many functions and variables that contain information about the local device.
 Package local contains many functions and variables that contain information about the local device.
tags
Package tags enables identification of the build tags and capabilities that are compiled into the current program.
 Package tags enables identification of the build tags and capabilities that are compiled into the current program.
Package regedit is a helper package that allows easy access to the Windows registry on Windows systems and allows non-Windows systems to read data generated from registry entries.
 Package regedit is a helper package that allows easy access to the Windows registry on Windows systems and allows non-Windows systems to read data generated from registry entries.
Package screen is a helper package that contains generic functions that allow for taking ScreenShots of the current display (if supported).
 Package screen is a helper package that contains generic functions that allow for taking ScreenShots of the current display (if supported).
Package unix is a nix* specific package that assists with calling Unix/Linux/BSD specific functions and data gathering.
 Package unix is a nix* specific package that assists with calling Unix/Linux/BSD specific functions and data gathering.
Package winapi is a Windows specific package that assists with handeling or accessing many advanced WinAPI functions.
 Package winapi is a Windows specific package that assists with handeling or accessing many advanced WinAPI functions.
registry
Package registry contains code to handle common Windows registry operations.
 Package registry contains code to handle common Windows registry operations.
svc
Package svc is a Windows specific Service interface.
 Package svc is a Windows specific Service interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.