man

Documentation

Overview

Package man is the implementation of the Guardian and Sentinel structs. These can be used to guard against accidental launching of multiple processes and can determine if targets are 'alive'.

Windows clients have many options using built-in API calls, while other options such as TCP or Sockets (Named Pipes on Windows, UDS on *nix) to use generic control structs.

Sentinel is a struct that can be Marshaled/Unmashaled from a file or network stream with optional encryption capabilities. Sentinels can launch applications in may different ways, including downloading, injecting or directly executing.

Index

• Constants
• Variables
• func Check(l Linker, n string) bool
• func ParseDownloadHeader(h http.Header) uint8
• type Guardian
  • func Guard(l Linker, n string) (*Guardian, error)
  • func GuardContext(x context.Context, l Linker, n string) (*Guardian, error)
  • func MustGuard(l Linker, n string) *Guardian
  • func MustGuardContext(x context.Context, l Linker, n string) *Guardian
  • func (g *Guardian) Close() error
  • func (g *Guardian) Done() <-chan struct{}
  • func (g *Guardian) Wait()
• type Linker
  • func LinkerFromName(n string) Linker
• type Loader
  • func LazyC(c cipher.Block, p string) Loader
  • func LazyF(p string) Loader
• type Sentinel
  • func C(c cipher.Block, p string) *Sentinel
  • func Crypt(c cipher.Block, p string) (*Sentinel, error)
  • func CryptReader(c cipher.Block, r io.Reader) (*Sentinel, error)
  • func F(p string) *Sentinel
  • func File(p string) (*Sentinel, error)
  • func Reader(r io.Reader) (*Sentinel, error)
  • func (s Sentinel) Check(l Linker, n string) (bool, error)
  • func (s Sentinel) CheckContext(x context.Context, l Linker, n string) (bool, error)
  • func (s Sentinel) Crypt(c cipher.Block, w io.Writer) error
  • func (s Sentinel) CryptFile(c cipher.Block, p string) error
  • func (s Sentinel) File(p string) error
  • func (s Sentinel) Wake(n string) (bool, error)
  • func (s Sentinel) WakeContext(x context.Context, n string) (bool, error)
  • func (s Sentinel) Write(w io.Writer) error

Constants

const (
	// TCP is a Linker type that can be used with a Guardian.
	// This Linker uses raw TCP sockets to determine Guardian status.
	TCP = netSync(false)
	// Pipe is a Linker type that can be used with a Guardian.
	// This Linker uses Unix Domain Sockets in *nix devices and Named Pipes
	// in Windows devices.
	//
	// Pipe names are prefixed with the appropriate namespace before being
	// checked or created (if it doesn't exist already).
	//
	// This is the default Linker used if a nil Linker is used.
	Pipe = netSync(true)

	// Mutex is a Linker type that can be used with a Guardian.
	// This Linker uses Windows Mutexes to determine Guardian status.
	//
	// This Linker type is only avaliable on Windows devices.
	// non-Windows devices will always return a 'device.ErrNoWindows' error.
	Mutex = objSync(0)
	// Event is a Linker type that can be used with a Guardian.
	// This Linker uses Windows Events to determine Guardian status.
	//
	// This Linker type is only avaliable on Windows devices.
	// non-Windows devices will always return a 'device.ErrNoWindows' error.
	Event = objSync(1)
	// Semaphore is a Linker type that can be used with a Guardian.
	// This Linker uses Windows Semaphores to determine Guardian status.
	//
	// This Linker type is only avaliable on Windows devices.
	// non-Windows devices will always return a 'device.ErrNoWindows' error.
	Semaphore = objSync(2)
	// Mailslot is a Linker type that can be used with a Guardian.
	// This Linker uses Windows MailslotS to determine Guardian status.
	//
	// This Linker type is only avaliable on Windows devices.
	// non-Windows devices will always return a 'device.ErrNoWindows' error.
	Mailslot = objSync(3)
)

const (
	// Self is a constant that can be used to reference the current executable
	// path without using the 'os.Executable' function.
	Self = "*"
)

Variables

var ErrNoEndpoints = xerr.Sub("no paths found", 0x13)

ErrNoEndpoints is an error returned if no valid Guardian paths could be used and/or found during a launch.

Functions

func Check

func Check(l Linker, n string) bool

Check will attempt to contact any current Guardians watching on the supplied name. This function returns false if the specified name could not be reached or an error occurred.

This function defaults to the 'Pipe' Linker if a nil Linker is specified.

