man

package
v0.5.5 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2024 License: GPL-3.0 Imports: 27 Imported by: 4

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

View Source
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)
)
View Source
const (
	// Self is a constant that can be used to reference the current executable
	// path without using the 'os.Executable' function.
	Self = "*"
)

Variables

View Source
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 added in v0.2.0

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.2.0

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 added in v0.1.0

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 added in v0.1.0

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 added in v0.1.0

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 added in v0.1.0

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.3.4

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 added in v0.1.0

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 added in v0.1.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL