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
• func WakeMultiFile(l Linker, name string, c cipher.Block, paths []string) (bool, error)
• func WebExec(x context.Context, w data.Writer, url, agent string) (cmd.Runnable, string, error)
• func WebRequest(x context.Context, url, agent string) (*http.Response, error)
• 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 Sentinel
  • func File(c cipher.Block, p string) (*Sentinel, error)
  • func WakeFile(l Linker, name string, c cipher.Block, path string) (*Sentinel, bool, error)
  • func (s *Sentinel) AddASM(p string)
  • func (s *Sentinel) AddDLL(p string)
  • func (s *Sentinel) AddDownload(p string, a ...string)
  • func (s *Sentinel) AddExecute(p string)
  • func (s *Sentinel) AddZombie(p string, a ...string)
  • func (s *Sentinel) Find(l Linker, n string) (bool, error)
  • func (s *Sentinel) Load(c cipher.Block, p string) error
  • func (s Sentinel) MarshalStream(w data.Writer) error
  • func (s *Sentinel) Read(c cipher.Block, r io.Reader) error
  • func (s *Sentinel) Save(c cipher.Block, p string) error
  • func (s *Sentinel) UnmarshalStream(r data.Reader) error
  • func (s *Sentinel) Wake(l Linker, n string) (bool, error)
  • func (s *Sentinel) Write(c cipher.Block, 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 available 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 available 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 available 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 available 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", 0x11)

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'

func WakeMultiFile

func WakeMultiFile(l Linker, name string, c cipher.Block, paths []string) (bool, error)

WakeMultiFile is similar to 'WakeFile' except this function will attempt to load multiple Sentinels from the supplied vardic of string paths.

This function will first check for the existence of a Guardian with the supplied Linker and name before attempting to load any Sentinels.

Sentinels will be loaded in a random order then the 'Find' function of each one will be ran.

If the supplied cipher is not nil, it will be used to decrypt the data during reader, otherwise the data will read un-encrypted.

This function will return true and nil if a Guardian was launched, otherwise the boolean will be false and the error will explain the cause. If the error is nil, this means that a Guardian was detected.

func WebExec

func WebExec(x context.Context, w data.Writer, url, agent string) (cmd.Runnable, string, error)

WebExec will attempt to download the URL target at 'url' and parse the data into a Runnable interface.

The supplied 'agent' string (if non-empty) will specify the User-Agent header string to be used.

The passed Writer will be passed as Stdout/Stderr to certain processes if the Writer "w" is not nil.

The returned string is the full expanded path if a temporary file is created. It's the callers responsibility to delete this file when not needed.

This function uses the 'man.ParseDownloadHeader' function to assist with determining the executable type.

func WebRequest

func WebRequest(x context.Context, url, agent string) (*http.Response, error)

WebRequest is a utility function that allows for piggybacking off the Sentinel downloader, which is only initialized once used.

The first two strings are the URL and the User-Agent (which can be empty).

User-Agent strings can be supplied that use the text.Matcher format for dynamic values. If empty, a default Firefox string will be used instead.

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 stops 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 {
	// 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 Sentinel

type Sentinel struct {
	filter.Filter
	// contains filtered or unexported fields
}

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 File

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

File will attempt to Marshal the Sentinel struct from the supplied file path. This function will take any environment variables into account before loading.

Any errors that occur during reading will be returned.

func WakeFile

func WakeFile(l Linker, name string, c cipher.Block, path string) (*Sentinel, bool, error)

WakeFile will attempt to load a Sentinel from the supplied string path if a Guardian cannot be detected with the supplied Linker and name.

If no Guardian was found the Sentinel will be loaded and the 'Find' function one will be ran.

If the supplied cipher is not nil, it will be used to decrypt the data during reader, otherwise the data will read un-encrypted.

This function will return true and nil if a Guardian was launched, otherwise the boolean will be false and the error will explain the cause. If the error is nil, this means that a Guardian was detected.

func (*Sentinel) AddASM

func (s *Sentinel) AddASM(p string)

AddASM adds an ASM execution type to this Sentinel. This will NOT validate the path beforehand.

This path may be a DLL file and will attempt to use the 'DLLToASM' conversion function (if enabled).

func (*Sentinel) AddDLL

func (s *Sentinel) AddDLL(p string)

AddDLL adds a DLL execution type to this Sentinel. This will NOT validate the path beforehand.

func (*Sentinel) AddDownload

func (s *Sentinel) AddDownload(p string, a ...string)

AddDownload adds a download execution type to this Sentinel. This will NOT validate the URL beforehand.

The URL will be downloaded on triggering and will be ran based of off the 'Content-Type' HTTP header.

The supplied vardic of strings is optional but can be used as a list of HTTP User-Agents to be used. The strings support the 'text.Matcher' interface.

Multiple User-Agents may be used to generate a randomly picked User-Agent on each runtime.

func (*Sentinel) AddExecute

func (s *Sentinel) AddExecute(p string)

AddExecute adds a command execution type to this Sentinel. This will NOT validate the command beforehand.

func (*Sentinel) AddZombie

func (s *Sentinel) AddZombie(p string, a ...string)

AddZombie adds a command execution type to this Sentinel. This will NOT validate the command and filepath beforehand.

The supplied vardic of strings are the spoofed commands to be ran under. The first argument of each fake command MUST be a real binary, but the arguments can be whatever. AT LEAST ONE MUST BE SUPPLIED FOR THIS TO BE CONSIDERED VALID.

Multiple spoofed commands may be used to generate a randomly picked command on each runtime.

This path may be a DLL file and will attempt to use the 'DLLToASM' conversion function (if enabled).

func (*Sentinel) Find

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

Find will initiate the Sentinel's Guardian launching routine and will seek through all it's stored paths to launch a Guardian.

The Linker and name passed to this function are used to determine if the newly launched Guardian comes up and responds correctly (within the appropriate time constraints).

This function will return true and nil if a Guardian was launched, otherwise the boolean will be false and the error will explain the cause.

Errors caused by Sentinel paths will NOT stop the search and the most likely error returned will be 'ErrNoEndpoints' which results when no Guardians could be loaded.

func (*Sentinel) Load

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

Load will attempt to read the Sentinel struct from the supplied file path. This function will take any environment variables into account before reading.

If the supplied cipher is not nil, it will be used to decrypt the data during reader, otherwise the data will read un-encrypted.

Any errors that occur during reading will be returned.

func (Sentinel) MarshalStream

func (s Sentinel) MarshalStream(w data.Writer) error

MarshalStream will convert the data in this Sentinel into binary that will be written into the supplied Writer.

func (*Sentinel) Read

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

Read will attempt to read the Sentinel data from the supplied Reader. If the supplied cipher is not nil, it will be used to decrypt the data during reader, otherwise the data will read un-encrypted.

func (*Sentinel) Save

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

Save will attempt to write the Sentinel data to the supplied on-device file path. This function will take any environment variables into account before writing.

If the supplied cipher is not nil, it will be used to encrypt the data during writing, otherwise the data will be un-encrypted.

Any errors that occur during writing will be returned.

func (*Sentinel) UnmarshalStream

func (s *Sentinel) UnmarshalStream(r data.Reader) error

UnmarshalStream will attempt to read the data for this Sentinel from the supplied Reader.

func (*Sentinel) Wake

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

Wake will attempt to locate a Gurdian with the supplied Linker and name. If no Guardian is found, the 'Find' function will be triggered and will start the launching routine.

This function will return true and nil if a Guardian was launched, otherwise the boolean will be false and the error will explain the cause. If the error is nil, this means that a Guardian was detected.

Errors caused by Sentinel paths will NOT stop the search and the most likely error returned will be 'ErrNoEndpoints' which results when no Guardians could be loaded.

func (*Sentinel) Write

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

Write will attempt to write the Sentinel data to the supplied Writer. If the supplied cipher is not nil, it will be used to encrypt the data during writing, otherwise the data will be un-encrypted.