func ParseDownloadHeader

func ParseDownloadHeader(h http.Header) uint8

ParseDownloadHeader converts HTTP headers into index-based output types.

Resulting output types:

• 0: None found.
• 1: DLL.
• 2: Assembly Code (ASM).
• 3: Shell Script.
• 4: PowerShell Script.

Ignores '*/' prefix.

Examples

DLL:
   '/d'
   '/dll'
   '/dontcare'
   '/dynamic'
   '/dynamiclinklib'

Assembly Code:
   '/a'
   '/b'
   '/asm'
   '/bin'
   '/assembly'
   '/binary'
   '/code'
   '/shellcode'
   '/superscript'
   '/shutupbro'

Shell Script:
   '/x'
   '/s'
   '/cm'
   '/cmd'
   '/xgongiveittoya'
   '/xecute'
   '/xe'
   '/com'
   '/command'
   '/shell'
   '/sh'
   '/script'

PowerShell:
   '/p'
   '/pwsh'
   '/powershell'
   '/power'
   '/powerwash'
   '/powerwashing'
   '/powerwashingsimulator'
   '/pwn'
   '/pwnme'

Types

type Guardian

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

Guardian is a struct that is used to maintain a running process that will re-establish itself if it is not detected running.

Guardian instances use Linker interfaces to determine status.

func Guard

func Guard(l Linker, n string) (*Guardian, error)

Guard will attempt to create a Guardian instance on the provided name using the specified Linker.

This function will return an error if the name is already being listened on.

This function defaults to the 'Pipe' Linker if a nil Linker is specified.

func GuardContext

func GuardContext(x context.Context, l Linker, n string) (*Guardian, error)

GuardContext will attempt to create a Guardian instance on the provided name.

This function will return an error if the name is already being listened on.

This function will choose the proper connection method based on the host operating system.

This function also takes a context.Context to be used for resource control.

func MustGuard

func MustGuard(l Linker, n string) *Guardian

MustGuard returns a Guardian instance that watches on the name provided.

This function must complete and will panic if an error occurs. Otherwise a Guardian instance is returned.

This function defaults to the 'Pipe' Linker if a nil Linker is specified.

func MustGuardContext

func MustGuardContext(x context.Context, l Linker, n string) *Guardian

MustGuardContext returns a Guardian instance that watches on the name provided.

This function must complete and will panic if an error occurs. Otherwise a Guardian instance is returned.

This function also takes a context.Context to be used for resource control.

func (*Guardian) Close

func (g *Guardian) Close() error

Close will close the Guardian and stoppings the listener.

Any errors during listener close will be returned.

This function will block until the Guardian fully closes.

func (*Guardian) Done

func (g *Guardian) Done() <-chan struct{}

Done returns a channel that's closed when this Guardian is closed.

This can be used to monitor a Guardian's status using a select statement.

func (*Guardian) Wait

func (g *Guardian) Wait()

Wait will block until the Guardian is closed.

type Linker

type Linker interface {
	String() string
	// contains filtered or unexported methods
}

Linker us an interface that specifies an object that can be used to check for a Guardian instance.

func LinkerFromName

func LinkerFromName(n string) Linker

LinkerFromName will attempt to map the name provided to an appropriate Linker interface.

If no linker is found, the 'Pipe' Linker will be returned.

type Loader

type Loader interface {
	Wake(string) (bool, error)
	Check(Linker, string) (bool, error)
	WakeContext(context.Context, string) (bool, error)
	CheckContext(context.Context, Linker, string) (bool, error)
}

Loader is an interface that allows for Sentinel structs to be built ONLY AFTER a call to 'Check' returns false.

This prevents reading of any Sentinel files if the Guardian already is running and no action is needed.

This is an internal interface that can be used by the 'LazyF' and 'LazyC' functions.

func LazyC

func LazyC(c cipher.Block, p string) Loader

LazyC is a "Lazy" version of the 'C' function.

This function will ONLY load and read the file contents if the 'Check' result returns false.

This function can be used in-place of Sentinel structs in all functions.

func LazyF

func LazyF(p string) Loader

LazyF is a "Lazy" version of the 'F' function.

This function will ONLY load and read the file contents if the 'Check' result returns false.

This function can be used in-place of Sentinel structs in all functions.

type Sentinel

type Sentinel struct {
	Filter *filter.Filter
	Linker string
	Paths  []string
}

Sentinel is a struct that can be used as a 'Named' arguments value to functions in the 'man' package or can be Marshaled from a file or bytes source.

