Documentation ¶
Index ¶
- Variables
- func DLLToASM(f string, b []byte) []byte
- func ResumeProcess(p uint32) error
- func Split(v string) []string
- func SuspendProcess(p uint32) error
- type Assembly
- func (a *Assembly) ExitCode() (int32, error)
- func (a *Assembly) Handle() (uintptr, error)
- func (a *Assembly) Location() (uintptr, error)
- func (Assembly) Pid() uint32
- func (a *Assembly) Release() error
- func (a *Assembly) Run() error
- func (a *Assembly) Running() bool
- func (Assembly) SetParent(_ *filter.Filter)
- func (a *Assembly) SetSuspended(s bool)
- func (Assembly) Start() error
- func (a *Assembly) Stop() error
- func (a *Assembly) Wait() error
- type DLL
- func (d *DLL) Done() <-chan struct{}
- func (d *DLL) ExitCode() (int32, error)
- func (d *DLL) Handle() (uintptr, error)
- func (DLL) Pid() uint32
- func (d *DLL) Release() error
- func (d *DLL) Run() error
- func (d *DLL) Running() bool
- func (DLL) SetParent(_ *filter.Filter)
- func (d *DLL) SetSuspended(s bool)
- func (DLL) Start() error
- func (d *DLL) Stop() error
- func (d *DLL) Wait() error
- type ExitError
- type Process
- func (p *Process) CombinedOutput() ([]byte, error)
- func (p *Process) ExitCode() (int32, error)
- func (p *Process) Flags() uint32
- func (p *Process) Handle() (uintptr, error)
- func (p *Process) Output() ([]byte, error)
- func (p *Process) Pid() uint32
- func (p *Process) Release() error
- func (p *Process) Resume() error
- func (p *Process) Run() error
- func (p *Process) Running() bool
- func (p *Process) SetDetached(d bool)
- func (p *Process) SetFlags(f uint32)
- func (p *Process) SetFullscreen(f bool)
- func (p *Process) SetGID(g int32)
- func (p *Process) SetInheritEnv(i bool)
- func (p *Process) SetLogin(u, d, pw string)
- func (p *Process) SetNewConsole(c bool)
- func (p *Process) SetNoWindow(h bool)
- func (p *Process) SetParent(f *filter.Filter)
- func (p *Process) SetSuspended(s bool)
- func (p *Process) SetToken(t uintptr)
- func (p *Process) SetUID(u int32)
- func (p *Process) SetWindowDisplay(m int)
- func (p *Process) SetWindowPosition(x, y uint32)
- func (p *Process) SetWindowSize(w, h uint32)
- func (p *Process) SetWindowTitle(s string)
- func (p *Process) Start() error
- func (p *Process) StderrPipe() (io.ReadCloser, error)
- func (p *Process) StdinPipe() (io.WriteCloser, error)
- func (p *Process) StdoutPipe() (io.ReadCloser, error)
- func (p *Process) Stop() error
- func (p *Process) Suspend() error
- func (p *Process) Wait() error
- type ProcessInfo
- type Runnable
- type Zombie
- func (z *Zombie) ExitCode() (int32, error)
- func (z *Zombie) Handle() (uintptr, error)
- func (z *Zombie) Location() (uintptr, error)
- func (z *Zombie) Resume() error
- func (z *Zombie) Run() error
- func (z *Zombie) Running() bool
- func (z *Zombie) SetSuspended(s bool)
- func (Zombie) Start() error
- func (z *Zombie) Stop() error
- func (z *Zombie) Suspend() error
- func (z *Zombie) Wait() error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotStarted is an error returned by multiple functions functions when // attempting to access a Runnable function that requires the Runnable to be // started first. ErrNotStarted = xerr.Sub("process has not been started", 0x63) // ErrEmptyCommand is an error returned when attempting to start a Runnable // that has empty arguments. ErrEmptyCommand = xerr.Sub("process arguments are empty", 0x64) // ErrStillRunning is returned when attempting to access the exit code on a // Runnable. ErrStillRunning = xerr.Sub("process is still running", 0x65) // ErrAlreadyStarted is an error returned by the 'Start' or 'Run' functions // when attempting to start a Runnable that has already been started via a // 'Start' or 'Run' function call. ErrAlreadyStarted = xerr.Sub("process has already been started", 0x66) )
Functions ¶
func DLLToASM ¶ added in v0.2.0
DLLToASM will patch the DLL raw bytes and convert it into shellcode using thE SRDi launcher.
SRDi GitHub: https://github.com/monoxgas/sRDI
The first string param is the function name which can be empty if not needed.
The resulting byte slice can be used in an 'Asm' struct to directly load and run the DLL.
func ResumeProcess ¶ added in v0.1.0
ResumeProcess will attempt to resume the process via it's PID. This will attempt to resume the process using an OS-dependent syscall.
This will not affect already running processes.
func Split ¶
Split will attempt to split the specified string based on the escape characters and spaces while attempting to preserve anything that is not a splitting space.
This will automatically detect quotes and backslashes. The return result is a string array that can be used as args.
func SuspendProcess ¶ added in v0.1.0
SuspendProcess will attempt to suspend the process via it's PID. This will attempt to suspend the process using an OS-dependent syscall.
This will not affect already suspended processes.
Types ¶
type Assembly ¶ added in v0.1.0
type Assembly struct { Data []byte Timeout time.Duration // contains filtered or unexported fields }
Assembly is a struct that can be used to contain and run shellcode on Windows devices. This struct has many of the functionallies of the standard 'cmd.Program' function.
The 'SetParent*' function will attempt to set the target that runs the shellcode. If none are specified, the shellcode will be injected into the current process.
This struct only works on Windows devices. All calls on non-Windows devices will return 'ErrNoWindows'.
TODO(dij): Add Linux shellcode execution support.
func NewAsm ¶ added in v0.1.0
NewAsm creates a new Assembly thread instance that uses the supplied byte array as the Data buffer. Similar to '&Assembly{Data: b}'.
func NewAsmContext ¶ added in v0.1.0
NewAsmContext creates a new Code thread instance that uses the supplied byte array as the Data buffer.
This function accepts a context that can be used to control the cancelation of the thread.
func (*Assembly) ExitCode ¶ added in v0.1.0
ExitCode returns the Exit Code of the thread. If the thread is still running or has not been started, this function returns an 'ErrNotCompleted' error.
func (*Assembly) Handle ¶ added in v0.1.0
Handle returns the handle of the current running thread. The return is a uintptr that can converted into a Handle.
This function returns an error if the thread was not started. The handle is not expected to be valid after the thread exits or is terminated.
func (*Assembly) Location ¶ added in v0.1.0
Location returns the in-memory Location of the current Assembly thread, if running. The return is a uintptr that can converted into a Handle.
This function returns an error if the Assembly thread was not started. The handle is not expected to be valid after the thread exits or is terminated.
func (Assembly) Pid ¶ added in v0.1.0
Pid retruns the process ID of the owning process (the process running the thread.)
This may return zero if the thread has not yet been started.
func (*Assembly) Release ¶ added in v0.2.0
Release will attempt to release the resources for this Assembly thread, including handles.
After the first call to this function, all other function calls will fail with errors. Repeated calls to this function return nil and are a NOP.
func (*Assembly) Run ¶ added in v0.1.0
Run will start the Assembly thread and wait until it completes. This function will return the same errors as the 'Start' function if they occur or the 'Wait' function if any errors occur during thread runtime.
Always returns nil on non-Windows devices.
func (*Assembly) Running ¶ added in v0.1.0
Running returns true if the current thread is running, false otherwise.
func (Assembly) SetParent ¶ added in v0.1.0
SetParent will instruct the Assembly thread to choose a parent with the supplied process Filter. If the Filter is nil this will use the current process (default).
This function has no effect if the device is not running Windows.
func (*Assembly) SetSuspended ¶ added in v0.1.0
SetSuspended will delay the execution of this thread and will put the thread in a suspended state until it is resumed using a Resume call.
This function has no effect if the device is not running Windows.
func (Assembly) Start ¶ added in v0.1.0
Start will attempt to start the Assembly thread and will return any errors that occur while starting the thread.
This function will return 'ErrEmptyCommand' if the 'Data' parameter is empty or the 'ErrAlreadyStarted' error if attempting to start a thread that already has been started previously.
Always returns 'ErrNoWindows' on non-Windows devices.
type DLL ¶
DLL is a struct that can be used to reflectively load a DLL into the memory of a selected process. Similar to the Assembly struct, this struct can only be used on Windows devices and will return 'ErrNoWindows' on non-Windows devices.
The 'SetParent*' function will attempt to set the target that loads the DLL. If none are specified, the DLL will be loaded into the current process.
func NewDLL ¶
NewDLL creates a new DLL instance that uses the supplied string as the DLL file path. Similar to '&DLL{Path: p}'.
func NewDLLBytes ¶ added in v0.1.0
NewDLLBytes creates a new DLL instance that uses the supplied raw bytes as the binary data to construct the DLL on disk to be executed.
NOTE(dij): This function does a write to disk. TODO(dij): In a future release, make this into a reflective loader.
Use 'NewAssembly(DLLtoASM(b))' func to bypass this.
func NewDLLBytesContext ¶ added in v0.1.0
NewDLLBytesContext creates a new DLL instance that uses the supplied raw bytes as the binary data to construct the DLL on disk to be executed.
NOTE(dij): This function does a write to disk. TODO(dij): In a future release, make this into a reflective loader.
This function accepts a context that can be used to control the cancelation of the thread.
func NewDllContext ¶
NewDllContext creates a new DLL instance that uses the supplied string as the DLL file path.
This function accepts a context that can be used to control the cancelation of the thread.
func (*DLL) Done ¶ added in v0.2.0
func (d *DLL) Done() <-chan struct{}
Done returns a channel that's closed when this DLL completes
This can be used to monitor a DLL's status using a select statement.
func (*DLL) ExitCode ¶
ExitCode returns the Exit Code of the thread. If the thread is still running or has not been started, this function returns an 'ErrNotCompleted' error.
func (*DLL) Handle ¶
Handle returns the handle of the current running thread. The return is a uintptr that can converted into a Handle.
This function returns an error if the thread was not started. The handle is not expected to be valid after the thread exits or is terminated.
func (DLL) Pid ¶ added in v0.1.0
Pid retruns the process ID of the owning process (the process running the thread.)
This may return zero if the thread has not yet been started.
func (*DLL) Release ¶ added in v0.2.0
Release will attempt to release the resources for this DLL instance, including handles.
After the first call to this function, all other function calls will fail with errors. Repeated calls to this function return nil and are a NOP.
func (*DLL) Run ¶
Run will start the DLL thread and wait until it completes. This function will return the same errors as the 'Start' function if they occur or the 'Wait' function if any errors occur during thread runtime.
Always returns nil on non-Windows devices.
func (DLL) SetParent ¶
SetParent will instruct the DLL to choose a parent with the supplied process Filter. If the Filter is nil this will use the current process (default).
This function has no effect if the device is not running Windows.
func (*DLL) SetSuspended ¶ added in v0.1.0
SetSuspended will delay the execution of this thread and will put the thread in a suspended state until it is resumed using a Resume call.
This function has no effect if the device is not running Windows.
func (DLL) Start ¶
Start will attempt to start the DLL and will return an errors that occur while starting the DLL.
This function will return 'ErrEmptyCommand' if the 'Path' parameter is empty and 'ErrAlreadyStarted' if attempting to start a DLL that already has been started previously.
Always returns 'ErrNoWindows' on non-Windows devices.
type ExitError ¶
type ExitError struct {
Exit uint32
}
ExitError is a type of error that is returned by the Wait and Run functions when a function returns an error code other than zero.
type Process ¶
type Process struct {
Stdout, Stderr io.Writer
Stdin io.Reader
Dir string
Args, Env []string
Timeout time.Duration
// contains filtered or unexported fields
}
Process is a struct that represents an executable command and allows for setting options in order change the operating functions.
func NewProcess ¶
NewProcess creates a new process instance that uses the supplied string vardict as the command line arguments. Similar to '&Process{Args: s}'.
func NewProcessContext ¶
NewProcessContext creates a new process instance that uses the supplied string vardict as the command line arguments.
This function accepts a context that can be used to control the cancelation of this process.
func (*Process) CombinedOutput ¶
CombinedOutput runs the Process and returns its combined standard output and standard error. Any returned error will usually be of type *ExitError.
func (*Process) ExitCode ¶
ExitCode returns the Exit Code of the process.
If the Process is still running or has not been started, this function returns an 'ErrStillRunning' error.
func (*Process) Handle ¶
Handle returns the handle of the current running Process. The return is a uintptr that can converted into a Handle.
This function returns an error if the Process was not started. The handle is not expected to be valid after the Process exits or is terminated.
This function always returns 'ErrNoWindows' on non-Windows devices.
func (*Process) Output ¶
Output runs the Process and returns its standard output. Any returned error will usually be of type *ExitError.
func (*Process) Pid ¶
Pid returns the current process PID. This function returns zero if the process has not been started.
func (*Process) Release ¶ added in v0.2.0
Release will attempt to release the resources for this Process, including handles.
After the first call to this function, all other function calls will fail with errors. Repeated calls to this function return nil and are a NOP.
func (*Process) Resume ¶ added in v0.1.0
Resume will attempt to resume this process. This will attempt to resume the process using an OS-dependent syscall.
This will not affect already running processes.
func (*Process) Run ¶
Run will start the process and wait until it completes.
This function will return the same errors as the 'Start' function if they occur or the 'Wait' function if any errors occur during Process runtime.
func (*Process) SetDetached ¶
SetDetached will detach or detach the console of the newly spawned process from the parent. This function has no effect on non-console commands. Setting this to true disables SetNewConsole.
This function has no effect if the device is not running Windows.
func (*Process) SetFlags ¶
SetFlags will set the startup Flag values used for Windows programs. This function overrites many of the 'Set*' functions.
func (*Process) SetFullscreen ¶
SetFullscreen will set the window fullscreen state of the newly spawned process. This function has no effect on commands that do not generate windows.
This function has no effect if the device is not running Windows.
func (*Process) SetGID ¶
SetGID will set the process GID at runtime. This function takes the numerical GID value. Use '-1' to disable this setting. The GID value is validated at runtime.
This function has no effect on Windows devices.
func (*Process) SetInheritEnv ¶
SetInheritEnv will change the behavior of the Environment variable inheritance on startup. If true (the default), the current Environment variables will be filled in, even if 'Env' is not empty.
If set to false, the current Environment variables will not be added into the Process's starting Environment.
func (*Process) SetLogin ¶ added in v0.3.0
SetLogin will set the User credentials that this Process will run under.
WARNING: This may cause issues when running with a parent process.
Currently only supported on Windows devices.
func (*Process) SetNewConsole ¶
SetNewConsole will allocate a new console for the newly spawned process. This console output will be independent of the parent process.
This function has no effect if the device is not running Windows.
func (*Process) SetNoWindow ¶
SetNoWindow will hide or show the window of the newly spawned process.
This function has no effect on commands that do not generate windows or if the device is not running Windows.
func (*Process) SetParent ¶
SetParent will instruct the Process to choose a parent with the supplied process Filter. If the Filter is nil this will use the current process (default). Setting the Parent process will automatically set 'SetNewConsole' to true
This function has no effect if the device is not running Windows.
func (*Process) SetSuspended ¶
SetSuspended will delay the execution of this Process and will put the process in a suspended state until it is resumed using a Resume call.
This function has no effect if the device is not running Windows.
func (*Process) SetToken ¶ added in v0.2.0
SetToken will set the User or Process Token handle that this Process will run under.
WARNING: This may cause issues when running with a parent process.
This function has no effect on commands that do not generate windows or if the device is not running Windows.
func (*Process) SetUID ¶
SetUID will set the process UID at runtime. This function takes the numerical UID value. Use '-1' to disable this setting. The UID value is validated at runtime.
This function has no effect on Windows devices.
func (*Process) SetWindowDisplay ¶
SetWindowDisplay will set the window display mode of the newly spawned process. This function has no effect on commands that do not generate windows.
See the 'SW_*' values in winuser.h or the Golang windows package documentation for more details.
This function has no effect if the device is not running Windows.
func (*Process) SetWindowPosition ¶
SetWindowPosition will set the window postion of the newly spawned process. This function has no effect on commands that do not generate windows.
This function has no effect if the device is not running Windows.
func (*Process) SetWindowSize ¶
SetWindowSize will set the window display size of the newly spawned process. This function has no effect on commands that do not generate windows.
This function has no effect if the device is not running Windows.
func (*Process) SetWindowTitle ¶
SetWindowTitle will set the title of the new spawned window to the the specified string. This function has no effect on commands that do not generate windows. Setting the value to an empty string will unset this setting.
This function has no effect if the device is not running Windows.
func (*Process) Start ¶
Start will attempt to start the Process and will return an errors that occur while starting the Process.
This function will return 'ErrEmptyCommand' if the 'Args' parameter is empty and 'ErrAlreadyStarted' if attempting to start a Process that already has been started previously.
func (*Process) StderrPipe ¶
func (p *Process) StderrPipe() (io.ReadCloser, error)
StderrPipe returns a pipe that will be connected to the Processes's standard error when the Processes starts.
The pipe will be closed after the Processe exits, so most callers need not close the pipe themselves. It is thus incorrect to call Wait before all reads from the pipe have completed. For the same reason, it is incorrect to use Run when using StderrPipe.
See the stdlib StdoutPipe example for idiomatic usage.
func (*Process) StdinPipe ¶
func (p *Process) StdinPipe() (io.WriteCloser, error)
StdinPipe returns a pipe that will be connected to the Processes's standard input when the Process starts. The pipe will be closed automatically after the Processes starts. A caller need only call Close to force the pipe to close sooner.
func (*Process) StdoutPipe ¶
func (p *Process) StdoutPipe() (io.ReadCloser, error)
StdoutPipe returns a pipe that will be connected to the Processes's standard output when the Processes starts.
The pipe will be closed after the Processe exits, so most callers need not close the pipe themselves. It is thus incorrect to call Wait before all reads from the pipe have completed. For the same reason, it is incorrect to use Run when using StderrPipe.
See the stdlib StdoutPipe example for idiomatic usage.
func (*Process) Stop ¶
Stop will attempt to terminate the currently running Process instance.
Stopping a Process may prevent the ability to read the Stdout/Stderr and any proper exit codes.
type ProcessInfo ¶ added in v0.2.2
ProcessInfo is a struct that holds simple process related data for extraction This struct is returned via a call to 'Processes'.
This struct also supports binary Marshaling/UnMarshaling.
func Processes ¶ added in v0.2.2
func Processes() ([]ProcessInfo, error)
Processes attempts to gather the current running Processes and returns them as a slice of ProcessInfo structs, otherwise any errors are returned.
func (ProcessInfo) MarshalStream ¶ added in v0.2.2
func (p ProcessInfo) MarshalStream(w data.Writer) error
MarshalStream transforms this struct into a binary format and writes to the supplied data.Writer.
func (*ProcessInfo) UnmarshalStream ¶ added in v0.2.2
func (p *ProcessInfo) UnmarshalStream(r data.Reader) error
UnmarshalStream transforms this struct from a binary format that is read from the supplied data.Reader.
type Runnable ¶
type Runnable interface { Run() error Pid() uint32 Wait() error Stop() error Start() error Running() bool Release() error Handle() (uintptr, error) ExitCode() (int32, error) SetParent(*filter.Filter) }
Runnable is an interface that helps support the type of structs that can be used for execution, such as Assembly, DLL and Process, which share the same methods as this interface.
type Zombie ¶ added in v0.1.0
Zombie is a struct that represents a Assembly backed process. This is simalar to 'execute-assembly' and will launch a suspended process to be injected into.
The 'Path' or 'Data' arguments can be used to specificy a DLL path or shellcode to be ran by the zombie. The 'Data' argument takes precedence over 'Path'. At least one of them must be supplied or an 'ErrEmptyCommand' error will be returned on any calls to 'Start'.
This struct shares many of the same methods as the 'Process' struct. The 'SetParent' function will affect the parent of the spawned process.
func NewZombie ¶ added in v0.1.0
NewZombie creates a Zombie struct that can be use to spawn a sacrificial process specified in the args vardict that will execute the shellcode in the byte array.
func NewZombieContext ¶ added in v0.1.0
NewZombieContext creates a Zombie struct that can be use to spawn a sacrificial process specified in the args vardict that will execute the shellcode in the byte array.
This function allows for specification of a Context for cancelation.
func (*Zombie) ExitCode ¶ added in v0.1.0
ExitCode returns the Exit Code of the Zombie thread. If the Zombie is still running or has not been started, this function returns an 'ErrStillRunning' error.
func (*Zombie) Handle ¶ added in v0.1.0
Handle returns the handle of the current running Zombie. The return is a uintptr that can converted into a Handle.
This function returns an error if the Zombie was not started. The handle is not expected to be valid after the Process exits or is terminated.
This function always returns 'ErrNoWindows' on non-Windows devices.
func (*Zombie) Location ¶ added in v0.1.0
Location returns the in-memory Location of the current Zombie thread, if running. The return is a uintptr that can converted into a Handle.
This function returns an error if the Zombie thread was not started. The handle is not expected to be valid after the thread exits or is terminated.
func (*Zombie) Resume ¶ added in v0.1.0
Resume will attempt to resume this process. This will attempt to resume the process using an OS-dependent syscall.
This will not affect already running processes.
func (*Zombie) Run ¶ added in v0.1.0
Run will start the Zombie and wait until it completes. This function will return the same errors as the 'Start' function if they occur or the 'Wait' function if any errors occur during Process runtime.
func (*Zombie) Running ¶ added in v0.1.0
Running returns true if the current Zombie is running, false otherwise.
func (*Zombie) SetSuspended ¶ added in v0.1.0
SetSuspended will delay the execution of this thread and will put the thread in a suspended state until it is resumed using a Resume call.
This function has no effect if the device is not running Windows.
func (Zombie) Start ¶ added in v0.1.0
Start will attempt to start the Zombie and will return an errors that occur while starting the Process.
This function will return 'ErrEmptyCommand' if the 'Args', the 'Data' or the 'Path; parameters are empty and 'ErrAlreadyStarted' if attempting to start a Zombie that already has been started previously.
Always returns 'ErrNoWindows' on non-Windows devices.
func (*Zombie) Stop ¶ added in v0.1.0
Stop will attempt to terminate the currently running Zombie instance. Stopping a Zombie may prevent the ability to read the Stdout/Stderr and any proper exit codes.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package evade is a package that contains functions that can be used to evade detection and disrupt defender tactics.
|
Package evade is a package that contains functions that can be used to evade detection and disrupt defender tactics. |
Package filter is a separate container for the 'Filter' struct that can be used to target a specific process or one that matches an attribute set.
|
Package filter is a separate container for the 'Filter' struct that can be used to target a specific process or one that matches an attribute set. |
Package script contains Script engines in separate packages to prevent loading if not needed/included.
|
Package script contains Script engines in separate packages to prevent loading if not needed/included. |