en-US/about_PSDetourSessions.help.txt
|
TOPIC
about_psdetoursessions SHORT DESCRIPTION As well as providing a mechanism to hook C function calls in PowerShell, PSDetour also provides a mechanism to provide remote hooking in other processes on the same system. This is done through embedding a PowerShell instance in the target process and exposes a normal PSRemoting session that can be used with `Enter-PSSession` or `Invoke-Command`. This feature is experimental and can have side effects in the target process. If done incorrectly, the hook can cause the process to crash. Note that creating a session in a process is an irreversible action. Once PowerShell has been loaded it will continue to run for the lifetime of the process and cannot be stopped. LONG DESCRIPTION A remote PSDetour session is split into 2 parts: * PowerShell injection into other process * PSRemoting through named pipes The PSRemoting component is a standard feature since PowerShell 5.1 and is simply the `PSHost` named pipe that every PowerShell process creates when it starts. This named pipe is used after PowerShell is injected to provide the remoting features that can be used with `Enter-PSSession` and `Invoke-Command`. PowerShell injection into non-PowerShell processes is the more complex component to PSDetour remoting. Included with this library is a basic x64 DLL that is remotely loaded into the target process. This DLL will create a new dotnet host that loads the PowerShell assembly and then starts the named pipe for use with PSRemoting. As this is an x64 compiled DLL, this can currently only be used with x64 processes. Further architectures will be available in the future. To create a PSDetour session, use the New-PSDetourSession cmdlet. This is a simple cmdlet that accepts either a process id, process object, or a process name (as long as there is only one process with that name). The output object is a `PSSession` object that can be used with any builtin cmdlet that uses the PSSession `-Session` parameter like `Invoke-Command` and `Enter-PSSession`. For example to start a PSDetour hook in notepad.exe, the process would look something like $session = New-PSDetourSession -ProcessId notepad Invoke-Command -Session $session -ScriptBlock { # The PSDetour module may need to be re-imported depending on where it is installed $hook = New-PSDetourHook -DllName Kernel32 -MethodName GetCurrentProcessId -Action { [OutputType([int])] param () $this.Invoke() } Start-PSDetour -Hook $hook ... code that waits until the hook needs to be stopped Stop-PSDetour } It can also be used interactively with `Enter-PSSession` which gives the caller more control over when the hooks start and stop. Once the session is no longer needed, use `Remove-PSSession` to close the connection. Remember that once a process has been tainted with PSDetour it will still continue to run the listener in the background until the process ends. Another option is to use `Trace-PSDetourProcess` to create a session in another process with a special state helper with the hooks. This special state object can be used to more easily send data back to the calling pipeline and provide more host interaction which might not be present when tracing other processes. The following code can be used to trace another process $hooks = New-PSDetourHook -DllName Kernel32 -MethodName GetCurrentProcessId -Action { [OutputType([int])] param () $this.State.WriteObject("object") $this.Invoke() } # Will block until the process has ended or the hook has called StopTrace. Trace-PSDetourProcess -ProcessId $otherProc -Hooks $hooks To stop a trace, press `ctrl+c`, or ensure one of your hooks sends the `StopTrace` signal. The `State` object set by `Trace-PSDetourProcess` has the following methods: * `GetFunction(string function)` * Gets the function scriptblock of the function name specified * These functions are populated by the `-FunctionsToDefine` parameter * `WriteDebug(string text)` * Writes a debug record * `WriteError(ErrorRecord errorRecord)` * Writes an error record * `WriteInformation(InformationRecord informationRecord)` * Writes an information record * `WriteObject(object sendToPipeline)` * Writes an object to the output pipeline with a depth of 1 * `WriteObject(object sendToPipeline, int depth)` * Writes an object to the output pipeline with a custom depth level * `WriteProgress(ProgressRecord progressRecord)` * Writes a progress record * `WriteVerbose(string text)` * Writes a verbose record * `WriteWarning(sting text)` * Writes a warning record * `WriteLine()` * Writes an empty line to the PSHost, i.e. `$host.UI.WriteLine()` * `WriteLine(string line, params string[] arg)` * Writes a line with optional format string args to the PSHost, i.e. `$host.UI.WriteLine('line')` * `ReadLine()` * Reads a line from the PSHost, i.e. `$host.UI.ReadLine()` * `ReadLine(string? prompt)` * Reads a line from the PSHost with a custom prompt * `StopTrace()` * Stops the current trace to unblock the caller |