func C

func C(c cipher.Block, p string) *Sentinel

C is a helper function that can be used as an in-line function.

This function will ALWAYS return a non-nil Sentinel.

This function uses the provided 'cipher.Block' to decrypt the resulting file data. A nil block is the same as a 'F(p)' call.

The returned Sentinel will be Marshaled from the supplied Cipher and file path.

If any errors occur, an empty Sentinel struct will be returned instead.

func Crypt

func Crypt(c cipher.Block, p string) (*Sentinel, error)

Crypt will attempt to Marshal the Sentinel struct from the supplied file path and 'cipher.Block'.

If the Block is nil, this function will behave similar to 'File(p)'.

This function will also attempt to fill in the Filter and Linker parameters.

Any errors that occur during reading will be returned.

func CryptReader

func CryptReader(c cipher.Block, r io.Reader) (*Sentinel, error)

CryptReader will attempt to Marshal the Sentinel struct from the 'io.Reader' and the supplied 'cipher.Block'.

If the Block is nil, this function will behave similar to 'Reader(p)'.

This function will also attempt to fill in the Filter and Linker parameters.

Any errors that occur during reading will be returned.

func F

func F(p string) *Sentinel

F is a helper function that can be used as an in-line function.

This function will ALWAYS return a non-nil Sentinel.

The returned Sentinel will be Marshaled from the supplied file path. If any errors occur, an empty Sentinel struct will be returned instead.

func File

func File(p string) (*Sentinel, error)

File will attempt to Marshal the Sentinel struct from the supplied file path. This function will also attempt to fill in the Filter and Linker parameters.

Any errors that occur during reading will be returned.

func Reader

func Reader(r io.Reader) (*Sentinel, error)

Reader will attempt to Marshal the Sentinel struct from the 'io.Reader'

This function will also attempt to fill in the Filter and Linker parameters.

Any errors that occur during reading will be returned.

func (Sentinel) Check

func (s Sentinel) Check(l Linker, n string) (bool, error)

Check will attempt to look for a Guardian using the provided Linker and path. This overrides the set Linker in the Sentinel.

This function will return true and nil if a Guardian is launched and false and nil if a Guardian was found. Any other errors that occur will also be returned with false.

func (Sentinel) CheckContext

func (s Sentinel) CheckContext(x context.Context, l Linker, n string) (bool, error)

CheckContext will attempt to look for a Guardian using the provided Linker and path. This overrides the set Linker in the Sentinel and will use the provided Context for cancelation.

This function will return true and nil if a Guardian is launched and false and nil if a Guardian was found. Any other errors that occur will also be returned with false.

func (Sentinel) Crypt

func (s Sentinel) Crypt(c cipher.Block, w io.Writer) error

Crypt will Marshal and write the Sentinel data to the supplied Writer and will encrypt it using the supplied 'cipher.Block' with a randomized IV value.

If the Block is nil, this function is the same as 's.Write(w)'.

Any errors that occur during writing will be returned.

func (Sentinel) CryptFile

func (s Sentinel) CryptFile(c cipher.Block, p string) error

CryptFile will attempt to Marshal the Sentinel struct into the supplied file path and 'cipher.Block'.

If the Block is nil, this function will behave similar to 's.File(p)'.

This function will also attempt to fill in the Filter and Linker parameters.

Any errors that occur during reading will be returned.

This function will truncate and overrite any file that exists at 'p'.

func (Sentinel) File

func (s Sentinel) File(p string) error

File will attempt to Marshal the Sentinel struct into the supplied file path. Any errors that occur during reading will be returned.

This function will truncate and overrite any file that exists at 'p'.

func (Sentinel) Wake

func (s Sentinel) Wake(n string) (bool, error)

Wake will attempt to look for a Guardian using the provided path. This uses the set Linker in the Sentinel.

This function will return true and nil if a Guardian is launched and false and nil if a Guardian was found. Any other errors that occur will also be returned with false.

func (Sentinel) WakeContext

func (s Sentinel) WakeContext(x context.Context, n string) (bool, error)

WakeContext will attempt to look for a Guardian using the provided path. This uses the set Linker in the Sentinel and will use the provided Context for cancelation.

This function will return true and nil if a Guardian is launched and false and nil if a Guardian was found. Any other errors that occur will also be returned with false.

func (Sentinel) Write

func (s Sentinel) Write(w io.Writer) error

Write will Marshal and write the Sentinel data to the supplied Writer. Any errors that occur during writing will be returned.