Documentation ¶
Index ¶
- Constants
- Variables
- func Fork() (uint32, error)
- func ShellExecute(_ Verb, _ int32, _ string, _ ...string) error
- func Split(s string) []string
- type Code
- func (c Code) Error() error
- func (c Code) ExitCode() (int32, error)
- func (c Code) Handle() (uintptr, error)
- func (c *Code) Run() error
- func (c *Code) Running() bool
- func (*Code) SetParent(_ *Filter)
- func (*Code) Start() error
- func (*Code) Stop() error
- func (c Code) String() string
- func (c *Code) Wait() error
- type DLL
- type ExitError
- type Filter
- func (f *Filter) Clear() *Filter
- func (f Filter) MarshalStream(w data.Writer) error
- func (f Filter) Select() (uint32, error)
- func (Filter) SelectFunc(_ filter) (uint32, error)
- func (f *Filter) SetElevated(e bool) *Filter
- func (f *Filter) SetExclude(n ...string) *Filter
- func (f *Filter) SetFallback(i bool) *Filter
- func (f *Filter) SetInclude(n ...string) *Filter
- func (f *Filter) SetPID(p uint32) *Filter
- func (f *Filter) SetSession(s bool) *Filter
- func (f *Filter) UnmarshalStream(r data.Reader) error
- type Process
- func (p *Process) CombinedOutput() ([]byte, error)
- func (p Process) Error() error
- func (p Process) ExitCode() (int32, error)
- func (p Process) Flags() uint32
- func (Process) Handle() (uintptr, error)
- func (p *Process) Output() ([]byte, error)
- func (p Process) Pid() uint64
- func (p *Process) Run() error
- func (p *Process) Running() bool
- func (p *Process) SetChroot(s string)
- func (*Process) SetDetached(_ bool)
- func (p *Process) SetFlags(f uint32)
- func (*Process) SetFullscreen(_ bool)
- func (p *Process) SetGID(i int32)
- func (p *Process) SetInheritEnv(i bool)
- func (*Process) SetNewConsole(_ bool)
- func (*Process) SetNoWindow(_ bool)
- func (*Process) SetParent(_ *Filter)
- func (*Process) SetSuspended(_ bool)
- func (p *Process) SetUID(i int32)
- func (*Process) SetWindowDisplay(_ int)
- func (*Process) SetWindowPosition(_, _ uint32)
- func (*Process) SetWindowSize(_, _ uint32)
- func (*Process) SetWindowTitle(_ 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) String() string
- func (p *Process) Wait() error
- type Runnable
- type Verb
Constants ¶
const ( // True is the 'true' bool value. True = boolean(2) // False is the 'false' bool value. False = boolean(1) // Empty represents the absence of a value. Empty = boolean(0) )
const ( // VerbEdit launches an editor and opens the document for editing. If the target is not a document file, // the function will fail. VerbEdit = Verb("edit") // VerbFind initiates a search beginning in the directory specified by the working directory. VerbFind = Verb("find") // VerbOpen opens the item specified by the target parameter. The item can be a file or folder. VerbOpen = Verb("open") // VerbPrint prints the file specified by the target. If the target is not a document file, the function fails. VerbPrint = Verb("print") // VerbRunAs launches an application as Administrator. User Account Control (UAC) will prompt the user for consent to run // the application elevated or enter the credentials of an administrator account used to run the application. VerbRunAs = Verb("runas") //VerbExplore explores a folder specified by the target. VerbExplore = Verb("explore") )
Variables ¶
var ( // ErrEmptyCommand is an error returned when attempting to start a Process that has an empty 'Args' array. ErrEmptyCommand = xerr.New("process arguments are empty") // ErrNotCompleted is returned when attempting to access the exit code on a running process or wait on a // non-stared proess. ErrNotCompleted = xerr.New("the process has not yet completed or was not started") // ErrAlreadyStarted is an error returned by the 'Start' or 'Run' functions when attempting to start a process // that has already been started via a 'Start' or 'Run' function call. ErrAlreadyStarted = xerr.New("process has already been started") // ErrNoProcessFound is returned by the SetParent* functions on Windows devices when a specified parent process // could not be found. ErrNoProcessFound = xerr.New("could not find a suitable parent process") )
var RandomParent = &Filter{Fallback: false}
RandomParent is a Filter that can be used by default to select ANY random process on the target device to be used as the parent process without crteating a new Filter struct.
Functions ¶
func Fork ¶
Fork will attempt to use built-in system utilities to fork off the process into a separate, but similar process. If successful, this function will return the PID of the new process.
func ShellExecute ¶
ShellExecute calls the Windows ShellExecuteW API function. This will "preform an operation on the specified target" from the API documentation. The parameters include the Verb (required), Flags, Working Directory and Arguments. The first string specified in args is the value that will fill 'lpFile' and the rest will be filled into the 'lpArguments' parameter. Otherwise, if empty, they will both be nil. The error returned will be nil if the function call is successful. Always returns 'ErrNoWindows' if the device is not running Windows.
Types ¶
type Code ¶
Code 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 'ErrNotSupportedOS'. TODO: Add Linux shellcode execution support.
func NewCode ¶
NewCode creates a new Code thread instance that uses the supplied byte array as the Data buffer . Similar to '&Code{Data: b}'.
func NewCodeContext ¶
NewCodeContext 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 this Code thread.
func (Code) Error ¶
Error returns any errors that may have occurred during the Code thread operation.
func (Code) ExitCode ¶
ExitCode returns the Exit Code of the process. If the Code thread is still running or has not been started, this function returns an 'ErrNotCompleted' error.
func (Code) Handle ¶
Handle returns the handle of the current running Code thread. The return is a uintptr that can converted into a Handle. This function returns an error if the Code thread was not started. The handle is not expected to be valid after the Code thread exits or is terminated.
func (*Code) Run ¶
Run will start the Code 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 Code thread runtime.
func (*Code) SetParent ¶
SetParent will instruct the Code 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 (*Code) Start ¶
Start will attempt to start the Code thread and will return an errors that occur while starting the Code thread. This function will return 'ErrEmptyCommand' if the 'Data' parameter is empty or nil and 'ErrAlreadyStarted' if attempting to start a Code thread that already has been started previously. Always returns 'ErrNoWindows' on non-Windows devices.
func (*Code) Stop ¶
Stop will attempt to terminate the currently running Code thread instance. Always returns nil 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 Code struct, this struct can only be used on Windows devices and will return 'ErrNoWindows' on non-Windows devices.
func NewDLL ¶
NewDLL creates a new DLL instance that uses the supplied string as the DLL file path. Similar to '&DLL{Path: p}'.
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 this DLL.
func (DLL) ExitCode ¶
ExitCode returns the Exit Code of the process. If the DLL 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 DLL. The return is a uintptr that can converted into a Handle. This function returns an error if the DLL was not started. The handle is not expected to be valid after the DLL exits or is terminated.
func (*DLL) Run ¶
Run will start the DLL 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 DLL runtime.
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) 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 or nil and 'ErrAlreadyStarted' if attempting to start a DLL that already has been started previously. Always returns 'ErrNoWindows' on non-Windows devices.
func (*DLL) Stop ¶
Stop will attempt to terminate the currently running DLL instance. Always returns nil 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 Filter ¶
type Filter struct { // PID will attempt to select the PID to be used for the parent. // If set to zero, it will be ignored. Values of <5 are not valid! PID uint32 `json:"pid,omitempty"` // Fallback specifies if the opts routine should try again with less constaints // than the previous attempt. All attempts will still respect the 'Exclude' and // 'Ignore' directives. Fallback bool `json:"fallback,omitempty"` // Session can be set to 'True' or 'False' to attempt to target processes that // are either in or not in a DWM session environment (ie: in a user deskop [True] // or a service context [False]). This value is ignored if set to 'Empty'. Session boolean `json:"session,omitempty"` // Elevated can be set 'True' or 'False' to attempt to target processes that are // in a High/System or Lower integrity context. 'True' will attempt to select // elevated processes, while 'False' will select lower integrity or non-elevated // processes. If set to 'Empty' or omitted, this will be set based on the current // process's integrity level (ie: 'True' if device.Elevated == true else 'False'). Elevated boolean `json:"elevated,omitempty"` // Exclude and Include determine the processes that can be included or omitted during // process listing. 'Exclude' always takes precedence over 'Include'. Ether one being // nil or empty means no processes are included/excluded. All matches are case-insensitive. Exclude []string `json:"exclude,omitempty"` Include []string `json:"include,omitempty"` }
Filter is a struct that can be used to set the Parent process for many types of 'cmd.Runnable' compatable interfaces.
Each option can be set directly or chained using the function calls which all return the struct for chain usage.
This struct can be serialized into JSON or written using a Stream Marshaler.
func (*Filter) Clear ¶
Clear clears the Filter settings, except for 'Fallback' and return the Filter struct.
func (Filter) MarshalStream ¶
MarshalStream will attempt to write the Filter data to the supplied Writer and return any errors that may occur.
func (Filter) Select ¶
Select will attempt to find a process with the specified Filter options. If a suitable process is found, the Process ID will be returned. An 'ErrNoProcessFound' error will be returned if no processes that match the Filter match. This function returns 'ErrNoWindows' on non-Windows devices.
func (Filter) SelectFunc ¶
SelectFunc will attempt to find a process with the specified Filter options. If a suitable process is found, the Process ID will be returned. An 'ErrNoProcessFound' error will be returned if no processes that match the Filter match. This function returns 'ErrNoWindows' on non-Windows devices.
This function allows for a filtering function to be passed along that will be supplied with the ProcessID, if the process is elevated, the process handle and process name. The function supplied should return true if the process passes the filter. The function argument may be nil.
func (*Filter) SetElevated ¶
SetElevated sets the Elevated setting to 'True' or 'False' and returns the Filter struct.
func (*Filter) SetExclude ¶
SetExclude sets the Exclusion list and returns the Filter struct.
func (*Filter) SetFallback ¶
SetFallback sets the Fallback setting and returns the Filter struct.
func (*Filter) SetInclude ¶
SetInclude sets the Inclusion list and returns the Filter struct.
func (*Filter) SetSession ¶
SetSession sets the Session setting to 'True' or 'False' and returns the Filter struct.
type Process ¶
type Process struct { Stdin io.Reader Stdout, Stderr io.Writer Dir string Env, Args []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.
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 'ErrNotCompleted' 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) 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) SetChroot ¶
SetChroot will set the process Chroot directory at runtime. This function takes the directory path as a string value. Use an empty string "" to disable this setting. The specified Path value is validated at runtime. This function has no effect on Windows devices.
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) 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. This function has no effect 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). This function has no effect if the device is not running Windows. Setting the Parent process will automatically set 'SetNewConsole' to true.
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) 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. This function has no effect if the device is not running Windows. See the 'SW_*' values in winuser.h or the Golang windows package documentation for more details.
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. 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 or nil 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 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 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 Runnable ¶
type Runnable interface { Run() error Wait() error Stop() error Start() error Running() bool SetParent(*Filter) ExitCode() (int32, error) }
Runnable is an interface that helps support the type of structs that can be used for execution, such as Code and Process, which share the same methods as this interface.